# 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](/auth-token#camada-1-api-key-secret)) |
| `Content-Type` | String | Sim | `application/json` |
| `hmac` | String | Sim | Assinatura HMAC-SHA512 do body em hexadecimal lowercase ([saiba mais](/hmac)) |
| `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](/hmac)) |
| `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"` |

::: tip Alias
O campo `document_number` também é aceito como alias.
:::

## Exemplo

::: warning 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.
:::

```bash
# 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.monetarie.com/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)

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

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

```json
{
  "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` |

::: tip 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

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

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

::: tip 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)

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

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

::: warning 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](/auth-token#respostas-de-erro) para o detalhamento das três camadas.
:::

::: tip 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.
:::