Casos de uso

Como combinar as consultas do Análise 360 em fluxos práticos. Os fluxos abaixo usam apenas comportamentos descritos na documentação da API.

1. Análise de crédito na esteira (score + ações judiciais)

Objetivo: avaliar o risco de um cliente pessoa física no momento da aprovação de crédito, usando consultas diretas do módulo Restritivo.

Consulte o score de crédito

GET /score/v3/pf/credito/{cpf} com idFinalidade=2 (Ciclo de crédito). Use acoes=true para já considerar ações judiciais no cálculo.

Detalhe as ações, se necessário

GET /score/v3/pf/acoes/{cpf} para obter quantidade, valor total, tipo, fórum, vara, cidade e UF das ações.

Registre o protocolo

Guarde o protocolo retornado — ele pode ser reutilizado em consultas seguintes e serve para auditoria.

2. Recuperação de crédito (propensão a negociar)

Objetivo: priorizar quem cobrar, avaliando a propensão de um cliente em negociar ou quitar débitos pendentes.

Para pessoa física, chame GET /score/v3/pf/recupere/{cpf} com idFinalidade=2.
Para pessoa jurídica, chame GET /score/v3/pj/recupere/{cnpj} com idFinalidade=2.

A resposta apresenta classe de recuperação, faixa de propensão, pontuação e uma descrição da probabilidade de negociação.

Exemplo — score de recuperação PF

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

curl -X GET \
  "https://api.assertivasolucoes.com.br/score/v3/pf/recupere/12345678901?idFinalidade=2" \
  -H "Authorization: Bearer SEU_ACCESS_TOKEN"

const accessToken = process.env.ASSERTIVA_ACCESS_TOKEN;

const url = new URL("https://api.assertivasolucoes.com.br/score/v3/pf/recupere/12345678901");
url.searchParams.set("idFinalidade", "2");

const resposta = await fetch(url, {
  headers: { Authorization: `Bearer ${accessToken}` }
});
const dados = await resposta.json();
console.log(dados);

import os
import requests

access_token = os.environ["ASSERTIVA_ACCESS_TOKEN"]

resposta = requests.get(
    "https://api.assertivasolucoes.com.br/score/v3/pf/recupere/12345678901",
    headers={"Authorization": f"Bearer {access_token}"},
    params={"idFinalidade": 2},
)
resposta.raise_for_status()
print(resposta.json())

3. Visão completa do cliente (Análise Comportamental assíncrona)

Objetivo: obter uma visão 360 do cliente (vários módulos) em lote, recebendo o resultado por callback. Ideal quando você não precisa da resposta na hora.

Envie a lista de consultas

POST /credito/v1/pf (ou /credito/v1/pj) com um array de objetos. Cada item traz doc, idFinalidade, urlEntregaResultado e, opcionalmente, identificador e consultasAdicionais.

Guarde os identificadores

A resposta inicial confirma o recebimento e traz um uuid por consulta. Armazene o uuid e o identificador para conciliar depois.

Receba o resultado no callback

Após o processamento, a API faz um POST para a urlEntregaResultado com os dados de cada módulo. A URL deve aceitar POST e usar HTTPS.

Exemplo — envio da consulta comportamental PF

POST /credito/v1/pf

curl -X POST \
  "https://api.assertivasolucoes.com.br/credito/v1/pf" \
  -H "Authorization: Bearer SEU_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "urlEntregaResultado": "https://seu-sistema.com.br/webhooks/analise-360/pf",
      "identificador": "cliente-001",
      "doc": "12345678901",
      "idFinalidade": 2,
      "consultasAdicionais": ["veiculos"]
    }
  ]'

const accessToken = process.env.ASSERTIVA_ACCESS_TOKEN;

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

const resposta = await fetch("https://api.assertivasolucoes.com.br/credito/v1/pf", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${accessToken}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify(consultas)
});
const dados = await resposta.json();
console.log(dados);

import os
import requests

access_token = os.environ["ASSERTIVA_ACCESS_TOKEN"]

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

resposta = requests.post(
    "https://api.assertivasolucoes.com.br/credito/v1/pf",
    headers={"Authorization": f"Bearer {access_token}"},
    json=consultas,
)
resposta.raise_for_status()
print(resposta.json())

Regras do lote: o corpo deve ser um array não vazio, com até 200 consultas. Cada item precisa de uma urlEntregaResultado, um documento válido e a finalidade. Os módulos adicionais devem ser válidos e compatíveis com o tipo de consulta.

Boas práticas para o callback

Valide a estrutura da requisição recebida antes de processá-la.
Armazene o uuid e o protocolo.
Responda rapidamente e processe o conteúdo de forma assíncrona.
Implemente logs para rastrear falhas no recebimento.
Garanta que a URL utilize HTTPS.

4. Protestos com detalhamento assíncrono

Objetivo: tratar consultas que retornam protestos, cujo detalhamento pode chegar depois.

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 a quantidade de protestos, mas o detalhamento ainda está em processamento.

Quando protestoCompleto for false, refaça a consulta após alguns minutos usando o mesmo documento. Conforme a documentação do produto, essa reconsulta não gera cobrança adicional no mesmo dia. O campo erroProtestos indica se houve falha ao obter o detalhamento.

5. Evitando o erro 429 (consulta duplicada)

O código 429 ocorre quando já existe uma consulta semelhante em processamento para o mesmo usuário e documento nos últimos dois minutos.

Não envie a mesma consulta repetidamente.
Armazene o identificador da solicitação.
Aguarde o processamento antes de uma nova tentativa.
Controle as requisições no seu sistema para evitar duplicidade.

Recomendações

Boas práticas

Trate erros por módulo

Uma falha em um módulo (idError) não significa que os demais falharam. Avalie módulo a módulo.

Escolha a finalidade correta

Use a idFinalidade compatível com o tratamento realizado (2 ou 4) — exigência da LGPD.

Registre protocolo e uuid

Armazene protocolo e uuid das consultas para rastreabilidade e auditoria.

Renove o token

Considere o expires_in retornado e gere um novo token antes de chamadas após a expiração (401).