# 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](/es/auth-token#capa-1-api-key-secret)) |
| `Content-Type` | String | Si | `application/json` |
| `hmac` | String | Si | Firma HMAC-SHA512 del body en hexadecimal lowercase ([mas informacion](/es/hmac)) |
| `X-Key-Case` | String | No | `camelCase` -- convierte params/response snake_case ↔ camelCase. Si envia `camelCase`, firme el body ya en camelCase (ver [HMAC-SHA512](/es/hmac)) |
| `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"` |

::: tip Alias
El campo `document_number` tambien es aceptado como alias.
:::

## Ejemplo

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

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

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

## Respuesta de Exito -- CPF Invalido (200)

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

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

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

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

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

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

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

::: warning 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](/es/auth-token#respuestas-de-error) para el detalle de las tres capas.
:::

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