Dossier de CPF

Crea un dossier de cumplimiento de una persona física: PEP, sanciones (CEIS y CNEP), expulsiones de la administración federal (CEAF), listas del TCU, trabajo esclavo, deuda activa de la Unión (PGFN) y sanciones internacionales. El procesamiento es asíncrono: la API responde 202 con un dossie_id y usted consulta el resultado con GET /v1/dossie/cpf/{id} o recibe un aviso en su callback_url.

Cuerpo de la solicitud

cpfstringobligatorio

CPF con o sin puntuación.

descriptionstringobligatorio

Finalidad de la consulta, de 1 a 200 caracteres. Ejemplo: "Prevención del lavado de dinero".

birthdatestringobligatorio

Fecha de nacimiento del titular, AAAA-MM-DD. La consulta cadastral es la misma de POST /v1/cpf y verifica CPF y nacimiento; si no coinciden, el dossier termina como failed (CPF_NOT_FOUND). No se devuelve ni se guarda.

callback_urlstring

URL HTTPS pública que recibe un aviso cuando el dossier termina. Sin IP, localhost ni puerto distinto de 443.

100 créditos por dossier concluido. Los dossiers fallidos no se cobran.

• La fecha de nacimiento es obligatoria, como en POST /v1/cpf; ausente o inválida responde 400. basic_info (nombre, situación cadastral y nacimiento) viene de la base de BrazID y, si el CPF aún no está en ella, se obtiene con la consulta cadastral estándar, sin costo extra. Si el CPF no existe o el nacimiento no coincide, el dossier termina como failed con el código CPF_NOT_FOUND y no se cobra nada.
• Privacidad (LGPD): el CPF completo, el nombre y el nacimiento se guardan por 30 días. Después se borran y el historial conserva el CPF enmascarado, la finalidad, el riesgo y los hallazgos. A pedido del titular el borrado es inmediato.
• Sin saldo para 100 créditos (y sin excedente), la respuesta es 402 y el dossier no comienza. Un CPF con formato inválido responde 400 y un dígito verificador inválido responde 422.
• Si alguna fuente no está disponible, el dossier termina con estado failed y no se cobra nada. Basta enviarlo de nuevo.
• Disponible en el sandbox. En producción el endpoint aún no fue liberado y responde 503 con el código DOSSIER_UNAVAILABLE.

Cómo se procesa el dossier

1. 1

   Usted envía el CPF y la finalidad

   La API valida los datos, verifica el saldo y responde 202 con el dossie_id y el estado pending. En este paso no se cobra nada.

2. 2

   Las fuentes se consultan en paralelo

   CGU (PEP, CEIS, CNEP y CEAF), TCU (inidóneos, inhabilitados, cuentas irregulares y fines electorales), el registro de trabajo esclavo, la deuda activa (PGFN) y las sanciones internacionales responden al mismo tiempo, en segundo plano. Las consultas que solo necesitan el CPF salen junto con la búsqueda catastral.

3. 3

   Usted hace el seguimiento

   Consulte GET /v1/dossie/cpf/{id} hasta que el estado sea completed o failed, o espere el aviso en su callback_url.

4. 4

   Se cobra una sola vez

   Los 100 créditos se debitan solo cuando todas las fuentes responden. El historial queda en su cuenta y puede consultarse en cualquier momento, sin costo adicional; los datos personales se borran tras 30 días.

Campos de la respuesta 202

successboolean

Siempre true cuando el dossier fue aceptado.

data.dossie_idstring

Identificador del dossier. Úselo para hacer el seguimiento.

data.statusstring

pending al crearlo. Después completed o failed.

data.created_atstring

Fecha y hora de creación, ISO 8601 (UTC).

data.queryobject

Lo que se consultó: cpf (solo dígitos) y description.

data.status_urlstring

Ruta para seguir el dossier. También viene en el encabezado Location.

credits_remainingnumber

Saldo actual. Aún no incluye los 100 créditos de este dossier. Puede ocultarse en el panel.

CPF de prueba en el sandbox

En el sandbox (api-sandbox.brazid.com) el dossier usa estos CPF, sin cobrar créditos. Cualquier otro CPF termina como failed con CPF_NOT_FOUND.

Aviso en callback_url

• Cuando el dossier termina, enviamos un POST con el evento dossie.completed o dossie.failed, el dossie_id, el estado y, si se concluyó, el risk_level.
• El aviso no lleva datos personales. Para leer el resultado, consulte GET /v1/dossie/cpf/{id}.
• Si tiene un webhook configurado en el panel, el cuerpo se firma en el encabezado x-brazid-signature, igual que los demás webhooks. Sin webhook configurado, el aviso va sin firma.
• Hasta 3 intentos seguidos si su servidor falla (5xx, 408, 429 o sin respuesta). No dependa solo del aviso: el GET sigue disponible.