API de Consulta de CPF en Brasil (2026) — Tutorial con Ejemplos de Código

Toda empresa que opera en Brasil necesita, en algún momento, verificar la identidad de sus clientes. El CPF — Cadastro de Pessoa Física, el número de identificación fiscal de las personas físicas en Brasil — es el documento clave para eso. Pero hay una diferencia enorme entre consultar CPF manualmente, uno por uno en el sitio de la Receita Federal (la autoridad tributaria federal de Brasil), y automatizar ese proceso vía API dentro de su sistema.

En este artículo vamos a explicar exactamente cómo funciona cada enfoque, por qué la consulta manual no escala y cómo integrar una API de consulta de CPF para automatizar validaciones de forma confiable. Si usted es desarrollador, CTO o lidera un equipo técnico que necesita implementar KYC, onboarding o prevención de fraudes, esta guía es para usted.

Qué es la consulta de CPF en la Receita Federal

El CPF es emitido y mantenido por la Receita Federal do Brasil (RFB). Cada número está vinculado a información registral como nombre completo, fecha de nacimiento y situación registral — que puede ser Regular, Pendiente de Regularización, Suspendida, Cancelada, Nula o Titular Fallecido.

La Receita ofrece una consulta pública en la dirección servicos.receita.fazenda.gov.br. El proceso es simple: usted informa el número del CPF, la fecha de nacimiento del titular, resuelve un captcha y recibe un comprobante de situación registral.

Esa consulta es gratuita y funciona bien para verificaciones puntuales — revisar la situación de su propio CPF antes de declarar el impuesto sobre la renta, por ejemplo. Pero cuando la necesidad es empresarial y recurrente, los problemas aparecen rápido.

Por qué la consulta manual no escala

En la práctica, quien intenta usar la consulta manual de la Receita Federal como parte de un proceso de negocio se topa con limitaciones estructurales.

Captcha obligatorio. Toda consulta exige resolver un captcha. Eso impide cualquier tipo de automatización directa y obliga a la intervención humana en cada verificación.

Una consulta a la vez. No hay funcionalidad de lote. Si usted necesita validar 200 CPF de nuevos registros en un día, son 200 accesos manuales al sitio, 200 captchas y 200 copias de resultados.

Sin integración con sistemas. El resultado es una página HTML — un comprobante visual. No existe un retorno estructurado (JSON, XML) que su sistema pueda procesar automáticamente para decidir si aprueba o rechaza un registro.

Sin disponibilidad garantizada. El sitio de la Receita no tiene SLA para uso externo. Puede estar caído, lento o devolviendo errores en horas pico sin ninguna previsibilidad.

Sin log ni trazabilidad. Cuando un analista hace la consulta manual, no queda un registro estandarizado. En caso de auditoría o disputa, reconstruir el historial de verificaciones es trabajoso y propenso a fallas.

Para cualquier operación que necesite validar más de un puñado de CPF por día — ya sea onboarding de clientes, análisis de crédito, emisión de facturas o prevención de fraudes — la consulta manual es un cuello de botella operativo.

Qué es la consulta de CPF por API

Una API de consulta de CPF hace, en esencia, la misma verificación que la consulta manual, pero de forma programática. Su sistema envía una solicitud HTTP con el número del CPF y recibe, en milisegundos, una respuesta estructurada con los datos registrales y la situación del documento.

La diferencia fundamental es que el proceso entero ocurre máquina a máquina, sin intervención humana, sin captcha y sin copiar y pegar datos entre pantallas.

Una llamada típica funciona así:

curl -H "X-API-Key: SUA_CHAVE" \
  "https://app.fontedata.com/api/v1/consulta/cadastro-rf-pf?cpf=12345678900"

Y la respuesta llega en JSON, con dos bloques principales — cadastro (datos enriquecidos) y receita (datos oficiales de la Receita Federal):

{
  "cadastro": {
    "cpf": "123.456.789-00",
    "nome": "Maria Silva Santos",
    "sexo": "Feminino",
    "dataNascimento": "15/06/1990 00:00:00",
    "nomeMae": "Ana Santos Lima",
    "idade": 35,
    "telefones": [
      {
        "telefoneComDDD": "11999887766",
        "operadora": "VIVO",
        "tipoTelefone": "CELULAR",
        "whatsApp": true
      }
    ],
    "enderecos": [
      {
        "logradouro": "R EXAMPLE",
        "numero": "100",
        "complemento": "AP 42",
        "bairro": "CENTRO",
        "cidade": "SAO PAULO",
        "uf": "SP",
        "cep": "01001-000"
      }
    ],
    "rendaEstimada": "8500.00",
    "rendaFaixaSalarial": "Faixa 5 a 8 salários mínimos"
  },
  "receita": {
    "numeroCPF": "123.456.789-00",
    "nomePessoaFisica": "MARIA SILVA SANTOS",
    "nomeSocial": null,
    "dataNascimento": "15/06/1990 00:00:00",
    "situacaoCadastral": "REGULAR",
    "dataInscricao": "10/03/2005 00:00:00",
    "digitoVerificador": "00",
    "dataEmissao": "06/01/2026 10:15:32",
    "codigoControleComprovante": "A1B2.C3D4.E5F6.G7H8",
    "possuiObito": false,
    "anoObito": null
  }
}

El bloque receita trae los datos oficiales de la Receita Federal — situación registral, fecha de inscripción, comprobante con código de control. El bloque cadastro enriquece con teléfonos, direcciones, ingresos estimados y otros datos útiles para KYC. Con ese retorno estructurado, su sistema puede tomar decisiones automáticamente: aprobar el registro si la situación es Regular, bloquearlo si está Suspendida o Cancelada, o derivarlo a revisión humana si hay divergencia en el nombre.

Validación del dígito verificador vs. consulta oficial: no las confunda

Un error común es creer que validar el CPF significa solamente comprobar que los dígitos verificadores sean correctos. El algoritmo mod-11 — ese cálculo matemático que verifica si los dos últimos dígitos del CPF tienen sentido — sirve para eliminar errores de tipeo. Responde a la pregunta "¿este número es matemáticamente posible?"

Pero no responde si el CPF existe de verdad, si está activo, si pertenece a la persona que lo informó, ni cuál es la situación registral actual. Los defraudadores generan CPF válidos según el mod-11 a escala — el cálculo es público y trivial de implementar.

La consulta vía API resuelve el segundo problema: va a la fuente oficial y confirma existencia y situación. En una buena arquitectura de validación, las dos etapas trabajan juntas.

En el front-end, use la validación del dígito verificador para dar feedback inmediato al usuario y frenar errores obvios de tipeo, sin costo y sin latencia. En el back-end, use la consulta vía API para confirmar en la fuente oficial antes de habilitar cualquier acción sensible como la creación de una cuenta, la aprobación de crédito o la activación de una billetera.

Casos de uso: dónde la consulta de CPF por API es indispensable

La validación de CPF por API no es un lujo técnico — es una necesidad operativa en diversos escenarios.

Onboarding y KYC (Know Your Customer). Fintechs, bancos digitales, exchanges de criptomonedas y plataformas de pago necesitan verificar la identidad de cada cliente antes de habilitar operaciones financieras. La consulta de CPF es la primera capa de ese proceso. Si el CPF es inválido, inexistente o irregular, no tiene sentido avanzar a etapas más caras como la verificación biométrica o el análisis de crédito.

Prevención de fraudes en e-commerce. Validar el CPF en el checkout reduce significativamente los registros falsos y los chargebacks. Un CPF con situación Cancelada o Nula usado para una compra es una señal clara de intento de fraude.

Emisión de facturas. Para emitir una NF-e (la factura electrónica brasileña), el CPF del destinatario debe estar correcto y activo. Consultar antes de emitir evita el rechazo por parte de la SEFAZ (la administración tributaria estatal) y el retrabajo del equipo fiscal.

Registro de conductores y prestadores de servicios. Las plataformas de movilidad y los marketplaces de servicios necesitan validar la identidad de sus socios antes de activarlos. La consulta de CPF es el paso inicial para garantizar que la persona existe y está regular.

Análisis de crédito. Antes de correr un score o consultar burós de crédito (Serasa, Boa Vista), tiene sentido verificar si el CPF está regular. Si la situación registral ya es impeditiva, el pipeline de crédito puede cortarse antes de generar costos con consultas más caras.

Compliance regulatorio. Las empresas de sectores regulados — financiero, salud, seguros — necesitan demostrar en auditoría que verificaron la identidad de sus clientes. La consulta vía API genera logs estructurados que sirven como evidencia.

Cómo integrar: ejemplo práctico con la API de FonteData

FonteData agrega más de 100 fuentes de datos en una API unificada. Eso significa que, con la misma integración, usted consulta CPF, CNPJ (el registro fiscal de las empresas en Brasil), KYC y varias otras bases — sin tener que mantener múltiples contratos e integraciones con proveedores distintos.

1. Cree su cuenta y obtenga una API key

Acceda a fontedata.com y cree su cuenta en menos de 30 segundos. Usted recibe R$50 en créditos gratuitos (reales brasileños) para probar, sin tarjeta de crédito. Su API key queda disponible de inmediato en el dashboard.

2. Haga su primera consulta

Con la API key en mano, la consulta es un único request:

cURL:

curl -H "X-API-Key: fd_live_sua_chave_aqui" \
  "https://app.fontedata.com/api/v1/consulta/cadastro-rf-pf?cpf=12345678900"

Python:

import requests

response = requests.get(
    "https://app.fontedata.com/api/v1/consulta/cadastro-rf-pf",
    params={"cpf": "12345678900"},
    headers={"X-API-Key": "fd_live_sua_chave_aqui"}
)

dados = response.json()
receita = dados["receita"]

if receita["situacaoCadastral"] == "REGULAR":
    print(f"CPF válido — titular: {receita['nomePessoaFisica']}")
else:
    print(f"CPF com situação: {receita['situacaoCadastral']}")

Node.js:

const response = await fetch(
  "https://app.fontedata.com/api/v1/consulta/cadastro-rf-pf?cpf=12345678900",
  {
    headers: { "X-API-Key": "fd_live_sua_chave_aqui" }
  }
);

const dados = await response.json();
const receita = dados.receita;

if (receita.situacaoCadastral === "REGULAR") {
  console.log(`CPF válido — titular: ${receita.nomePessoaFisica}`);
} else {
  console.log(`CPF com situação: ${receita.situacaoCadastral}`);
}

3. Implemente la lógica de decisión

El verdadero poder aparece cuando usted conecta el retorno de la API a su flujo de negocio. Un patrón eficiente para onboarding funciona así:

def validar_cpf_onboarding(cpf: str, nome_informado: str) -> dict:
    """
    Valida el CPF en el flujo de onboarding.
    Devuelve la decisión: aprobar, revisar o rechazar.
    """
    response = requests.get(
        "https://app.fontedata.com/api/v1/consulta/cadastro-rf-pf",
        params={"cpf": cpf},
        headers={"X-API-Key": API_KEY}
    )
    dados = response.json()
    receita = dados["receita"]

    # Situación impeditiva → rechazo automático
    situacoes_bloqueio = ["CANCELADA", "NULA", "TITULAR FALECIDO"]
    if receita["situacaoCadastral"] in situacoes_bloqueio:
        return {
            "decisao": "REJEITAR",
            "motivo": f"CPF com situação {receita['situacaoCadastral']}"
        }

    # Defunción registrada → rechazo automático
    if receita.get("possuiObito"):
        return {
            "decisao": "REJEITAR",
            "motivo": "CPF com registro de óbito"
        }

    # Situación pendiente → revisión humana
    if receita["situacaoCadastral"] != "REGULAR":
        return {
            "decisao": "REVISAR",
            "motivo": f"CPF com situação {receita['situacaoCadastral']}"
        }

    # Nombre divergente → revisión humana
    nome_oficial = receita["nomePessoaFisica"].upper().strip()
    if nome_informado.upper().strip() != nome_oficial:
        return {
            "decisao": "REVISAR",
            "motivo": "Nome informado diverge do cadastro oficial"
        }

    # Todo OK → aprobación automática
    return {"decisao": "APROVAR", "motivo": None}

Este es un ejemplo simplificado. En producción, usted puede agregar comparación fuzzy de nombres (para manejar abreviaciones y acentuación), validación de edad mínima usando el campo dataNascimento del bloque cadastro, y el cruce de teléfonos y direcciones para enriquecer el score de confiabilidad.

Buenas prácticas de arquitectura

Integrar una API de CPF es simple. Integrarla de forma inteligente exige atención a algunos puntos.

Valide en el front, consulte en el back. El dígito verificador (mod-11) puede comprobarse en el front-end para feedback inmediato. La consulta oficial debe ocurrir en el back-end, donde usted controla la lógica de decisión y protege su API key.

No consulte en cada keystroke. Haga la llamada a la API solo cuando el usuario confirme los datos — en el submit del formulario, no mientras escribe. Eso reduce costos y evita consultas innecesarias.

Implemente cache con criterio. Los datos registrales de CPF no cambian con frecuencia. Según su caso de uso, un cache de 24 h o hasta de 7 días puede ser adecuado para reducir llamadas repetidas sin comprometer la confiabilidad. Para operaciones financieras de alto valor, consulte siempre en tiempo real.

Maneje los errores con elegancia. La API puede estar temporalmente indisponible. Su sistema necesita un fallback definido: encolar para retry, habilitar con restricción provisoria o bloquear y notificar. Nunca ignore el error y apruebe silenciosamente.

Mantenga logs estructurados. Registre cada consulta con timestamp, CPF consultado (enmascarado si es necesario), resultado y decisión tomada. En una auditoría, ese log es su evidencia de due diligence.

Consulta manual vs. API: resumen comparativo

Aspecto	Consulta manual (Receita)	Consulta vía API
Velocidad	30 s–2 min por consulta	< 1 segundo
Captcha	Obligatorio	Ninguno
Formato del retorno	HTML visual	JSON estructurado
Integración con sistemas	Ninguna	Directa vía HTTP
Volumen	Unitaria	Miles por minuto
Costo operativo	Tiempo de analista	Centavos por consulta
Trazabilidad	Manual	Logs automáticos
Disponibilidad	Sin SLA	SLA contractual

¿Y la LGPD?

La consulta de CPF vía API trabaja con datos públicos disponibles en la Receita Federal. Aun así, la LGPD (la ley brasileña de protección de datos) exige que el tratamiento de datos personales tenga base legal y finalidad definida. En la práctica, eso significa que usted necesita una justificación legítima para consultar — KYC, prevención de fraudes, obligación legal o ejecución de un contrato son bases adecuadas. No debe consultar CPF de forma indiscriminada, sin relación con una operación concreta.

FonteData opera en conformidad con la legislación brasileña y no almacena datos personales de los titulares consultados más allá de lo necesario para el log de la operación.

Próximo paso

Si usted necesita validar CPF en su sistema — ya sea para onboarding, antifraude, emisión fiscal o compliance — la forma más eficiente es integrar vía API.

FonteData ofrece la consulta de CPF como parte de un hub con más de 100 fuentes de datos, incluyendo CNPJ, KYC, Receita Federal, antifraude y mucho más. Usted paga por consulta, sin mensualidad, con R$50 en créditos gratuitos para empezar.

Cree su cuenta gratuita →

¿Necesita ayuda con la integración? Nuestra documentación cubre todos los endpoints con ejemplos en Python, Node.js, cURL y más. Acceda a la documentación →