# API DNI — guía para LLM / agentes

## Propósito
Resuelve un DNI peruano (8 dígitos) a su titular: nombres completos,
apellidos paterno y materno.

## Base URL
`https://api-dni-ruc.gd.pe`

## Endpoint público

```
GET /api/dni/{dni}
```

- `dni` (path, requerido): exactamente 8 dígitos numéricos.
- Sin autenticación. Cache-Control: `public, max-age=300` en respuestas 200.

### Respuesta 200 OK

```json
{
  "success": true,
  "source": "cache",
  "data": {
    "dni": "60012345",
    "cliente": "QUISPE PEREZ JULIO FERNANDO",
    "nombres": "JULIO FERNANDO",
    "apellido_paterno": "QUISPE",
    "apellido_materno": "PEREZ",
    "mensaje": "OK",
    "code": "200"
  }
}
```

`source` indica de dónde vino la respuesta:
- `"cache"` → BD local. No consumió cupo del proveedor.
- `"provider"` → se llamó a peruapi.com y se guardó en cache para
  futuras consultas del mismo DNI.

Header HTTP equivalente: `X-Source: cache | provider`.

### Códigos de error

| HTTP | error                  | Significado                                          |
|------|------------------------|------------------------------------------------------|
| 400  | invalid_dni            | El parámetro no tiene 8 dígitos.                    |
| 404  | not_found              | El DNI no existe.                                   |
| 502  | provider_error         | El proveedor externo falló tras varios reintentos.  |
| 503  | no_tokens_available    | Todos los tokens del proveedor están agotados hoy.  |

## Ejemplo cURL

```bash
curl https://api-dni-ruc.gd.pe/api/dni/60012345
```

## Panel administrativo

Bajo `/admin`, protegido por `ADMIN_TOKEN`. Permite gestionar los
tokens del proveedor peruapi.com, ver métricas y auditar consultas.