Validação CPF

Valida um número de CPF verificando formato e dígitos verificadores pelo algoritmo Módulo 11.

Endpoint

POST /api/external/cpf/validate

Headers

Header	Tipo	Obrigatório	Descrição
Authorization	String	Sim	ApiKey {client_id}:{client_secret} (formato Basic com base64 também aceito -- ver Autenticação)
Content-Type	String	Sim	application/json
hmac	String	Sim	Assinatura HMAC-SHA512 do body em hexadecimal lowercase (saiba mais)
X-Key-Case	String	Não	camelCase -- converte params/response snake_case ↔ camelCase. Se enviar camelCase, assine o body já em camelCase (ver HMAC-SHA512)
Idempotency-Key	String	Não	Chave única para evitar processamento duplicado (até 256 chars). Quando presente, o servidor ecoa em Idempotency-Key no response e adiciona X-Idempotent-Replay: true em caso de replay

Permissão obrigatória na API Key: account:read. Sem ela, a requisição é rejeitada com 403 API key lacks permission: account:read antes de executar a validação.

Request Body

Campo	Tipo	Obrigatório	Descrição	Exemplo
cpf	String	Sim	Número do CPF (com ou sem formatação)	"12345678909" ou "123.456.789-09"

Alias

O campo document_number também é aceito como alias.

Exemplo

HMAC obrigatório

Este endpoint exige o header hmac mesmo tendo um único campo no body. Requisições sem o header retornam 401 Missing HMAC header antes de chegar ao controller.

# Body com apenas 1 campo — já está "alfabetizado" trivialmente
BODY='{"cpf":"12345678909"}'

# Computa HMAC-SHA512 com o client_secret como chave
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"

Resposta de Sucesso -- CPF Válido (200)

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

Resposta de Sucesso -- CPF Inválido (200)

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

Possíveis mensagens em detail quando valid: false:

detail	Causa
"CPF deve ter 11 digitos"	Após remover não-dígitos, o número não tem exatamente 11 dígitos
"CPF invalido"	Todos os 11 dígitos são iguais (ex: 111.111.111-11)
"CPF invalido (digito verificador)"	Dígitos verificadores falharam no algoritmo Módulo 11

Campo	Tipo	Descrição
worked	Boolean	true indica que a validação foi executada (não é garantia de CPF válido)
valid	Boolean	true se o CPF é válido pelo Módulo 11, false caso contrário
formatted	String	CPF formatado (XXX.XXX.XXX-XX). Presente apenas quando valid: true
detail	String	Mensagem explicando a reprovação. Presente apenas quando valid: false

Por que 200 OK com valid: false e não 400?

CPF inválido é um resultado válido da validação -- não é um erro da requisição. A API processou o pedido com sucesso e está informando que aquele número não passa no Módulo 11. O cliente deve sempre inspecionar o campo valid (não apenas o HTTP status) para decidir o próximo passo. O mesmo padrão {worked: true, ...} aparece em GET /balance (retorna worked: true, balance: N) e no POST /webhooks (retorna worked: true, id: "...").

Validações Realizadas

1. Verifica se o CPF possui exatamente 11 dígitos
2. Rejeita CPFs com todos os dígitos iguais (ex: 111.111.111-11)
3. Calcula e verifica os 2 dígitos verificadores pelo algoritmo Módulo 11

Respostas de Erro

400 -- Campo cpf Ausente (FallbackController)

Quando o body não contém o campo cpf (nem o alias document_number), o FallbackController rejeita a requisição antes de executar a validação Módulo 11:

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

CPF inválido retorna HTTP 200, não 400

CPFs que chegam ao controller mas falham no Módulo 11 (dígitos verificadores errados, todos os dígitos iguais, ou menos de 11 dígitos) retornam HTTP 200 com {"worked": true, "valid": false, "detail": "CPF inválido"}. Não confunda com o 400 acima -- o 400 é exclusivo para o caso de o campo cpf estar ausente do body.

401 -- HMAC Ausente ou Inválido (plug HMAC)

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

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

401 tem dois formatos distintos

O 401 retornado pela camada de validação HMAC (acima) tem shape diferente do 401 retornado pela camada de API Key ({"error": {status, message}}). Veja Autenticação -- Respostas de Erro para o detalhamento das três camadas.

Uso

Este endpoint realiza apenas validação matemática do CPF (Módulo 11). Não consulta a Receita Federal nem verifica a situação cadastral do documento.