Validacion CPF

Valida un numero de CPF verificando formato y digitos verificadores por el algoritmo Modulo 11.

Endpoint

POST /api/external/cpf/validate

Headers

Header	Tipo	Obligatorio	Descripcion
Authorization	String	Si	ApiKey {client_id}:{client_secret} (formato Basic con base64 tambien aceptado -- ver Autenticacion)
Content-Type	String	Si	application/json
hmac	String	Si	Firma HMAC-SHA512 del body en hexadecimal lowercase (mas informacion)
X-Key-Case	String	No	camelCase -- convierte params/response snake_case ↔ camelCase. Si envia camelCase, firme el body ya en camelCase (ver HMAC-SHA512)
Idempotency-Key	String	No	Clave unica para evitar procesamiento duplicado (hasta 256 chars). Cuando presente, el servidor reproduce en Idempotency-Key en el response y agrega X-Idempotent-Replay: true en caso de replay

Permiso obligatorio en la API Key: account:read. Sin el, la solicitud es rechazada con 403 API key lacks permission: account:read antes de ejecutar la validacion.

Request Body

Campo	Tipo	Obligatorio	Descripcion	Ejemplo
cpf	String	Si	Numero del CPF (con o sin formato)	"12345678909" o "123.456.789-09"

Alias

El campo document_number tambien es aceptado como alias.

Ejemplo

HMAC obligatorio

Este endpoint exige el header hmac incluso teniendo un unico campo en el body. Solicitudes sin el header retornan 401 Missing HMAC header antes de llegar al controller.

# Body con solo 1 campo — ya esta "alfabetizado" trivialmente
BODY='{"cpf":"12345678909"}'

# Computa HMAC-SHA512 con el client_secret como clave
HMAC=$(echo -n "$BODY" | openssl dgst -sha512 -hmac "$CLIENT_SECRET" | awk '{print $2}')

curl -X POST https://api.owem.com.br/api/external/cpf/validate \
  -H "Authorization: ApiKey $CLIENT_ID:$CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -H "hmac: $HMAC" \
  -d "$BODY"

Respuesta de Exito -- CPF Valido (200)

{
  "worked": true,
  "valid": true,
  "formatted": "123.456.789-09"
}

Respuesta de Exito -- CPF Invalido (200)

{
  "worked": true,
  "valid": false,
  "detail": "CPF inválido"
}

Posibles mensajes en detail cuando valid: false:

detail	Causa
"CPF deve ter 11 digitos"	Despues de remover no-digitos, el numero no tiene exactamente 11 digitos
"CPF invalido"	Todos los 11 digitos son iguales (ej: 111.111.111-11)
"CPF invalido (digito verificador)"	Digitos verificadores fallaron en el algoritmo Modulo 11

Campo	Tipo	Descripcion
worked	Boolean	true indica que la validacion fue ejecutada (no es garantia de CPF valido)
valid	Boolean	true si el CPF es valido por el Modulo 11, false caso contrario
formatted	String	CPF formateado (XXX.XXX.XXX-XX). Presente solo cuando valid: true
detail	String	Mensaje explicando la reprobacion. Presente solo cuando valid: false

Por que 200 OK con valid: false y no 400?

CPF invalido es un resultado valido de la validacion -- no es un error de la solicitud. La API proceso el pedido con exito y esta informando que aquel numero no pasa en el Modulo 11. El cliente debe siempre inspeccionar el campo valid (no solo el HTTP status) para decidir el proximo paso. El mismo patron {worked: true, ...} aparece en GET /balance (retorna worked: true, balance: N) y en POST /webhooks (retorna worked: true, id: "...").

Validaciones Realizadas

1. Verifica que el CPF tenga exactamente 11 digitos
2. Rechaza CPFs con todos los digitos iguales (ej: 111.111.111-11)
3. Calcula y verifica los 2 digitos verificadores mediante el algoritmo Modulo 11

Respuestas de Error

400 -- Campo cpf Ausente (FallbackController)

Cuando el body no contiene el campo cpf (ni el alias document_number), el FallbackController rechaza la solicitud antes de ejecutar la validacion Modulo 11:

{
  "errors": {
    "bad_request": {
      "cpf": ["is required"]
    }
  }
}

CPF invalido retorna HTTP 200, no 400

CPFs que llegan al controller pero fallan en el Modulo 11 (digitos verificadores errados, todos los digitos iguales, o menos de 11 digitos) retornan HTTP 200 con {"worked": true, "valid": false, "detail": "CPF inválido"}. No confunda con el 400 arriba -- el 400 es exclusivo para el caso de que el campo cpf este ausente del body.

401 -- HMAC Ausente o Invalido (plug HMAC)

{
  "worked": false,
  "detail": "Missing HMAC header"
}

{
  "worked": false,
  "detail": "Invalid HMAC signature"
}

401 tiene dos formatos distintos

El 401 retornado por la capa de validacion HMAC (arriba) tiene shape diferente del 401 retornado por la capa de API Key ({"error": {status, message}}). Vea Autenticacion -- Respuestas de Error para el detalle de las tres capas.

Uso

Este endpoint realiza solo validacion matematica del CPF (Modulo 11). No consulta a la Receita Federal ni verifica la situacion registral del documento.