Primeira requisição

Este passo a passo leva você até o primeiro Dossiê gerado: solicitar o Dossiê PF, verificar o status e baixar o PDF.

Pré-requisitos

Credenciais

Ter suas credenciais de aplicação (Client ID e Secret).

Token de acesso

Ter gerado um token de acesso — veja Autenticação .

1. Solicite o Dossiê

POST /dossie/pf — solicita o Dossiê de uma pessoa física

Corpo da requisição (JSON):

Campo	Obrigatório	Descrição
`cpf`	sim	CPF a ser consultado, com ou sem máscara.
`idFinalidade`	sim	Finalidade de uso LGPD ( `2` — Ciclo de crédito).
`tipoConsulta`	não	`PRO` (padrão) ou `LITE` .
`idsModulosAdicionais`	não	Consultas adicionais. No PRO, `[2]` inclui Bens Veiculares.
`webhookUrl`	não	URL `https` que receberá as notificações de andamento.

Os valores abaixo são fictícios , apenas para ilustração. Use dados reais só em produção e conforme a finalidade declarada.

POST /dossie/pf

curl -X POST \
  "https://api.assertivasolucoes.com.br/dossie/pf" \
  -H "Authorization: Bearer SEU_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "cpf": "123.456.789-09",
    "idFinalidade": 2,
    "tipoConsulta": "PRO",
    "idsModulosAdicionais": [2],
    "webhookUrl": "https://seu-sistema.com.br/webhooks/dossie"
  }'

// Node 18+ possui fetch nativo.
const accessToken = process.env.ASSERTIVA_ACCESS_TOKEN;

const resposta = await fetch("https://api.assertivasolucoes.com.br/dossie/pf", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${accessToken}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    cpf: "123.456.789-09",
    idFinalidade: 2,
    tipoConsulta: "PRO",
    idsModulosAdicionais: [2],
    webhookUrl: "https://seu-sistema.com.br/webhooks/dossie"
  })
});
if (!resposta.ok) throw new Error(`Solicitação falhou: ${resposta.status}`);
const dados = await resposta.json();
// Verifique o idStatus: 11 = Em Fila (consulta aceita).
console.log(dados.body.protocol, dados.body.idStatus);

import os
import requests

access_token = os.environ["ASSERTIVA_ACCESS_TOKEN"]

resposta = requests.post(
    "https://api.assertivasolucoes.com.br/dossie/pf",
    headers={"Authorization": f"Bearer {access_token}"},
    json={
        "cpf": "123.456.789-09",
        "idFinalidade": 2,
        "tipoConsulta": "PRO",
        "idsModulosAdicionais": [2],
        "webhookUrl": "https://seu-sistema.com.br/webhooks/dossie",
    },
)
resposta.raise_for_status()
dados = resposta.json()
# Verifique o idStatus: 11 = Em Fila (consulta aceita).
print(dados["body"]["protocol"], dados["body"]["idStatus"])

Entenda a resposta

Uma solicitação aceita retorna 200 com:

body.protocol : identifica o dossiê. Guarde-o para baixar o PDF e correlacionar o webhook (campo protocolo ).
body.idStatus : 11 indica que a consulta foi aceita e está em fila.
body.message : descrição do status.

A API pode responder 200 e, mesmo assim, informar no idStatus que a consulta não pôde ser feita (por exemplo, 2 — Sem saldo, 4 — Bloqueado por LGPD). Só aguarde o resultado quando o idStatus for 11 .

2. Aguarde a conclusão

Se você informou webhookUrl , a Assertiva envia um POST para a sua URL quando o dossiê termina. Responda com qualquer status 2xx em até 10 segundos. Exemplo de notificação final:

{
  "protocolo": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "doc": "12345678901",
  "status": "SUCCESS"
}

Com módulos adicionais (como veículos), você recebe antes uma notificação CONSULTING , com PDF parcial. Considere o dossiê concluído apenas em SUCCESS ou PARTIAL_SUCCESS .

3. Baixe o PDF

GET /dossie/download/{protocolo} — PDF do dossiê

GET /dossie/download/{protocolo}

curl -X GET \
  "https://api.assertivasolucoes.com.br/dossie/download/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: Bearer SEU_ACCESS_TOKEN" \
  -o dossie.pdf

import { writeFile } from "node:fs/promises";

const accessToken = process.env.ASSERTIVA_ACCESS_TOKEN;
const protocolo = "a1b2c3d4-e5f6-7890-abcd-ef1234567890";

const resposta = await fetch(
  `https://api.assertivasolucoes.com.br/dossie/download/${protocolo}`,
  { headers: { Authorization: `Bearer ${accessToken}` } }
);
if (!resposta.ok) throw new Error(`Download falhou: ${resposta.status}`);
await writeFile("dossie.pdf", Buffer.from(await resposta.arrayBuffer()));

import os
import requests

access_token = os.environ["ASSERTIVA_ACCESS_TOKEN"]
protocolo = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"

resposta = requests.get(
    f"https://api.assertivasolucoes.com.br/dossie/download/{protocolo}",
    headers={"Authorization": f"Bearer {access_token}"},
)
resposta.raise_for_status()
with open("dossie.pdf", "wb") as arquivo:
    arquivo.write(resposta.content)

O PDF baixado após uma notificação CONSULTING é parcial e será substituído pela versão final. Baixe o PDF final após SUCCESS ou PARTIAL_SUCCESS .

Principais respostas de erro

Código	Significado	Tratamento recomendado
`400`	CPF não informado ou inválido, finalidade ausente/inválida, ou `webhookUrl` inválida.	Corrigir o campo indicado em `message` .
`401`	Falha na autenticação.	Verificar o cabeçalho `Authorization` , o formato `Bearer` e a validade do token.
`403`	Usuário sem permissão para a operação ou para o `tipoConsulta` .	Confirmar as permissões da aplicação e do produto.
`404`	Download: protocolo inválido, dossiê não encontrado, não concluído ou expurgado.	Conferir o protocolo e aguardar a notificação final.
`500`	Erro de servidor.	Repetir com retentativas controladas; acionar o suporte se persistir.

Próximo passo

Veja como tratar as notificações do webhook, os módulos adicionais e os status nos casos de uso .