{"openapi":"3.1.0","info":{"title":"API DNI / RUC","version":"2.1.0","description":"Consulta de DNI peruano (nombres y apellidos del titular) y de RUC (razón social, estado, condición de domicilio y domicilio fiscal). Los DNI se balancean entre los tokens registrados sin importar el proveedor (peruapi.com o api.perudevs.com) y se cachean localmente. Los RUC se resuelven contra el Padrón Reducido oficial de SUNAT cargado en la BD, sin proveedores externos de por medio."},"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/ruc/{ruc}":{"get":{"summary":"Consulta un RUC peruano (11 dígitos).","description":"Devuelve la razón social y los datos del contribuyente según el Padrón Reducido del RUC de SUNAT, cargado localmente y refrescado a diario. La respuesta sale siempre de la BD (`source: \"padron\"`) y no consume cupo de ningún proveedor externo, pero sí aplica la misma auth, rate limit y cuotas por API key que los endpoints de DNI. `padron_actualizado_al` indica la fecha del archivo de SUNAT con el que se pobló la tabla: el dato puede tener hasta ~24h de rezago frente a la ficha RUC en vivo.","security":[{"bearerAuth":[]}],"parameters":[{"name":"ruc","in":"path","required":true,"schema":{"type":"string","pattern":"^(10|15|16|17|20)\\d{9}$"}}],"responses":{"200":{"description":"RUC encontrado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RucOk"}}}},"400":{"description":"RUC inválido."},"401":{"description":"API key faltante o inválida."},"404":{"description":"RUC no encontrado en el padrón."},"429":{"description":"Rate limit o cuota superada."},"503":{"description":"El padrón todavía no fue importado."}}}},"/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"}}}}},"RucOk":{"type":"object","properties":{"success":{"type":"boolean","const":true},"source":{"type":"string","const":"padron","description":"Siempre \"padron\": el dato sale del Padrón Reducido local."},"padron_actualizado_al":{"type":["string","null"],"format":"date-time","description":"Fecha del archivo de SUNAT con el que se pobló la tabla."},"data":{"type":"object","required":["ruc","razon_social"],"properties":{"ruc":{"type":"string"},"razon_social":{"type":"string"},"estado":{"type":["string","null"],"description":"Estado del contribuyente, ej. ACTIVO / BAJA DE OFICIO."},"condicion":{"type":["string","null"],"description":"Condición de domicilio, ej. HABIDO / NO HABIDO."},"ubigeo":{"type":["string","null"]},"direccion":{"type":["string","null"],"description":"Domicilio fiscal concatenado. Null para casi todos los RUC 10: el padrón sólo publica el domicilio desglosado de personas jurídicas."},"direccion_partes":{"type":"object","description":"Las mismas partes del domicilio sin concatenar, con los nombres de columna originales de SUNAT. Todos los campos pueden ser null; en los RUC 10 (personas naturales) normalmente lo son todos.","properties":{"tipo_via":{"type":["string","null"],"description":"Abreviatura del tipo de vía: AV., JR., CAL., PSJ."},"nombre_via":{"type":["string","null"],"description":"Nombre de la vía."},"codigo_zona":{"type":["string","null"],"description":"Pese al nombre, contiene la ABREVIATURA del tipo de zona (URB., A.H., P.J., C.P.). SUNAT tiene invertidos los rótulos de esta columna y de `tipo_zona` en su archivo fuente; conservamos sus nombres para que el dato sea rastreable. Al concatenar va este campo primero."},"tipo_zona":{"type":["string","null"],"description":"Pese al nombre, contiene el NOMBRE propio de la zona. Ver la nota en `codigo_zona`."},"numero":{"type":["string","null"],"description":"Número de puerta."},"interior":{"type":["string","null"],"description":"Interior."},"lote":{"type":["string","null"],"description":"Lote."},"departamento":{"type":["string","null"],"description":"Departamento (piso/unidad), no el departamento geográfico."},"manzana":{"type":["string","null"],"description":"Manzana."},"kilometro":{"type":["string","null"],"description":"Kilómetro, para direcciones sobre carretera."}}}}}}},"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"}}}}}}}}