Validación de CPF: Formato, algoritmo e integración con API para Brasil

El CPF (Cadastro de Pessoas Físicas) es la columna vertebral de la identificación individual en Brasil. Si estás construyendo cualquier aplicación que atienda a usuarios brasileños — fintech, e-commerce, nómina o compliance — vas a necesitar validar números de CPF en algún momento. Un solo CPF inválido puede bloquear una transferencia PIX, rechazar una Nota Fiscal Eletrônica o marcar un onboarding de cliente como fraudulento. Sin embargo, la lógica de validación de CPF es más compleja de lo que la mayoría de los desarrolladores espera. Más allá de las verificaciones básicas de formato, necesitás entender el algoritmo de dos pasos para los dígitos verificadores, reconocer patrones inválidos conocidos y manejar casos especiales que aparecen en producción. Esta guía cubre todo: qué es un CPF, su estructura de 11 dígitos, el algoritmo completo de módulo 11 para ambos dígitos verificadores, errores comunes y cómo validar CPFs instantáneamente usando la API Validate de Normadata.

¿Qué es un CPF?

El CPF (Cadastro de Pessoas Físicas) es el número de identificación tributaria individual de Brasil, emitido por la Receita Federal (el equivalente brasileño del IRS). Todo ciudadano y residente brasileño que paga impuestos, abre una cuenta bancaria, firma un contrato o incluso compra un chip de celular necesita un CPF. Es el identificador más importante para personas físicas en Brasil, comparable al Social Security Number en Estados Unidos o al CUIT en Argentina. A diferencia de identificadores corporativos como el CNPJ (que identifica empresas), el CPF es estrictamente personal. Acompaña a la persona de por vida y no cambia cuando se muda de estado o cambia de trabajo. El número en sí tiene 11 dígitos e incluye dos dígitos verificadores calculados mediante un algoritmo de módulo 11, lo que significa que podés verificar su validez matemática sin consultar ninguna base de datos externa.

Formato y estructura del CPF

Un CPF se escribe como XXX.XXX.XXX-XX, donde los primeros nueve dígitos identifican al contribuyente y los últimos dos son dígitos verificadores. El cuerpo de nueve dígitos no es completamente aleatorio: el noveno dígito (antes de los dígitos verificadores) indica la región fiscal donde se emitió originalmente el CPF. Por ejemplo, 0 corresponde a Rio Grande do Sul, 1 al Distrito Federal, Goiás, Mato Grosso, Mato Grosso do Sul y Tocantins, y así sucesivamente hasta 9 para São Paulo. Si bien este dígito regional es un artefacto histórico y no afecta la validación, es contexto útil. Cuando se transmite electrónicamente, el CPF siempre son 11 dígitos sin separadores. En interfaces para el usuario, se muestra con puntos y un guión para facilitar la lectura: 123.456.789-09. Tu sistema debería aceptar ambos formatos y normalizar a la versión de 11 dígitos antes de validar.

El algoritmo de dígitos verificadores

El CPF usa dos dígitos verificadores, cada uno calculado independientemente usando un algoritmo de módulo 11 con diferentes secuencias de pesos. Esta verificación de dos pasos hace al CPF más robusto contra errores de transcripción que los esquemas de un solo dígito. Este es el algoritmo completo:

1. Primer dígito verificador (dígito 10): Tomá los primeros 9 dígitos. Multiplicá cada uno por pesos descendentes de 10 a 2 (primer dígito x 10, segundo dígito x 9, .., noveno dígito x 2). Sumá todos los productos. Calculá el resto: suma módulo 11. Si el resto es menor que 2, el primer dígito verificador es 0. Si no, el primer dígito verificador es 11 menos el resto.
2. Segundo dígito verificador (dígito 11): Tomá los primeros 10 dígitos (incluyendo el dígito verificador que acabás de calcular). Multiplicá cada uno por pesos descendentes de 11 a 2 (primer dígito x 11, segundo dígito x 10, .., décimo dígito x 2). Sumá todos los productos. Calculá el resto: suma módulo 11. Si el resto es menor que 2, el segundo dígito verificador es 0. Si no, el segundo dígito verificador es 11 menos el resto.

Veamos un ejemplo con el CPF 111.444.777-35. Los primeros 9 dígitos son 5, 2, 9, 9, 8, 2, 2, 4, 7. Multiplicamos por pesos del 10 al 2: (5x10)+(2x9)+(9x8)+(9x7)+(8x6)+(2x5)+(2x4)+(4x3)+(7x2) = 50+18+72+63+48+10+8+12+14 = 295. Luego 295 mod 11 = 9, y como 9 >= 2, el primer dígito verificador es 11-9 = 2. Para el segundo dígito verificador, tomamos los 10 dígitos 5,2,9,9,8,2,2,4,7,2 y multiplicamos por pesos del 11 al 2: (5x11)+(2x10)+(9x9)+(9x8)+(8x7)+(2x6)+(2x5)+(4x4)+(7x3)+(2x2) = 55+20+81+72+56+12+10+16+21+4 = 347. Luego 347 mod 11 = 6, y 11-6 = 5. El CPF completo es 111.444.777-35, y ambos dígitos verificadores coinciden.

Patrones inválidos comunes

Más allá del algoritmo de dígitos verificadores, hay varios patrones de CPF que son matemáticamente válidos pero se sabe que son inválidos. Tu lógica de validación debería rechazarlos:

• Todos los dígitos iguales — CPFs como 000.000.000-00, 111.111.111-11, 222.222.222-22, hasta 999.999.999-99 pasan la verificación de módulo 11 pero no son CPFs reales. La Receita Federal nunca emite estas secuencias. Siempre verificá este patrón antes de ejecutar el algoritmo.
• Todos ceros — 000.000.000-00 es el input inválido más común y debería rechazarse directamente.
• Dígitos secuenciales — Aunque no están oficialmente en lista negra, patrones como 123.456.789-09 a veces se usan como datos de prueba y deberían marcarse en ambientes de producción.
• Errores de longitud — Inputs más cortos o más largos de 11 dígitos (después de limpiar el formato) son inválidos. Cuidado con los ceros iniciales faltantes: los CPFs que empiezan con 0 son legítimos, y quitar ese cero produce un número de 10 dígitos que va a fallar la validación.

Validando con la API de Normadata

La API Validate de Normadata maneja toda la lógica de validación de CPF — el algoritmo de módulo 11, detección de patrones inválidos, normalización de formato y extracción de metadatos — en una sola llamada a la API. Esto significa que no necesitás implementar ni mantener el algoritmo vos mismo. Acá van ejemplos:

curl -X POST https://api.normadata.io/v1/validate/tax-ids \
 -H "X-API-Key: nd_your_key_here" \
 -H "Content-Type: application/json" \
 -d {
 "value": "111.444.777-35",
 "country": "BR",
 "type": "cpf"
 }

import requests

response = requests.post(
 "https://api.normadata.io/v1/validate/tax-ids",
 headers={"X-API-Key": "nd_your_key_here"},
 json={
 "value": "111.444.777-35",
 "country": "BR",
 "type": "cpf"
 }
)
data = response.json()
print(data["valid"]) # True

{
 "valid": true,
 "country": "BR",
 "type": "cpf",
 "value": {
 "raw": "11144477735",
 "formatted": "111.444.777-35"
 },
 "metadata": {
 "fiscal_region": "7",
 "fiscal_region_name": "Amazonas, Pará, Maranhão, Piauí",
 "check_digits": "25"
 }
}

{
 "valid": false,
 "country": "BR",
 "type": "cpf",
 "value": {
 "raw": "11111111111",
 "formatted": "111.111.111-11"
 },
 "error": {
 "code": "err_known_invalid",
 "message": "CPF matches known invalid pattern (all same digits)."
 }
}

Próximos pasos

La validación de CPF es un bloque fundamental para cualquier aplicación que atienda usuarios brasileños. Ya sea que estés verificando clientes durante el onboarding, validando datos de Nota Fiscal o procesando transferencias PIX, tener la validación de CPF bien implementada previene errores downstream y problemas de compliance. La API Validate de Normadata soporta no solo CPFs sino también CNPJs y docenas de otros identificadores latinoamericanos — todo a través del mismo endpoint batch consistente. Visitá la página del producto Validate para la lista completa de tipos de documento soportados, o andá a la documentación de la API para empezar a integrar.