Documentación de la API

Un único endpoint, autenticado con clave. Todas las respuestas son JSON.

Autenticación

Envíe su clave en el encabezado x-api-key en cada solicitud. Las claves ausentes, inválidas o revocadas reciben 401. Cree y revoque claves en el panel y guárdelas solo en su servidor.

x-api-key: cpf_live_••••••••••••••••

Endpoints

Hay dos caminos: la consulta rápida en nuestra base interna (solo CPF) y la consulta oficial (CPF + fecha de nacimiento). Ambos tienen versión por lotes, con hasta 1.000 CPF por solicitud. Todo CPF se higieniza (se quitan puntos y guiones) antes de la búsqueda.

Consulta en la base interna

El 404 de caché no es un error de CPF: solo significa que el registro aún no está en nuestra base. El cuerpo trae code: "CACHE_MISS". El dato en caché vale hasta 30 días.

curl https://api.brazid.com/v1/cpf/52998224725 \
  -H "x-api-key: $BRAZID_API_KEY"

Consulta por lotes

En el lote de la base interna la respuesta es inmediata. Los CPF repetidos cuentan una vez. Sin excedente, si el saldo no cubre todos los encontrados, toda la solicitud responde 402 y no se cobra nada.

curl -X POST https://api.brazid.com/v1/cpf/batch \
  -H "x-api-key: $BRAZID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "cpfs": ["529.982.247-25", "11144477735"] }'

{
  "success": true,
  "found": [
    {
      "cpf": "52998224725",
      "name": "MARIA SOUZA LIMA",
      "birthdate": "26/11/1982",
      "situation": "REGULAR"
    }
  ],
  "missing": [
    "11144477735"
  ],
  "invalid": [],
  "credits_remaining": 48
}

Cómo funciona el lote oficial

Lo que ya está en caché se responde al instante. El resto va a la fuente oficial en segundo plano, con concurrencia limitada. Los ítems inválidos, no encontrados y las fallas del proveedor no cobran, y usted puede reenviar solo los que fallaron. Los resultados quedan disponibles por 24 horas. Si tiene un webhook configurado, enviamos el evento batch.completed (sin datos personales) cuando el lote termina.

curl -X POST https://api.brazid.com/v1/cpf/batch/process \
  -H "x-api-key: $BRAZID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[{ "cpf": "529.982.247-25", "birthdate": "1982-11-26" }, { "cpf": "11144477735", "birthdate": "1990-05-02" }]'

{
  "success": true,
  "batch_id": "0c1e…",
  "status": "processing",
  "total": 2,
  "processed": 1,
  "status_url": "/v1/cpf/batch/0c1e…"
}

Consultar un CPF

Envíe cpf (con o sin puntuación) y birthdate (AAAA-MM-DD), ambos obligatorios. Los dos se sanean y validan antes de cualquier consulta; la fecha de nacimiento debe coincidir con la del titular, de lo contrario la respuesta es 404.

POST /v1/cpf

curl -X POST https://api.brazid.com/v1/cpf \
  -H "x-api-key: $BRAZID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "cpf": "529.982.247-25", "birthdate": "1982-11-26" }'

Respuesta

credits_remaining puede ocultarse en la configuración del panel. gender y deceased pueden ser null cuando la fuente no los informa.

{
  "success": true,
  "data": {
    "cpf": "52998224725",
    "name": "MARIA SOUZA LIMA",
    "birthdate": "26/11/1982",
    "day": 26,
    "month": 11,
    "year": 1982,
    "gender": "M",
    "deceased": false,
    "situation": "REGULAR"
  },
  "credits_remaining": 49
}

cpf

CPF saneado, 11 dígitos.

name

Nombre del titular, en mayúsculas.

birthdate

Fecha de nacimiento en formato DD/MM/AAAA. day, month y year traen las partes numéricas.

gender

M, F o null.

situation

Situación catastral en texto (ej.: REGULAR, TITULAR FALECIDO); null si la fuente no la informa.

deceased

true cuando la situación catastral indica fallecimiento; null si se desconoce.

credits_remaining

Saldo después de esta consulta (cuota mensual + créditos de bonificación).

Errores

Ninguna respuesta 4xx o 5xx consume crédito ni genera cobro de excedente.

Límites de solicitudes

Cada clave tiene un límite por segundo según el plan: 5 (Gratuito), 20 (Pro 200), 50 (Pro 1.000), 100 (Pro 5.000), 200+ (Corporativo). Las respuestas incluyen X-RateLimit-Limit, X-RateLimit-Remaining y, en caso de 429, Retry-After en segundos.

Webhooks de consumo

Registre una URL HTTPS en el panel para recibir el evento usage.threshold_reached cuando el consumo llegue al 80% y al 95% de la cuota. Cada envío incluye x-brazid-signature: t=<timestamp>,v1=<HMAC-SHA256 de "timestamp.cuerpo">, firmado con el secreto de su webhook.

{
  "type": "usage.threshold_reached",
  "threshold": 80,
  "used_percent": 80,
  "monthly_credits": 500,
  "auto_charge_enabled": true,
  "period_end": "2026-11-13T00:00:00.000Z"
}