Instruções inicias - API Portal DEPS

• Aqui apresentamos algumas informações essenciais que lhe auxiarão na melhor compreensão de como consumir nossas APIs do Portal Deps
• Como temos alguns termos e funcionalidades que não são de sua familiaridade, reunimos aqui uma breve explicação deles para agilizar seu desenvolvimento
• Qualquer dúvida nosso time de atendimento poderá estar apoiando você através do e-mail [email protected]

Acesso ao Swagger com todas APIs disponíveis 🎯

• Swagger das APIs https://api-portal.deps.com.br/swagger/index.html (opens new window)
• ATENÇÃO: Observar para selecionar sempre a versão mais recente disponível das nossas APIs, tanto no Swagger como no consumo direto da URL;

Autenticação e segurança:

• Para consumir qualquer uma de nossas APIs é necessário a utilização de um token
• Ele é disponibilizado através da API de autenticação no endereço https://api-portal.deps.com.br/api/v3/conta/entrar (opens new window) utilizando seu usuário e senha
• Ponto de atenção: O usuário que fará o login na API deve ser cadastrado exclusivamente para este fim, pois assim não teremos problema com expiração e renovação de senhas e com isso ter problemas de comunicação com nossa API.
• Há um tempo que ele ficará válido e é retornado em um campo na medida de segundos. Hoje são de 18.000 segundos que convertendo são 5 horas. Podendo haver mudanças no futuro, então recomendamos pensar nessa hipótese.
• Nessa API também é retornado a relação de produtos que esse usuario tem permissão e contratado.

Inicialmente importante entender o diferencial entre nossos produtos e algumas funcionalidades associadas à eles:

• DepsMix: é nosso produto voltado a Dados, é uma consulta que lhe retorna blocos de dados na qual você pode utiliza-los para apoio em sua tomada de decisão.

• AQUI FALAMOS DE DIRECIONAR PARA OS LINKS DA DOC QUE TENHAM OS BLOCOS POSSIVEIS QUE RETORNAMOS E TAMBÉM NOSSO LAYOUT MESMO DE RETORNO EM JSON

• DepsSmart: é nosso produto com um diagnóstico de análise de crédito mais completo, nele além dos dados do DepsMix, você terá os dados passados por uma política de crédito, que irá resultar em um diagnóstico completo e uma sugestão de limite. Ela possui ainda funcionalidades opcionais extras, que faz possível automatizar seu processo;

• Funcionalidades essas como:

  • Parecer: A funcionalidade de Parecer, consiste em criar regras personalizadas para os dados que constam no relatório, e através dessas regras você terá um resultado de parecer atendido ou não, e o conjunto de pareceres atendidos ou reprovados irão influenciar no resultado final da análise do Parecer. O DepsSmart irá sugerir o limite independente de suas regras de parecer, porém no seu processo você pode ignorar o limite em caso do parecer não ser completamente atendido conforme você deseja. Obs.: O limite requisitado é uma função associada ao Parecer, na qual só funciona caso o Parecer esteja disponível em seu contrato com a Deps. Caso a função não estiver habilitada e o limite requisitado for enviado, ele será ignorado.

    • Regras Agrupadas: Outro ponto importante, algumas regras de parecer são na modalidade de regras agrupadas, pois os dados que o parecer irá validar além de estarem em uma lista também se deseja verificar mais de um dado de cada uma das linhas, como exemplo o quadro societário e participações, que pode possuir mais de um sócio ou participação, e pode haver necessidade de validar em conjunto o percentual de participação e a data de entrada por exemplo. Logo eu preciso validar essa combinação dos dois dados todos sócios, e basta algum não atender a regra que o parecer será reprovado. Na nossa API é retornada uma lista desses pareceres quando forem de uma regra agrupada onde fica possível fazer a validação de todos eles.

  • Centro de Custos: O centro de custos nada mais é do que rateio de valores de fatura. Serve para cenários onde por exemplo o cliente possui mais de uma empresa ou mesmo filial, e ele deseja saber o quanto gastou em cada uma delas e assim cada uma arcar com seu custo. Ele serve tanto para analistas separados por centro de custo, como para um analista que atenda dois ou mais centros de custos, basta definir em qual deles a consulta deve ser creditada. Na hora de verificar a sua fatura, será possível verificar os valores individuais por cada centro de custos. Caso não se deseje ratear os custos, não é necessário enviar esta informação no consumo. Caso sim, é necessário fazer o cadastro dos centros de custos dentro do portal, pegar o código do mesmo, e enviar em cada requisição de consulta que será feita na API

  • Fluxo de Consultas: O fluxo de consultas tem o intuito de otimizar a realização de consultas através da criação de faixas de valor de limite requisitado para definição de qual produto utilizar ao efetuar uma consulta. Com isso, ao consumir nossa API e ter o fluxo configurado, não será necessário informar o identificador do produto, pois o fluxo que irá definir qual produto utilizar de forma dinâmica.

• Identificador do Produto: É o código único (chave primária) que identifica o produto dentro do Portal Deps. Ele é retornado na API de login na lista de produtos que o usuário tem acesso, e também é mostrado na conta corrente pela interface web. Ele é necessário para consumo da API de consultas Deps.

Envio do seu Contas à Receber para utilização na análise do DepsSmart:

• Com o intuito de fazer uma análise de crédito e diagnóstico ainda mais preciso, você tem a opção de nos enviar o histórico de contas a receber que o seu cliente analisado tem com você, e assim utilizarmos esse comportamento também.
• Para isso utilizamos dois modelos, sendo o detalhado e o resumido. Ambos são utilizados pela análise, porém recomendamos sempre que escolha um ou outro, e adote esse padrão de envio à todas analises que serão feitas.
• O Resumido obviamente é mais performático e simples de enviar, já o detalhado um pouco mais complexo e pesado, porém ambos apresentam um bom resultado na sua análise.
• Para o contas a receber, vale ressaltar alguns pontos que merecem maior atenção:
  • O campo codigoTitulo do titulo é uma chave primária (única) dentro do nosso banco juntamente com seu ID de cliente, logo você precisa me garantir que o codigoTitulo que você irá enviar no título não irá repetir nunca mais em outro título que você venha a enviar. Porque digo isso: Pois podem haver combinações de cenario que precisam ser levados em consideração, como por exemplo se você for me enviar Contas a Receber de mais de um sistema, você pode ter o título 1 em ambos, porém são titulos diferentes, de clientes diferentes. Em um cenário desses eu preciso que você combine informações que garantam que esse título terá uma chave unica dentro do Portal Deps, como por exemplo 1A e 1B, sendo A o sistema X e o B o sistema Y por exemplo. Também pode haver cenário onde cada cliente pode ter seu titulo 1, logo preciso então que seja casada a informação de titulo e cliente no codigoTitulo que será enviado. Já o campo numeroTitulo você utilza para enviar o numero, codigo, identificador do titulo que é familiar para o seu usuário final, podendo se repetir, pois ele não é chave.
  • O campo tipoFiltro também tem sua complexidade de entendimento, por isso é bom menciona-lo aqui. Ele tem a função de informar qual tipo de data estão baseados os dados de CR que estão sendo enviados. Exemplo, se voce envia o tipoFiltro EMISSAO, eu entendo que todos titulos emitidos no periodo que você enviou nos campos Inicio e Fim estão vindo nesse envio, logo eu posso descartar todo o mesmo período que está no meu banco. O conceito é de fotografia, logo entendo que vocçê sempre me enviará a o estado atual completo daquele período. Se você me enviar tipoFiltro COMPLETO, eu entendo que posso descartar todo o CR desse cliente, e acatar o que você está me enviando agora. Se for por vencimento, então o que descarto é tudo com vencimento nesse período. E acato o que você está mandando agora.
  • Atenção: Caso uma dessas informações não seja bem entendida por quem construir esse envio, podemos ter problemas. O envio incorreto por exemplo de uma chave de título no campo codigoTitulo pode fazer com que dados de contas a receber sejam integrados ou modificados de forma equivocada. A informação de tipoFiltro também é imprescindível que seja feita de forma correta, pois ela influencia nos dados que o Portal irá descartar da base, logo precisa de atenção em seu entendimento.

Realização de consultas DepsMix via API:

• Consumir a API do Portal de Login/Token com método POST https://api-portal.deps.com.br/api/v3/conta/entrar (opens new window) com o login e senha do usuario

• Nessa API, serão retornados alem do Token e sua validade, também a relação de produtos que esse usuario e cliente tem disponíveis

• Deve-se buscar pelo produto desejado nessa lista, e pegar seu identificador, pois ele será necessario na segunda requisição que será feita para realizar a consulta de fato.

• Esse identificador também está disponível visualmente por dentro do Portal, através das movimentações do conta corrente, porém você vai precisar que já tenha sido feita alguma consulta do produto desejado para visualiza-lo.

• nessa lista também constará o nome do produto, e para qual tipo de pessoa ele é destinado, seja física ou juridica

• Para consumir a API de consulta, é necessário executar via método POST no endereço 'https://api-portal.deps.com.br/api/v3/consultas/depsmix (opens new window)'

• Nela, será necessário informar o documento desejado (CNPJ ou CPF), o identificador do Produto desejado, e o token de autenticação coletado na API de Login

• Também há a opção de informar um centro de custo no campo "codigoCentroCustos", caso o mesmo seja utilizado. O codigo a ser enviado está disponivel acessando o portal, no menu administração > centro de custo, campo identificador da lista de centros de custo.

• A opção "reutilizarDadosExistentes" não precisa ser enviada pois não está disponível para os produtos Mix;

• A opção "historicoConsultaId" serve para em caso de necessidade de buscar uma consulta de seu histórico. Para isso é preciso ter armazenado o Id do histórico que é devolvido ao fazer a consulta pela primeira vez;

• A opção "limiteRequisitado" não precisa ser enviada pois não está disponível para os produtos Mix;

• A opção "autorizacaoScr" é para produtos que terem essa informação em sua composição, onde caso tenha precisa definir se é necessário exigir a autorização antes ou não. Caso não tenha a informação se os produtos necessitam dessa opção, entrar em contato com nosso atendimento, e até ter a definição pode utilizar como false;

Realização de consultas DepsSmart via API:

• Consumir a API do Portal de Login/Token com método POST 'https://api-portal.deps.com.br/api/v3/conta/entrar (opens new window)' com o login e senha do usuario

• Nessa API, serão retornados alem do Token, também a relação de produtos que esse usuario e cliente tem disponíveis

• Deve-se buscar pelo produto MIX desejado nessa lista, e pegar seu identificador, pois ele será necessario na segunda requisição que será feita para realizar a consulta de fato.

• nessa lista também constará o nome do produto, e para qual tipo de pessoa ele é destinado, seja física ou juridica

• Caso ja se tenha o identificador, e dependendo da dinamica que irá ser construido o consumo, pode se manter fixo o identificador que será enviado sem necessidade de percorrer a lista retornada no login.

• Para consumir a API de consulta, é necessário executar via método POST no endereço 'https://api-portal.deps.com.br/api/v3/consultas/depsmix (opens new window)' (mesmo endereço utilizado na Mix, o que vai mudar é o produto, e os dados enviados que podem ter os adicionais)

• Nela, será necessário informar o documento desejado (CNPJ ou CPF), o identificador do Produto desejado, e o token de autenticação coletado na API de Login

• Também é solicitado se deve ser reaproveitado dados, onde esse parâmetro define se os dados da consulta devem ser reprocessados na análise. Caso enviado como false, ele irá apenas pegar a ultima consulta feita e trazer o resultado identico. Caso true, ele reprocessará os dados das métricas.

• Também pode ser enviado um limite requisitado, onde é utilizado para validar com o limite sugerido e os pareceres. Caso o requisitado seja menor ou igual ao sugerido e todos pareceres aprovados, o limite tbm será aprovado.

• Caso não, será recusado.

• Também há a opção de informar um centro de custo, caso o mesmo seja utilizado. O codigo a ser enviado está disponivel acessando o portal, no menu administração > centro de custo, campo identificador da lista de centros de custo.

##Resumindo algumas diferenças para ficar mais claro:

• DepsMix: Consulta voltada apenas a ter dados, ela espera você enviar documento, identificadorProduto e o token, nada mais;
• DepsSmart: Consulta com diagnóstico e processos, onde com ela além de dados há mais um conjunto de funcionalidades possíveis. Para isso ela espera além dos dados básicos, se deve ou nao reprocessar os dados, se deve utilizar o fluxo de consultas, e se há um limite requisitado.