Validation CPF

Valide un numéro de CPF en vérifiant le format et les chiffres de contrôle par l'algorithme Modulo 11.

Endpoint

POST /api/external/cpf/validate

Headers

Header	Type	Obligatoire	Description
Authorization	String	Oui	ApiKey {client_id}:{client_secret} (format Basic avec base64 aussi accepté -- voir Authentification)
Content-Type	String	Oui	application/json
hmac	String	Oui	Signature HMAC-SHA512 du body en hexadécimal lowercase (en savoir plus)
X-Key-Case	String	Non	camelCase -- convertit params/response snake_case ↔ camelCase. Si vous envoyez camelCase, signez le body déjà en camelCase (voir HMAC-SHA512)
Idempotency-Key	String	Non	Clé unique pour éviter le traitement en double (jusqu'à 256 caractères). Quand présent, le serveur renvoie cette valeur dans Idempotency-Key dans la response et ajoute X-Idempotent-Replay: true en cas de replay

Permission obligatoire sur l'API Key : account:read. Sans elle, la requête est rejetée avec 403 API key lacks permission: account:read avant d'exécuter la validation.

Request Body

Champ	Type	Obligatoire	Description	Exemple
cpf	String	Oui	Numéro du CPF (avec ou sans formatage)	"12345678909" ou "123.456.789-09"

Alias

Le champ document_number est également accepté comme alias.

Exemple

HMAC obligatoire

Cet endpoint exige l'en-tête hmac même en ayant un unique champ dans le body. Les requêtes sans cet en-tête retournent 401 Missing HMAC header avant d'atteindre le controller.

# Body avec seulement 1 champ — déjà « alphabétisé » trivialement
BODY='{"cpf":"12345678909"}'

# Calcul du HMAC-SHA512 avec le client_secret comme clé
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"

Réponse de succès -- CPF valide (200)

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

Réponse de succès -- CPF invalide (200)

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

Messages possibles dans detail quand valid: false :

detail	Cause
"CPF deve ter 11 digitos"	Après suppression des non-chiffres, le numéro n'a pas exactement 11 chiffres
"CPF invalido"	Les 11 chiffres sont tous identiques (ex. : 111.111.111-11)
"CPF invalido (digito verificador)"	Les chiffres de contrôle ont échoué à l'algorithme Modulo 11

Champ	Type	Description
worked	Boolean	true indique que la validation a été exécutée (n'est pas une garantie de CPF valide)
valid	Boolean	true si le CPF est valide selon le Modulo 11, false sinon
formatted	String	CPF formaté (XXX.XXX.XXX-XX). Présent seulement quand valid: true
detail	String	Message expliquant le rejet. Présent seulement quand valid: false

Pourquoi 200 OK avec valid: false et pas 400 ?

CPF invalide est un résultat valide de la validation -- ce n'est pas une erreur de la requête. L'API a traité la demande avec succès et informe que ce numéro ne passe pas le Modulo 11. Le client doit toujours inspecter le champ valid (pas seulement le status HTTP) pour décider de la suite. Le même pattern {worked: true, ...} apparaît dans GET /balance (retourne worked: true, balance: N) et POST /webhooks (retourne worked: true, id: "...").

Validations effectuées

1. Vérifie que le CPF contient exactement 11 chiffres
2. Rejette les CPFs dont tous les chiffres sont identiques (ex. : 111.111.111-11)
3. Calcule et vérifie les 2 chiffres de contrôle par l'algorithme Modulo 11

Réponses d'erreur

400 -- Champ cpf absent (FallbackController)

Quand le body ne contient pas le champ cpf (ni l'alias document_number), le FallbackController rejette la requête avant d'exécuter la validation Modulo 11 :

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

CPF invalide retourne HTTP 200, pas 400

Les CPFs qui arrivent au controller mais échouent au Modulo 11 (chiffres de contrôle erronés, tous les chiffres identiques, ou moins de 11 chiffres) retournent HTTP 200 avec {"worked": true, "valid": false, "detail": "CPF inválido"}. Ne confondez pas avec le 400 ci-dessus -- le 400 est exclusif au cas où le champ cpf est absent du body.

401 -- HMAC absent ou invalide (plug HMAC)

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

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

401 a deux formats distincts

Le 401 retourné par la couche de validation HMAC (ci-dessus) a un shape différent du 401 retourné par la couche API Key ({"error": {status, message}}). Voir Authentification -- Réponses d'erreur pour le détail des trois couches.

Usage

Cet endpoint effectue uniquement une validation mathématique du CPF (Modulo 11). Il ne consulte pas la Receita Federal ni ne vérifie la situation du document auprès de l'administration fiscale.