Passar para o conteúdo principal

API Assertiva Análise 360

Escrito por Alex Bruno Machado

A API Assertiva Análise 360 permite consultar informações comportamentais, cadastrais, financeiras e restritivas de pessoas físicas e jurídicas.

O produto é dividido em dois módulos:

  • Análise Comportamental: apresenta uma visão ampliada do perfil do cliente, com informações cadastrais, socioeconômicas, financeiras e comportamentais.

  • Análise Restritiva: permite consultar scores, ações judiciais, protestos, cheques, dívidas e outros indicadores relacionados ao risco de crédito e à recuperação de valores.

A integração deve ser realizada por uma equipe técnica. A documentação completa está disponível na https://integracao.assertivasolucoes.com.br/v3/portal

1. URL base

As requisições devem ser realizadas no ambiente de produção utilizando a seguinte URL base:

https://api.assertivasolucoes.com.br

2. Autenticação

Para consumir a API, é necessário gerar um Bearer Token temporário utilizando as credenciais da aplicação:

  • Client ID

  • Secret

A geração do token utiliza o fluxo OAuth 2.0 client_credentials.

2.1 Endpoint para geração do token

Método: POST

URL:

https://api.assertivasolucoes.com.br/oauth2/v3/token

2.2 Configuração da requisição

Authorization

Configure a requisição utilizando:

  • Type: Basic Auth

  • Username: Client ID

  • Password: Secret

Body

Configure o corpo como:

  • Tipo: x-www-form-urlencoded

  • Chave: grant_type

  • Valor: client_credentials

Exemplo:

Chave

Valor

grant_type

client_credentials

2.3 Exemplo utilizando cURL

curl --request POST \ --url https://api.assertivasolucoes.com.br/oauth2/v3/token \ --user 'SEU_CLIENT_ID:SEU_SECRET' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data grant_type=client_credentials

2.4 Resposta esperada

Uma resposta bem-sucedida retorna um objeto semelhante a:

{ "access_token": "SEU_TOKEN_DE_ACESSO", "token_type": "bearer", "expires_in": 60, "scope": "ALL" }

O campo access_token deverá ser utilizado nas requisições da API.

2.5 Utilização do token

Envie o token no cabeçalho Authorization:

Authorization: Bearer SEU_TOKEN_DE_ACESSO

Atenção: o tempo de validade deve ser obtido pelo campo expires_in retornado na geração do token. A documentação operacional informa validade de 30 minutos, enquanto a especificação OAuth apresenta um exemplo com expires_in: 60. Portanto, a aplicação deve considerar o valor retornado pelo serviço como referência.

3. Finalidade de uso

As consultas que utilizam dados pessoais devem informar o parâmetro idFinalidade, conforme a finalidade real do tratamento dos dados.

Para o produto Análise 360, estão disponíveis as seguintes finalidades:

ID

Finalidade

Descrição

2

Ciclo de crédito

Utilização dos dados no ciclo de proteção ao crédito, incluindo cobrança, verificação da situação financeira e identificação correta.

4

Execução de contrato

Utilização dos dados para atualização, execução de contrato ou procedimentos preliminares relacionados ao contrato.

O parâmetro idFinalidade é obrigatório nos endpoints do módulo Análise Restritiva e nas consultas comportamentais.

4. Módulo Análise Comportamental

O módulo Análise Comportamental permite enviar consultas para processamento e receber os resultados posteriormente por meio de uma URL de callback.

As consultas são processadas de forma assíncrona:

  1. A aplicação envia uma lista de consultas.

  2. A API valida e registra as solicitações.

  3. A API retorna os identificadores das consultas criadas.

  4. Após o processamento, a API envia o resultado para a URL informada em urlEntregaResultado.

A URL de callback deve aceitar requisições POST.

4.1 Consulta comportamental de pessoa física

Método: POST

Endpoint:

https://api.assertivasolucoes.com.br/credito/v1/pf

Estrutura da requisição

A requisição deve conter um array de objetos. Cada objeto representa uma consulta de CPF.

Campo

Obrigatório

Descrição

urlEntregaResultado

Sim

URL que receberá o resultado da consulta por meio de um POST.

doc

Sim

CPF que será consultado.

idFinalidade

Sim

Finalidade de uso da consulta.

identificador

Não

Texto livre retornado junto com o resultado para facilitar a identificação da solicitação.

consultasAdicionais

Não

Lista de módulos adicionais solicitados. Esses módulos podem ter cobrança adicional.

Exemplo

[ { "urlEntregaResultado": "https://seu-sistema.com.br/webhooks/analise-360/pf", "identificador": "cliente-001", "doc": "12345678901", "idFinalidade": 2, "consultasAdicionais": [ "veiculos" ] } ]

Regras importantes

  • O corpo deve ser um array.

  • A lista não pode estar vazia.

  • A lista pode conter até 200 consultas.

  • Cada item deve conter uma URL de callback.

  • O CPF deve ser válido.

  • A finalidade deve ser informada.

  • Os módulos adicionais devem ser válidos.

  • O documento precisa ser compatível com o tipo de consulta.

4.2 Consulta comportamental de pessoa jurídica

Método: POST

Endpoint:

https://api.assertivasolucoes.com.br/credito/v1/pj

Estrutura da requisição

A requisição também deve conter um array de objetos.

Campo

Obrigatório

Descrição

urlEntregaResultado

Sim

URL que receberá o resultado da consulta por meio de um POST.

doc

Sim

CNPJ que será consultado.

idFinalidade

Sim

Finalidade de uso da consulta.

identificador

Não

Texto livre retornado junto com o resultado.

consultasAdicionais

Não

Lista de módulos adicionais solicitados. Esses módulos podem ter cobrança adicional.

Exemplo

[ { "urlEntregaResultado": "https://seu-sistema.com.br/webhooks/analise-360/pj", "identificador": "empresa-001", "doc": "01234567000189", "idFinalidade": 2, "consultasAdicionais": [ "veiculos" ] } ]

4.3 Resposta inicial das consultas comportamentais

A resposta inicial confirma o recebimento das solicitações e apresenta identificadores para acompanhamento.

Exemplo:

[ { "success": true, "body": [ { "doc": "12345678901", "uuid": "identificador-unico-da-consulta", "identificador": "cliente-001", "mensagem": "Consulta incluída com sucesso." } ] } ]

Os campos retornados podem incluir:

  • success: indica se a solicitação foi aceita.

  • doc: documento enviado.

  • uuid: identificador único da consulta.

  • identificador: valor informado pela aplicação.

  • mensagem: mensagem de processamento da solicitação.

4.4 Recebimento dos resultados

Após o processamento, a API envia uma requisição POST para a URL informada em urlEntregaResultado.

O resultado contém, normalmente:

  • Informações do cabeçalho da consulta;

  • Protocolo;

  • Documento pesquisado;

  • Finalidade utilizada;

  • Data e hora do processamento;

  • Indicador de reconsulta;

  • Módulos solicitados;

  • Dados retornados por cada módulo;

  • Eventuais códigos idError.

A aplicação deve disponibilizar uma rota pública ou acessível pela Assertiva para receber esses dados.

Boas práticas para o callback

  • Validar a estrutura da requisição recebida.

  • Armazenar o uuid e o protocolo.

  • Responder rapidamente à requisição.

  • Processar o conteúdo de forma assíncrona quando necessário.

  • Evitar executar operações demoradas antes de retornar uma confirmação.

  • Implementar logs para rastrear falhas no recebimento.

  • Garantir que a URL utilize HTTPS.

4.5 Módulos comportamentais disponíveis

O resultado da Análise Comportamental pode conter diferentes módulos, conforme o tipo de documento e as consultas solicitadas.

Pessoa física

Entre os módulos disponíveis estão:

  • Perfil socioeconômico;

  • Síntese cadastral;

  • Participações em empresas;

  • Ações judiciais;

  • Cheques;

  • Protestos;

  • Dívidas ativas na União;

  • Renda presumida;

  • Limite de crédito;

  • Restituição de Imposto de Renda;

  • Benefícios públicos;

  • Composição domiciliar;

  • Score;

  • Últimas consultas;

  • Veículos.

Pessoa jurídica

Entre os módulos disponíveis estão:

  • Síntese cadastral;

  • Participações em empresas;

  • Ações judiciais;

  • Cheques;

  • Protestos;

  • Dívidas ativas na União;

  • Limite de crédito;

  • Score;

  • Quadro societário;

  • Faturamento presumido;

  • Antifraude;

  • Últimas consultas;

  • Veículos;

  • Imóveis;

  • Concorrências;

  • Movimentações cadastrais;

  • Reputação em plataformas públicas.

A disponibilidade dos módulos depende das permissões e da configuração contratada para a empresa.

4.6 Códigos de erro dos módulos

Além dos códigos HTTP, cada módulo pode retornar a propriedade idError.

idError

Descrição

1

Informações não encontradas.

2

Saldo insuficiente para a consulta.

3

Documento não localizado.

4

Informações bloqueadas conforme as diretrizes da LGPD.

6

Problemas técnicos no processamento.

7

Score pôde ser calculado.

8

Score não pôde ser calculado.

9

Informações insuficientes.

10

Documento pertencente a pessoa publicamente exposta ou VIP.

11

Empresa sem presença ativa identificada no Google Meu Negócio.

13

Empresa sem presença ativa identificada no Reclame Aqui.

14

Problemas técnicos no processamento.

O tratamento do erro deve ser realizado por módulo. Uma falha em um módulo não significa necessariamente que todos os demais módulos da consulta falharam.

5. Módulo Análise Restritiva

O módulo Análise Restritiva disponibiliza consultas diretas, realizadas por meio de endpoints GET.

As consultas podem retornar dados imediatamente ou informar que o processamento ainda está em andamento, utilizando o status HTTP 202.

5.1 Ações judiciais de pessoa física

Consulta ações judiciais associadas a um CPF.

Método: GET

Endpoint:

https://api.assertivasolucoes.com.br/score/v3/pf/acoes/{cpf}

Parâmetros

Parâmetro

Localização

Obrigatório

Descrição

cpf

Path

Sim

CPF consultado.

idFinalidade

Query

Sim

Finalidade de uso da consulta.

protocolo

Query

Não

Protocolo de uma consulta anterior, quando aplicável.

Exemplo

GET https://api.assertivasolucoes.com.br/score/v3/pf/acoes/12345678901?idFinalidade=2

A resposta pode apresentar:

  • Data da ocorrência mais recente;

  • Quantidade de ações;

  • Valor total;

  • Tipo de ação;

  • Data;

  • Valor;

  • Fórum;

  • Vara;

  • Cidade;

  • UF.

5.2 Score de crédito de pessoa física

Consulta a propensão de uma pessoa física em honrar seus compromissos.

Método: GET

Endpoint:

https://api.assertivasolucoes.com.br/score/v3/pf/credito/{cpf}

Parâmetros

Parâmetro

Localização

Obrigatório

Descrição

cpf

Path

Sim

CPF consultado.

acoes

Query

Não

Define se a consulta deve considerar ações judiciais.

positivo

Query

Não

Define se o cálculo deve considerar informações do Cadastro Positivo.

idFinalidade

Query

Sim

Finalidade de uso da consulta.

protocolo

Query

Não

Protocolo de uma consulta anterior, quando aplicável.

Exemplo

GET https://api.assertivasolucoes.com.br/score/v3/pf/credito/12345678901?acoes=false&positivo=true&idFinalidade=2

A resposta pode incluir:

  • Classe de risco;

  • Faixa de risco;

  • Pontuação;

  • Cadastro Positivo;

  • Comprometimento de renda;

  • Relacionamento com cartão de crédito;

  • Atrasos recentes;

  • Protestos;

  • Registros de débitos;

  • Ações judiciais;

  • Cheques;

  • Renda presumida.

5.3 Score de recuperação de pessoa física

Indicado para avaliar a propensão de uma pessoa física em negociar ou quitar débitos pendentes.

Método: GET

Endpoint:

https://api.assertivasolucoes.com.br/score/v3/pf/recupere/{cpf}

Exemplo

GET https://api.assertivasolucoes.com.br/score/v3/pf/recupere/12345678901?idFinalidade=2

A resposta pode apresentar:

  • Classe de recuperação;

  • Faixa de propensão;

  • Pontuação;

  • Descrição da probabilidade de negociação.

5.4 Ações judiciais de pessoa jurídica

Consulta ações judiciais associadas a um CNPJ.

Método: GET

Endpoint:

https://api.assertivasolucoes.com.br/score/v3/pj/acoes/{cnpj}

Exemplo

GET https://api.assertivasolucoes.com.br/score/v3/pj/acoes/01234567000189?idFinalidade=2

A consulta pode retornar informações sobre:

  • Quantidade de ações;

  • Valor total;

  • Tipos de ação;

  • Datas;

  • Fóruns;

  • Varas;

  • Cidades;

  • Estados.

5.5 Score de crédito de pessoa jurídica

Consulta a propensão de uma empresa em honrar seus compromissos.

Método: GET

Endpoint:

https://api.assertivasolucoes.com.br/score/v3/pj/credito/{cnpj}

Parâmetros

Parâmetro

Localização

Obrigatório

Descrição

cnpj

Path

Sim

CNPJ consultado.

acoes

Query

Não

Define se a consulta deve considerar ações judiciais.

idFinalidade

Query

Sim

Finalidade de uso da consulta.

protocolo

Query

Não

Protocolo de uma consulta anterior, quando aplicável.

Exemplo

GET https://api.assertivasolucoes.com.br/score/v3/pj/credito/01234567000189?acoes=false&idFinalidade=2

A resposta pode conter:

  • Classe de risco;

  • Faixa de risco;

  • Pontuação;

  • Protestos;

  • Registros de débitos;

  • Últimas consultas;

  • Ações judiciais;

  • Cheques;

  • Faturamento presumido.

5.6 Score de recuperação de pessoa jurídica

Indicado para avaliar a propensão de uma empresa em negociar ou quitar débitos pendentes.

Método: GET

Endpoint:

https://api.assertivasolucoes.com.br/score/v3/pj/recupere/{cnpj}

Exemplo

GET https://api.assertivasolucoes.com.br/score/v3/pj/recupere/01234567000189?idFinalidade=2

A resposta pode apresentar:

  • Classe de recuperação;

  • Faixa de propensão;

  • Pontuação;

  • Descrição relacionada à possibilidade de negociação.

6. Protestos e processamento assíncrono

Nas consultas que retornam protestos, o resultado pode ser entregue de forma parcial enquanto o detalhamento ainda está sendo processado.

O campo protestoCompleto indica o status do detalhamento:

Valor

Significado

true

A consulta foi concluída e a lista detalhada de protestos foi retornada.

false

A API retornou inicialmente a quantidade de protestos, mas o detalhamento ainda está em processamento.

Quando protestoCompleto for false, a aplicação deverá realizar uma nova consulta após alguns minutos, utilizando o mesmo documento. Essa reconsulta não gera cobrança adicional no mesmo dia, conforme a documentação do produto.

Também pode ser retornado o campo erroProtestos:

  • true: ocorreu uma falha ao obter o detalhamento dos protestos.

  • false: não foi identificada falha no detalhamento.

7. Códigos de resposta HTTP

A API pode retornar os seguintes códigos:

Código

Significado

Tratamento recomendado

200

Consulta processada com sucesso.

Processar a resposta.

202

Consulta aceita, mas ainda em processamento ou sem dados exibíveis no momento.

Consultar o status ou realizar nova consulta conforme a regra do endpoint.

400

Documento ou parâmetros inválidos.

Validar CPF, CNPJ e parâmetros enviados.

401

Falha de autenticação.

Gerar ou enviar um token válido.

403

Usuário sem permissão.

Confirmar as permissões do produto e da operação.

404

Recurso ou informação não encontrado.

Validar o documento e o endpoint utilizado.

422

Dados válidos, mas incompatíveis com as regras de negócio.

Conferir os parâmetros e as condições da consulta.

429

Já existe uma consulta semelhante em andamento para o mesmo documento.

Aguardar e evitar o reenvio imediato.

500

Erro interno do servidor.

Tentar novamente e acionar o suporte se o erro persistir.

503

Instabilidade ou indisponibilidade de fornecedor.

Aguardar e repetir a consulta posteriormente.

504

Tempo limite excedido.

Repetir a requisição após validar a disponibilidade do serviço.

8. Tratamento do código 429

O código 429 pode ocorrer quando já existe uma consulta semelhante sendo processada para o mesmo usuário e documento nos últimos dois minutos.

Para evitar esse erro:

  • Não envie a mesma consulta repetidamente.

  • Armazene o identificador da solicitação.

  • Aguarde o processamento antes de realizar uma nova tentativa.

  • Consulte novamente apenas quando necessário.

  • Controle as requisições no sistema para evitar duplicidade.

9. Cuidados com dados pessoais

A API pode retornar dados pessoais e informações relacionadas a risco de crédito. Por isso, a integração deve observar os princípios da LGPD e as políticas de segurança da empresa.

Recomenda-se:

  • Utilizar uma finalidade compatível com o tratamento realizado.

  • Restringir o acesso aos dados por perfil de usuário.

  • Evitar armazenar informações além do período necessário.

  • Proteger tokens, credenciais e respostas da API.

  • Não expor dados pessoais em logs.

  • Utilizar HTTPS em todas as comunicações.

  • Registrar o protocolo das consultas para auditoria.

  • Implementar controles de acesso e rastreabilidade.

  • Não utilizar dados retornados para finalidades diferentes da informada.

10. Boas práticas de integração

  • Armazene o access_token de forma segura.

  • Nunca envie o Client ID e o Secret no front-end.

  • Utilize variáveis de ambiente ou um gerenciador de segredos.

  • Considere o valor de expires_in retornado pela API.

  • Renove o token antes de realizar chamadas após sua expiração.

  • Armazene o uuid e o protocolo das consultas.

  • Implemente tratamento para os códigos HTTP 401, 403, 429, 503 e 504.

  • Valide CPF e CNPJ antes do envio.

  • Controle consultas duplicadas.

  • Para Análise Comportamental, disponibilize uma URL de callback com HTTPS.

  • Responda rapidamente às notificações recebidas no callback.

  • Trate os erros individualmente por módulo.

  • Considere que alguns resultados podem ser processados de forma assíncrona.

  • Não interprete a ausência de dados como confirmação de inexistência sem avaliar o status da resposta.

11. Resumo dos endpoints

Módulo

Método

Endpoint

Geração de token

POST

/oauth2/v3/token

Análise Comportamental PF

POST

/credito/v1/pf

Análise Comportamental PJ

POST

/credito/v1/pj

Ações PF

GET

/score/v3/pf/acoes/{cpf}

Score de Crédito PF

GET

/score/v3/pf/credito/{cpf}

Score de Recuperação PF

GET

/score/v3/pf/recupere/{cpf}

Ações PJ

GET

/score/v3/pj/acoes/{cnpj}

Score de Crédito PJ

GET

/score/v3/pj/credito/{cnpj}

Score de Recuperação PJ

GET

/score/v3/pj/recupere/{cnpj}

12. Suporte

Em caso de dúvidas sobre a integração, permissões ou funcionamento da API, consulte a https://integracao.assertivasolucoes.com.br/v3/portal ou entre em contato pelo e-mail:

atendimento@assertivasolucoes.com.br

Respondeu à sua pergunta?