Dossiê de CPF

Cria um dossiê de conformidade de uma pessoa física: PEP, sanções (CEIS e CNEP), expulsões da administração federal (CEAF), listas do TCU, trabalho escravo, dívida ativa da União (PGFN) e sanções internacionais. O processamento é assíncrono: a API responde 202 com um dossie_id e você consulta o resultado com GET /v1/dossie/cpf/{id} ou recebe um aviso no callback_url.

Corpo da requisição

cpfstringobrigatório

CPF com ou sem pontuação.

descriptionstringobrigatório

Finalidade da consulta, de 1 a 200 caracteres. Exemplo: "Prevenção à lavagem de dinheiro".

birthdatestringobrigatório

Data de nascimento do titular, AAAA-MM-DD. A consulta cadastral é a mesma de POST /v1/cpf e confere CPF e nascimento; se não bater, o dossiê termina como failed (CPF_NOT_FOUND). Ela não é devolvida nem guardada.

callback_urlstring

URL HTTPS pública que recebe um aviso quando o dossiê termina. Sem IP, localhost nem porta diferente de 443.

100 créditos por dossiê concluído. Dossiês com falha não cobram.

• A data de nascimento é obrigatória, como em POST /v1/cpf; ausente ou inválida responde 400. O basic_info (nome, situação cadastral e nascimento) vem da base da BrazID e, se o CPF ainda não estiver nela, é buscado na consulta cadastral padrão, sem custo extra. Se o CPF não existir ou o nascimento não conferir, o dossiê termina como failed com o código CPF_NOT_FOUND e nada é cobrado.
• Privacidade (LGPD): o CPF completo, o nome e o nascimento ficam guardados por 30 dias. Depois disso são apagados e o histórico segue com o CPF mascarado, a finalidade, o risco e os achados. A pedido do titular o apagamento é imediato.
• Sem saldo para 100 créditos (e sem excedente), a resposta é 402 e o dossiê não começa. CPF fora do formato responde 400 e dígito verificador inválido responde 422.
• Se alguma fonte estiver indisponível, o dossiê termina com status failed e nada é cobrado. Basta enviar de novo.
• Disponível no sandbox. Em produção o endpoint ainda não foi liberado e responde 503 com o código DOSSIER_UNAVAILABLE.

Como o dossiê é processado

1. 1

   Você envia o CPF, o nascimento e a finalidade

   A API valida os dados, confere o saldo e responde 202 com o dossie_id e o status pending. Nada é cobrado nessa etapa.

2. 2

   As fontes são consultadas em paralelo

   CGU (PEP, CEIS, CNEP e CEAF), TCU (inidôneos, inabilitados, contas irregulares e fins eleitorais), cadastro de trabalho escravo, dívida ativa (PGFN) e sanções internacionais respondem ao mesmo tempo, em segundo plano. As consultas que só precisam do CPF saem junto com a busca cadastral.

3. 3

   Você acompanha

   Consulte GET /v1/dossie/cpf/{id} até o status ser completed ou failed, ou aguarde o aviso no callback_url.

4. 4

   A cobrança acontece uma vez

   Os 100 créditos são debitados só quando todas as fontes respondem. O histórico fica na sua conta e pode ser consultado a qualquer momento, sem novo custo; os dados pessoais saem após 30 dias.

Campos da resposta 202

successboolean

Sempre true quando o dossiê foi aceito.

data.dossie_idstring

Identificador do dossiê. Use-o para acompanhar.

data.statusstring

pending na criação. Depois completed ou failed.

data.created_atstring

Data e hora de criação, em ISO 8601 (UTC).

data.queryobject

O que foi consultado: cpf (só dígitos) e description.

data.status_urlstring

Caminho para acompanhar o dossiê. Também vem no cabeçalho Location.

credits_remainingnumber

Saldo atual. Ainda não inclui os 100 créditos do dossiê. Pode ser ocultado no painel.

CPFs de teste no sandbox

No sandbox (api-sandbox.brazid.com) o dossiê usa estes CPFs, sem cobrar créditos. Envie o nascimento da tabela. Qualquer outro CPF, ou outra data, termina como failed com CPF_NOT_FOUND.

Aviso no callback_url

• Quando o dossiê termina, enviamos um POST com o evento dossie.completed ou dossie.failed, o dossie_id, o status e, se concluído, o risk_level.
• O aviso não leva dados pessoais. Para ler o resultado, consulte GET /v1/dossie/cpf/{id}.
• Se você tem um webhook configurado no painel, o corpo é assinado no cabeçalho x-brazid-signature, igual aos demais webhooks. Sem webhook configurado, o aviso vai sem assinatura.
• Até 3 tentativas seguidas se o seu servidor falhar (5xx, 408, 429 ou sem resposta). Não dependa só do aviso: o GET continua disponível.