# 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. Dos versiones disponibles según el shape
de respuesta que necesites (`v1` con `cliente`, `v2` con
`nombre_completo` + `codigo_verificacion`).

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

## Autenticación (ambas versiones)
- Header: `Authorization: Bearer <api-key>`.
- Rate limit por API key: por minuto + cuota diaria + cuota mensual. La
  respuesta incluye headers `X-RateLimit-Limit-Minute`,
  `X-RateLimit-Remaining-Minute`, `X-RateLimit-Limit-Day`,
  `X-RateLimit-Remaining-Day`, `X-RateLimit-Limit-Month`,
  `X-RateLimit-Remaining-Month`. Al superar el límite por minuto se agrega
  `Retry-After` (segundos).
- Cache-Control: `public, max-age=300` en respuestas 200.
- `source` y header `X-Source`: `"cache"` si la respuesta vino de la BD
  local (sin consumir cupo) o `"provider"` si se llamó al proveedor externo
  (peruapi.com o api.perudevs.com — el balanceo es transparente para el
  cliente).

## Endpoint v1 — shape histórico

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

- `dni` (path, requerido): exactamente 8 dígitos numéricos.

### Respuesta 200 OK (v1)

```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"
  }
}
```

## Endpoint v2 — con nombre_completo y código de verificación

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

- Mismos parámetros, mismas reglas de auth/rate limit/cuotas que v1.
- `cliente` se reemplaza por `nombre_completo`.
- Se agrega `codigo_verificacion`: dígito verificador del DNI provisto por
  `api.perudevs.com`. Puede ser `null` si la respuesta vino cacheada de un
  proveedor que no lo expone (en ese caso, una nueva consulta servida por
  perudevs lo poblará en el cache).

### Respuesta 200 OK (v2)

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

## Códigos de error (ambas versiones)

| HTTP | error                  | Significado                                          |
|------|------------------------|------------------------------------------------------|
| 400  | invalid_dni            | El parámetro no tiene 8 dígitos.                    |
| 401  | unauthorized           | Falta la API key o es inválida/inactiva.            |
| 404  | not_found              | El DNI no existe.                                   |
| 429  | rate_limit_minute      | Se superó el límite de requests por minuto.         |
| 429  | quota_daily            | Se agotó la cuota diaria de la API key.             |
| 429  | quota_monthly          | Se agotó la cuota mensual de la API key.            |
| 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
# v1 (cliente)
curl -H "Authorization: Bearer TU_API_KEY" https://api-dni-ruc.gd.pe/api/dni/60012345

# v2 (nombre_completo + codigo_verificacion)
curl -H "Authorization: Bearer TU_API_KEY" https://api-dni-ruc.gd.pe/api/v2/dni/60012345
```

## Cómo elegir v1 vs v2
- Usá **v1** si ya tenés integraciones que leen `data.cliente` y no necesitás
  el dígito verificador.
- Usá **v2** si necesitás el código de verificación (`codigo_verificacion`)
  o preferís el nombre canónico `nombre_completo`.

## Panel administrativo

Bajo `/admin`, protegido por login admin. Permite gestionar los tokens de
los proveedores (peruapi.com y api.perudevs.com), ver métricas, auditar
consultas y limpiar el cache local.