{"openapi":"3.1.0","info":{"title":"API DNI","version":"2.0.0","description":"Consulta de DNI peruano. Devuelve nombres y apellidos del titular. Las consultas se balancean entre los tokens registrados sin importar el proveedor (peruapi.com o api.perudevs.com). Las respuestas se cachean en la BD local para servir hits futuros sin consumir cupo."},"servers":[{"url":"https://api-dni-ruc.gd.pe"}],"paths":{"/api/dni/{dni}":{"get":{"summary":"Consulta un DNI peruano (8 dígitos) — v1.","description":"Versión 1: shape histórico con `cliente`. Requiere autenticación con API key vía `Authorization: Bearer <key>`. Aplica rate limit por minuto y cuotas diaria/mensual por cliente (headers `X-RateLimit-*` en la respuesta).","security":[{"bearerAuth":[]}],"parameters":[{"name":"dni","in":"path","required":true,"schema":{"type":"string","pattern":"^\\d{8}$"}}],"responses":{"200":{"description":"DNI encontrado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DniOkV1"}}}},"400":{"description":"DNI inválido."},"401":{"description":"API key faltante o inválida."},"404":{"description":"DNI no encontrado."},"429":{"description":"Rate limit o cuota superada."},"502":{"description":"Error del proveedor externo."},"503":{"description":"No hay tokens disponibles."}}}},"/api/v2/dni/{dni}":{"get":{"summary":"Consulta un DNI peruano (8 dígitos) — v2.","description":"Versión 2: reemplaza `cliente` por `nombre_completo` y agrega `codigo_verificacion` (dígito verificador del DNI, provisto por api.perudevs.com; puede ser `null` si la respuesta cacheada vino de un proveedor que no lo expone). Mismas reglas de auth, rate limit y cuotas que v1.","security":[{"bearerAuth":[]}],"parameters":[{"name":"dni","in":"path","required":true,"schema":{"type":"string","pattern":"^\\d{8}$"}}],"responses":{"200":{"description":"DNI encontrado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DniOkV2"}}}},"400":{"description":"DNI inválido."},"401":{"description":"API key faltante o inválida."},"404":{"description":"DNI no encontrado."},"429":{"description":"Rate limit o cuota superada."},"502":{"description":"Error del proveedor externo."},"503":{"description":"No hay tokens disponibles."}}}},"/api/health":{"get":{"summary":"Estado del servicio","responses":{"200":{"description":"OK"}}}}},"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key del cliente. Header: Authorization: Bearer <key>"}},"schemas":{"DniOkV1":{"type":"object","properties":{"success":{"type":"boolean","const":true},"source":{"type":"string","enum":["cache","provider"],"description":"cache → BD interna · provider → llamada al proveedor externo."},"data":{"type":"object","properties":{"dni":{"type":"string"},"cliente":{"type":"string","description":"Nombre completo concatenado."},"nombres":{"type":"string"},"apellido_paterno":{"type":"string"},"apellido_materno":{"type":"string"},"mensaje":{"type":"string"},"code":{"type":"string"}}}}},"DniOkV2":{"type":"object","properties":{"success":{"type":"boolean","const":true},"source":{"type":"string","enum":["cache","provider"],"description":"cache → BD interna · provider → llamada al proveedor externo."},"data":{"type":"object","properties":{"dni":{"type":"string"},"nombres":{"type":"string"},"apellido_paterno":{"type":"string"},"apellido_materno":{"type":"string"},"nombre_completo":{"type":"string","description":"Sustituye a `cliente` de v1."},"codigo_verificacion":{"type":["string","null"],"description":"Dígito verificador del DNI. Sólo lo expone api.perudevs.com; será null si el cache vino de un proveedor que no lo provee."},"mensaje":{"type":"string"},"code":{"type":"string"}}}}}}}}