{ "openapi": "3.1.0", "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema", "info": { "title": "DatosPerú API", "version": "1.0.0", "description": "25 endpoints de consulta de datos en Perú. API privada e independiente de SUNAT y RENIEC. Una consulta exitosa consume un crédito. Guarda el token en tu servidor. La disponibilidad depende del proveedor y la configuración del servicio.", "termsOfService": "https://datosperu.net/terminos", "contact": { "name": "Soporte DatosPerú", "email": "soporte@wazend.net", "url": "https://datosperu.net/contacto" } }, "servers": [ { "url": "https://api.datosperu.net", "description": "Producción" } ], "externalDocs": { "url": "https://datosperu.net/docs", "description": "Referencia, ejemplos e integraciones" }, "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "personas" }, { "name": "empresas" }, { "name": "sunat" }, { "name": "vehiculos" }, { "name": "finanzas" }, { "name": "recibos" } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "API Key generada en el dashboard. No utilizar credenciales JSON.pe ni claves de administrador." } }, "schemas": { "Meta": { "type": "object", "required": [ "request_id", "timestamp" ], "properties": { "request_id": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "ErrorResponse": { "type": "object", "required": [ "success", "error" ], "additionalProperties": false, "properties": { "success": { "const": false }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "missing": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "meta": { "$ref": "#/components/schemas/Meta" } } } } }, "paths": { "/api/v1/dni": { "post": { "operationId": "consultar_dni", "summary": "Consulta DNI", "description": "Request body para consulta de DNI. El DNI debe ser un string de 8 dígitos numéricos.", "tags": [ "personas" ], "externalDocs": { "url": "https://datosperu.net/docs/dni" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "dni" ], "description": "Request body para consulta de DNI. El DNI debe ser un string de 8 dígitos numéricos.", "properties": { "dni": { "type": "string", "description": "Número de Documento Nacional de Identidad (DNI) de 8 dígitos. Debe ser numérico y tener exactamente 8 caracteres.", "pattern": "^[0-9]{8}$", "minLength": 8, "maxLength": 8 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Consulta exitosa. Los campos opcionales dependen de la fuente; un resultado no equivale a una certificación oficial.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "meta" ], "additionalProperties": false, "properties": { "success": { "const": true }, "data": { "type": "object", "additionalProperties": false, "properties": { "documento": { "type": [ "string", "null" ], "description": "Número de DNI consultado" }, "nombres": { "type": [ "string", "null" ], "description": "Nombres de pila de la persona" }, "apellido_paterno": { "type": [ "string", "null" ], "description": "Primer apellido (apellido paterno) de la persona" }, "apellido_materno": { "type": [ "string", "null" ], "description": "Segundo apellido (apellido materno) de la persona" } } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "description": "JSON inválido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "API Key ausente, inválida o revocada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Cuenta, verificación o permisos insuficientes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No se encontraron resultados", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Método no admitido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Cuerpo demasiado grande", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "415": { "description": "Content-Type no admitido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Parámetros inválidos", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Límite por minuto o cuota del periodo agotada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Error interno", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Error del proveedor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Servicio no disponible o pendiente de configuración", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "Tiempo de espera agotado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/ce": { "post": { "operationId": "consultar_ce", "summary": "Carnet de extranjería", "description": "Carnet de extranjería mediante una consulta autenticada.", "tags": [ "personas" ], "externalDocs": { "url": "https://datosperu.net/docs/ce" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "ce" ], "properties": { "ce": { "type": "string", "description": "El carnet de extranjería a consultar", "pattern": "^[A-Za-z0-9-]{1,20}$", "maxLength": 200, "minLength": 1 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Consulta exitosa. Los campos opcionales dependen de la fuente; un resultado no equivale a una certificación oficial.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "meta" ], "additionalProperties": false, "properties": { "success": { "const": true }, "data": { "type": "object", "additionalProperties": false, "properties": { "documento": { "type": [ "string", "null" ], "description": "Número del carnet de extranjería de la persona" }, "nombres": { "type": [ "string", "null" ], "description": "Nombres de la persona" }, "apellido_paterno": { "type": [ "string", "null" ], "description": "Apellido paterno de la persona" }, "apellido_materno": { "type": [ "string", "null" ], "description": "Apellido materno de la persona" } } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "description": "JSON inválido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "API Key ausente, inválida o revocada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Cuenta, verificación o permisos insuficientes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No se encontraron resultados", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Método no admitido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Cuerpo demasiado grande", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "415": { "description": "Content-Type no admitido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Parámetros inválidos", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Límite por minuto o cuota del periodo agotada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Error interno", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Error del proveedor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Servicio no disponible o pendiente de configuración", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "Tiempo de espera agotado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/ci": { "post": { "operationId": "consultar_ci", "summary": "Cédula de identidad", "description": "Cédula de identidad mediante una consulta autenticada.", "tags": [ "personas" ], "externalDocs": { "url": "https://datosperu.net/docs/ci" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "ci" ], "properties": { "ci": { "type": "string", "description": "La cédula de identidad a consultar", "pattern": "^[A-Za-z0-9-]{1,20}$", "maxLength": 200, "minLength": 1 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Consulta exitosa. Los campos opcionales dependen de la fuente; un resultado no equivale a una certificación oficial.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "meta" ], "additionalProperties": false, "properties": { "success": { "const": true }, "data": { "type": "object", "additionalProperties": false, "properties": { "documento": { "type": [ "string", "null" ], "description": "Número de la cédula de identidad de la persona" }, "nombres": { "type": [ "string", "null" ], "description": "Nombres de la persona" }, "apellido_paterno": { "type": [ "string", "null" ], "description": "Apellido paterno de la persona" }, "apellido_materno": { "type": [ "string", "null" ], "description": "Apellido materno de la persona" } } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "description": "JSON inválido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "API Key ausente, inválida o revocada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Cuenta, verificación o permisos insuficientes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No se encontraron resultados", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Método no admitido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Cuerpo demasiado grande", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "415": { "description": "Content-Type no admitido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Parámetros inválidos", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Límite por minuto o cuota del periodo agotada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Error interno", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Error del proveedor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Servicio no disponible o pendiente de configuración", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "Tiempo de espera agotado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/dni-ruc": { "post": { "operationId": "consultar_dni_ruc", "summary": "DNI → RUC", "description": "Request body para consulta DNI - RUC. El DNI debe ser un string de 8 dígitos.", "tags": [ "personas" ], "externalDocs": { "url": "https://datosperu.net/docs/dni-ruc" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "dni" ], "description": "Request body para consulta DNI - RUC. El DNI debe ser un string de 8 dígitos.", "properties": { "dni": { "type": "string", "description": "Número de DNI de 8 dígitos", "pattern": "^[0-9]{8}$", "minLength": 8, "maxLength": 8 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Consulta exitosa. Los campos opcionales dependen de la fuente; un resultado no equivale a una certificación oficial.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "meta" ], "additionalProperties": false, "properties": { "success": { "const": true }, "data": { "type": [ "object", "null" ], "description": "Datos del RUC asociado al DNI", "properties": { "ruc": { "type": [ "string", "null" ], "description": "Número de RUC asociado al DNI" } }, "additionalProperties": false }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "description": "JSON inválido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "API Key ausente, inválida o revocada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Cuenta, verificación o permisos insuficientes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No se encontraron resultados", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Método no admitido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Cuerpo demasiado grande", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "415": { "description": "Content-Type no admitido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Parámetros inválidos", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Límite por minuto o cuota del periodo agotada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Error interno", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Error del proveedor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Servicio no disponible o pendiente de configuración", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "Tiempo de espera agotado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/licencia": { "post": { "operationId": "consultar_licencia", "summary": "Licencia de conducir", "description": "Licencia de conducir mediante una consulta autenticada.", "tags": [ "personas" ], "externalDocs": { "url": "https://datosperu.net/docs/licencia" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "dni" ], "properties": { "dni": { "type": "string", "description": "El DNI a consultar", "pattern": "^[0-9]{8}$", "maxLength": 200, "minLength": 1 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Consulta exitosa. Los campos opcionales dependen de la fuente; un resultado no equivale a una certificación oficial.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "meta" ], "additionalProperties": false, "properties": { "success": { "const": true }, "data": { "type": [ "object", "null" ], "description": "Datos detallados de la respuesta", "properties": { "numero_documento": { "type": [ "string", "null" ], "description": "Numero de documento" }, "nombres": { "type": [ "string", "null" ], "description": "Nombres" }, "apellido_paterno": { "type": [ "string", "null" ], "description": "Apellido paterno" }, "apellido_materno": { "type": [ "string", "null" ], "description": "Apellido materno" }, "grupo_sanguineo": { "type": [ "string", "null" ], "description": "Grupo sanguineo" }, "donacion_organos": { "type": [ "string", "null" ], "description": "Donación de organos" }, "licencia": { "type": [ "array", "null" ], "description": "Licencias de su dni" } }, "additionalProperties": false }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "description": "JSON inválido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "API Key ausente, inválida o revocada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Cuenta, verificación o permisos insuficientes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No se encontraron resultados", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Método no admitido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Cuerpo demasiado grande", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "415": { "description": "Content-Type no admitido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Parámetros inválidos", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Límite por minuto o cuota del periodo agotada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Error interno", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Error del proveedor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Servicio no disponible o pendiente de configuración", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "Tiempo de espera agotado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/ruc": { "post": { "operationId": "consultar_ruc", "summary": "Consulta RUC", "description": "Consulta RUC mediante una consulta autenticada.", "tags": [ "empresas" ], "externalDocs": { "url": "https://datosperu.net/docs/ruc" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "ruc" ], "properties": { "ruc": { "type": "string", "description": "El RUC a consultar", "pattern": "^[0-9]{11}$", "maxLength": 200, "minLength": 1 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Consulta exitosa. Los campos opcionales dependen de la fuente; un resultado no equivale a una certificación oficial.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "meta" ], "additionalProperties": false, "properties": { "success": { "const": true }, "data": { "type": "object", "additionalProperties": false, "properties": { "ruc": { "type": [ "string", "null" ], "description": "Número de identificación (RUC)" }, "razon_social": { "type": [ "string", "null" ], "description": "Nombre o Razon Social de la empresa" }, "estado": { "type": [ "string", "null" ], "description": "Estado de la empresa" }, "condicion": { "type": [ "string", "null" ], "description": "Condición de la empresa" }, "direccion": { "type": [ "string", "null" ], "description": "Dirección específica" }, "departamento": { "type": [ "string", "null" ], "description": "Departamento de la empresa" }, "provincia": { "type": [ "string", "null" ], "description": "Provincia de la empresa" }, "distrito": { "type": [ "string", "null" ], "description": "Distrito de la empresa" }, "ubigeo": { "type": [ "string", "null" ], "description": "Ubigeo según SUNAT" } } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "description": "JSON inválido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "API Key ausente, inválida o revocada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Cuenta, verificación o permisos insuficientes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No se encontraron resultados", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Método no admitido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Cuerpo demasiado grande", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "415": { "description": "Content-Type no admitido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Parámetros inválidos", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Límite por minuto o cuota del periodo agotada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Error interno", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Error del proveedor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Servicio no disponible o pendiente de configuración", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "Tiempo de espera agotado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/ruc/representantes": { "post": { "operationId": "consultar_ruc_representantes", "summary": "Representantes legales", "description": "Representantes legales mediante una consulta autenticada.", "tags": [ "empresas" ], "externalDocs": { "url": "https://datosperu.net/docs/ruc/representantes" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "ruc" ], "properties": { "ruc": { "type": "string", "description": "El RUC a consultar", "pattern": "^[0-9]{11}$", "maxLength": 200, "minLength": 1 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Consulta exitosa. Los campos opcionales dependen de la fuente; un resultado no equivale a una certificación oficial.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "meta" ], "additionalProperties": false, "properties": { "success": { "const": true }, "data": { "type": [ "array", "null" ], "description": "Datos detallados de la respuesta", "items": { "type": [ "object", "null" ], "properties": { "tipo_de_documento": { "type": [ "string", "null" ], "description": "Tipo de documento del representate" }, "numero_de_documento": { "type": [ "string", "null" ], "description": "Numero de documento del representante" }, "nombre": { "type": [ "string", "null" ], "description": "Nombre del representante" }, "cargo": { "type": [ "string", "null" ], "description": "Cargo del representate" }, "fecha_desde": { "type": [ "string", "null" ], "description": "Fecha desde" } }, "additionalProperties": false } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "description": "JSON inválido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "API Key ausente, inválida o revocada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Cuenta, verificación o permisos insuficientes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No se encontraron resultados", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Método no admitido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Cuerpo demasiado grande", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "415": { "description": "Content-Type no admitido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Parámetros inválidos", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Límite por minuto o cuota del periodo agotada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Error interno", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Error del proveedor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Servicio no disponible o pendiente de configuración", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "Tiempo de espera agotado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/ruc/establecimientos": { "post": { "operationId": "consultar_ruc_establecimientos", "summary": "Establecimientos", "description": "Establecimientos mediante una consulta autenticada.", "tags": [ "empresas" ], "externalDocs": { "url": "https://datosperu.net/docs/ruc/establecimientos" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "ruc" ], "properties": { "ruc": { "type": "string", "description": "El RUC a consultar", "pattern": "^[0-9]{11}$", "maxLength": 200, "minLength": 1 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Consulta exitosa. Los campos opcionales dependen de la fuente; un resultado no equivale a una certificación oficial.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "meta" ], "additionalProperties": false, "properties": { "success": { "const": true }, "data": { "type": [ "array", "null" ], "description": "Datos detallados de la respuesta", "items": { "type": [ "object", "null" ], "properties": { "codigo": { "type": [ "string", "null" ], "description": "Codigo del local" }, "tipo_establecimiento": { "type": [ "string", "null" ], "description": "Tipo de establecimiento del local" }, "actividad_economica": { "type": [ "string", "null" ], "description": "Actividad economica del local" }, "departamento": { "type": [ "string", "null" ], "description": "Departamento del local" }, "provincia": { "type": [ "string", "null" ], "description": "Provincia del local" }, "distrito": { "type": [ "string", "null" ], "description": "Distrito del local" }, "direccion": { "type": [ "string", "null" ], "description": "Dirección específica" }, "direccion_completa": { "type": [ "string", "null" ], "description": "Dirección completa, incluyendo distrito, provincia y departamento" }, "ubigeo_sunat": { "type": [ "string", "null" ], "description": "Ubigeo según SUNAT" }, "ubigeo": { "type": [ "array", "null" ], "description": "Ubigeo desglosado por componentes", "items": { "type": [ "string", "null" ] } } }, "additionalProperties": false } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "description": "JSON inválido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "API Key ausente, inválida o revocada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Cuenta, verificación o permisos insuficientes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No se encontraron resultados", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Método no admitido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Cuerpo demasiado grande", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "415": { "description": "Content-Type no admitido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Parámetros inválidos", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Límite por minuto o cuota del periodo agotada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Error interno", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Error del proveedor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Servicio no disponible o pendiente de configuración", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "Tiempo de espera agotado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/ruc/domicilio-fiscal": { "post": { "operationId": "consultar_ruc_domicilio_fiscal", "summary": "Domicilio fiscal", "description": "Domicilio fiscal mediante una consulta autenticada.", "tags": [ "empresas" ], "externalDocs": { "url": "https://datosperu.net/docs/ruc/domicilio-fiscal" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "ruc" ], "properties": { "ruc": { "type": "string", "description": "El RUC a consultar", "pattern": "^[0-9]{11}$", "maxLength": 200, "minLength": 1 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Consulta exitosa. Los campos opcionales dependen de la fuente; un resultado no equivale a una certificación oficial.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "meta" ], "additionalProperties": false, "properties": { "success": { "const": true }, "data": { "type": [ "object", "null" ], "description": "Datos del domicilio fiscal", "properties": { "codigo": { "type": [ "string", "null" ], "description": "Código del domicilio fiscal" }, "tipo_de_establecimiento": { "type": [ "string", "null" ], "description": "Tipo de establecimiento" }, "actividad_economica": { "type": [ "string", "null" ], "description": "Actividad económica" }, "direccion": { "type": [ "string", "null" ], "description": "Dirección específica" }, "direccion_completa": { "type": [ "string", "null" ], "description": "Dirección completa, incluyendo distrito, provincia y departamento" }, "departamento": { "type": [ "string", "null" ], "description": "Departamento" }, "provincia": { "type": [ "string", "null" ], "description": "Provincia" }, "distrito": { "type": [ "string", "null" ], "description": "Distrito" }, "ubigeo_sunat": { "type": [ "string", "null" ], "description": "Ubigeo según SUNAT" }, "ubigeo": { "type": [ "array", "null" ], "description": "Ubigeo desglosado por componentes", "items": { "type": [ "string", "null" ] } } }, "additionalProperties": false }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "description": "JSON inválido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "API Key ausente, inválida o revocada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Cuenta, verificación o permisos insuficientes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No se encontraron resultados", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Método no admitido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Cuerpo demasiado grande", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "415": { "description": "Content-Type no admitido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Parámetros inválidos", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Límite por minuto o cuota del periodo agotada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Error interno", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Error del proveedor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Servicio no disponible o pendiente de configuración", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "Tiempo de espera agotado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/ruc/deuda-coactiva": { "post": { "operationId": "consultar_ruc_deuda_coactiva", "summary": "Deuda coactiva", "description": "Deuda coactiva mediante una consulta autenticada.", "tags": [ "empresas" ], "externalDocs": { "url": "https://datosperu.net/docs/ruc/deuda-coactiva" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "ruc" ], "properties": { "ruc": { "type": "string", "description": "El RUC a consultar", "pattern": "^[0-9]{11}$", "maxLength": 200, "minLength": 1 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Consulta exitosa. Los campos opcionales dependen de la fuente; un resultado no equivale a una certificación oficial.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "meta" ], "additionalProperties": false, "properties": { "success": { "const": true }, "data": { "type": [ "array", "null" ], "description": "Lista de deudas coactivas", "items": { "type": [ "object", "null" ], "properties": { "monto": { "type": [ "string", "null" ], "description": "Monto de la deuda coactiva" }, "periodo_tibutario": { "type": [ "string", "null" ], "description": "Período tributario" }, "fecha_inicio_cobranza": { "type": [ "string", "null" ], "description": "Fecha de inicio de cobranza en formato yyyy-mm-dd" }, "entidad_asociada": { "type": [ "string", "null" ], "description": "Entidad asociada a la deuda" } }, "additionalProperties": false } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "description": "JSON inválido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "API Key ausente, inválida o revocada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Cuenta, verificación o permisos insuficientes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No se encontraron resultados", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Método no admitido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Cuerpo demasiado grande", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "415": { "description": "Content-Type no admitido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Parámetros inválidos", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Límite por minuto o cuota del periodo agotada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Error interno", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Error del proveedor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Servicio no disponible o pendiente de configuración", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "Tiempo de espera agotado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/ruc/trabajadores": { "post": { "operationId": "consultar_ruc_trabajadores", "summary": "Trabajadores", "description": "Trabajadores mediante una consulta autenticada.", "tags": [ "empresas" ], "externalDocs": { "url": "https://datosperu.net/docs/ruc/trabajadores" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "ruc" ], "properties": { "ruc": { "type": "string", "description": "El RUC a consultar", "pattern": "^[0-9]{11}$", "maxLength": 200, "minLength": 1 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Consulta exitosa. Los campos opcionales dependen de la fuente; un resultado no equivale a una certificación oficial.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "meta" ], "additionalProperties": false, "properties": { "success": { "const": true }, "data": { "type": [ "array", "null" ], "description": "Serie histórica por período (año-mes)", "items": { "type": [ "object", "null" ], "properties": { "periodo": { "type": [ "string", "null" ], "description": "Período en formato YYYY-MM" }, "numero_trabajadores": { "type": [ "string", "null" ], "description": "Número de trabajadores declarados" }, "numero_pensionistas": { "type": [ "string", "null" ], "description": "Número de pensionistas" }, "numero_prestadores_de_servicio": { "type": [ "string", "null" ], "description": "Número de prestadores de servicio" } }, "additionalProperties": false } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "description": "JSON inválido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "API Key ausente, inválida o revocada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Cuenta, verificación o permisos insuficientes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No se encontraron resultados", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Método no admitido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Cuerpo demasiado grande", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "415": { "description": "Content-Type no admitido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Parámetros inválidos", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Límite por minuto o cuota del periodo agotada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Error interno", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Error del proveedor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Servicio no disponible o pendiente de configuración", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "Tiempo de espera agotado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/ruc/omisiones": { "post": { "operationId": "consultar_ruc_omisiones", "summary": "Omisiones tributarias", "description": "Omisiones tributarias mediante una consulta autenticada.", "tags": [ "empresas" ], "externalDocs": { "url": "https://datosperu.net/docs/ruc/omisiones" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "ruc" ], "properties": { "ruc": { "type": "string", "description": "El RUC a consultar", "pattern": "^[0-9]{11}$", "maxLength": 200, "minLength": 1 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Consulta exitosa. Los campos opcionales dependen de la fuente; un resultado no equivale a una certificación oficial.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "meta" ], "additionalProperties": false, "properties": { "success": { "const": true }, "data": { "type": [ "array", "null" ], "description": "Lista de períodos omisos. Es null cuando no hay omisiones o cuando ocurre un error.", "items": { "type": [ "object", "null" ], "properties": { "periodo": { "type": [ "string", "null" ], "description": "Período en formato YYYYMM" }, "tipo": { "type": [ "string", "null" ], "description": "Tipo de declaración omisa (ej. PDT IGV - Renta)" }, "fecha_presentacion": { "type": [ "string", "null" ], "description": "Fecha de presentación. Puede ser \"-\" si no se presentó" } }, "additionalProperties": false } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "description": "JSON inválido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "API Key ausente, inválida o revocada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Cuenta, verificación o permisos insuficientes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No se encontraron resultados", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Método no admitido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Cuerpo demasiado grande", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "415": { "description": "Content-Type no admitido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Parámetros inválidos", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Límite por minuto o cuota del periodo agotada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Error interno", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Error del proveedor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Servicio no disponible o pendiente de configuración", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "Tiempo de espera agotado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/ruc/razon-social": { "post": { "operationId": "consultar_ruc_razon_social", "summary": "Razón social", "description": "Razón social mediante una consulta autenticada.", "tags": [ "empresas" ], "externalDocs": { "url": "https://datosperu.net/docs/ruc/razon-social" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "razon_social" ], "properties": { "razon_social": { "type": "string", "description": "La razón social a buscar", "maxLength": 200, "minLength": 1 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Consulta exitosa. Los campos opcionales dependen de la fuente; un resultado no equivale a una certificación oficial.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "meta" ], "additionalProperties": false, "properties": { "success": { "const": true }, "data": { "type": [ "array", "null" ], "description": "Lista de empresas que coinciden con la razón social", "items": { "type": [ "object", "null" ], "properties": { "ruc": { "type": [ "string", "null" ], "description": "RUC de la empresa" }, "nombre_o_razon_social": { "type": [ "string", "null" ], "description": "Nombre o razón social de la empresa" }, "ubicacion": { "type": [ "string", "null" ], "description": "Ubicación de la empresa" }, "estado": { "type": [ "string", "null" ], "description": "Estado de la empresa (ACTIVO, etc.)" } }, "additionalProperties": false } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "description": "JSON inválido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "API Key ausente, inválida o revocada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Cuenta, verificación o permisos insuficientes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No se encontraron resultados", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Método no admitido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Cuerpo demasiado grande", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "415": { "description": "Content-Type no admitido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Parámetros inválidos", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Límite por minuto o cuota del periodo agotada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Error interno", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Error del proveedor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Servicio no disponible o pendiente de configuración", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "Tiempo de espera agotado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/sunat/cpe": { "post": { "operationId": "consultar_sunat_cpe", "summary": "Consulta CPE", "description": "Consulta CPE mediante una consulta autenticada.", "tags": [ "sunat" ], "externalDocs": { "url": "https://datosperu.net/docs/sunat/cpe" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ruc_emisor": { "type": "string", "description": "RUC Emisor del comprobante", "pattern": "^[0-9]{11}$", "maxLength": 200, "minLength": 1 }, "codigo_tipo_documento": { "type": "string", "description": "Tipo Documento del comprobante", "maxLength": 200, "minLength": 1 }, "serie_documento": { "type": "string", "description": "Serie del comprobante", "maxLength": 200, "minLength": 1 }, "numero_documento": { "type": "string", "description": "Correlativo del comprobante", "maxLength": 200, "minLength": 1 }, "fecha_de_emision": { "type": "string", "description": "Debe tener el formato dd/mm/yyyy", "maxLength": 200, "minLength": 1 }, "total": { "type": "string", "description": "Total del comprobante", "maxLength": 200, "minLength": 1 } }, "additionalProperties": false, "required": [ "ruc_emisor", "codigo_tipo_documento", "serie_documento", "numero_documento", "fecha_de_emision", "total" ] } } } }, "responses": { "200": { "description": "Consulta exitosa. Los campos opcionales dependen de la fuente; un resultado no equivale a una certificación oficial.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "meta" ], "additionalProperties": false, "properties": { "success": { "const": true }, "data": { "type": [ "object", "null" ], "description": "Datos detallados de la respuesta", "properties": { "ruc_emisor": { "type": [ "string", "null" ], "description": "RUC del emisor del comprobante" }, "codigo_tipo_documento": { "type": [ "string", "null" ], "description": "Código del tipo de documento (ej. 01, 03)" }, "serie_documento": { "type": [ "string", "null" ], "description": "Serie del comprobante" }, "numero_documento": { "type": [ "string", "null" ], "description": "Número del comprobante" }, "fecha_de_emision": { "type": [ "string", "null" ], "description": "Fecha de emisión del comprobante en formato dd/mm/yyyy" }, "total": { "type": [ "number", "null" ], "description": "Importe total declarado en el comprobante" }, "comprobante_estado_codigo": { "type": [ "string", "null" ], "description": "Código del estado del comprobante" }, "comprobante_estado_descripcion": { "type": [ "string", "null" ], "description": "Descripción del estado del comprobante" }, "empresa_estado_codigo": { "type": [ "string", "null" ], "description": "Código del estado del contribuyente emisor" }, "empresa_estado_description": { "type": [ "string", "null" ], "description": "Descripción del estado del contribuyente emisor" }, "empresa_condicion_codigo": { "type": [ "string", "null" ], "description": "Código de la condición del contribuyente emisor" }, "empresa_condicion_descripcion": { "type": [ "string", "null" ], "description": "Descripción de la condición del contribuyente emisor" }, "observaciones": { "type": [ "array", "null" ], "description": "Observaciones reportadas por SUNAT", "items": { "type": [ "string", "null" ] } } }, "additionalProperties": false }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "description": "JSON inválido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "API Key ausente, inválida o revocada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Cuenta, verificación o permisos insuficientes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No se encontraron resultados", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Método no admitido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Cuerpo demasiado grande", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "415": { "description": "Content-Type no admitido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Parámetros inválidos", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Límite por minuto o cuota del periodo agotada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Error interno", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Error del proveedor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Servicio no disponible o pendiente de configuración", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "Tiempo de espera agotado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/sunat/xml": { "post": { "operationId": "consultar_sunat_xml", "summary": "Descargar XML", "description": "Descargar XML mediante una consulta autenticada.", "tags": [ "sunat" ], "externalDocs": { "url": "https://datosperu.net/docs/sunat/xml" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "ruc", "usuario", "password", "proveedor", "tipo_doc", "serie", "correlativo" ], "properties": { "ruc": { "type": "string", "description": "RUC de la empresa", "pattern": "^[0-9]{11}$", "maxLength": 200, "minLength": 1 }, "usuario": { "type": "string", "description": "Usuario SOL", "maxLength": 200, "minLength": 1 }, "password": { "type": "string", "description": "Contraseña SOL", "maxLength": 200, "minLength": 1 }, "proveedor": { "type": "string", "description": "RUC del emisor del comprobante. Si es una venta (comprobante emitido por tu empresa), usa el mismo valor que el campo ruc. Si es una compra (comprobante que te emitió un tercero), indica el RUC de la empresa que te emitió la factura.", "pattern": "^[0-9]{11}$", "maxLength": 200, "minLength": 1 }, "tipo_doc": { "type": "string", "description": "Tipo de documento", "maxLength": 200, "minLength": 1 }, "serie": { "type": "string", "description": "Serie del comprobante", "maxLength": 200, "minLength": 1 }, "correlativo": { "type": "string", "description": "Número correlativo", "maxLength": 200, "minLength": 1 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Consulta exitosa. Los campos opcionales dependen de la fuente; un resultado no equivale a una certificación oficial.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "meta" ], "additionalProperties": false, "properties": { "success": { "const": true }, "data": { "type": [ "object", "null" ], "description": "Archivo ZIP en Base64 con el PDF del comprobante", "properties": { "pdf_base64": { "type": [ "string", "null" ], "description": "Archivo ZIP codificado en Base64 que contiene el PDF generado" } }, "additionalProperties": false }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "description": "JSON inválido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "API Key ausente, inválida o revocada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Cuenta, verificación o permisos insuficientes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No se encontraron resultados", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Método no admitido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Cuerpo demasiado grande", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "415": { "description": "Content-Type no admitido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Parámetros inválidos", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Límite por minuto o cuota del periodo agotada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Error interno", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Error del proveedor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Servicio no disponible o pendiente de configuración", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "Tiempo de espera agotado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/sunat/xml-pdf": { "post": { "operationId": "consultar_sunat_xml_pdf", "summary": "XML a PDF", "description": "XML a PDF mediante una consulta autenticada.", "tags": [ "sunat" ], "externalDocs": { "url": "https://datosperu.net/docs/sunat/xml-pdf" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "file_base64" ], "properties": { "file_base64": { "type": "string", "description": "Archivo XML codificado en base64", "maxLength": 1000000, "minLength": 1 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Consulta exitosa. Los campos opcionales dependen de la fuente; un resultado no equivale a una certificación oficial.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "meta" ], "additionalProperties": false, "properties": { "success": { "const": true }, "data": { "type": [ "object", "null" ], "description": "Archivo ZIP en Base64 con el PDF del comprobante", "properties": { "pdf_base64": { "type": [ "string", "null" ], "description": "Archivo ZIP codificado en Base64 que contiene el PDF generado" } }, "additionalProperties": false }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "description": "JSON inválido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "API Key ausente, inválida o revocada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Cuenta, verificación o permisos insuficientes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No se encontraron resultados", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Método no admitido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Cuerpo demasiado grande", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "415": { "description": "Content-Type no admitido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Parámetros inválidos", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Límite por minuto o cuota del periodo agotada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Error interno", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Error del proveedor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Servicio no disponible o pendiente de configuración", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "Tiempo de espera agotado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/sunat/guia/xml": { "get": { "operationId": "consultar_sunat_guia_xml", "summary": "Guía XML", "description": "Guía XML mediante una consulta autenticada.", "tags": [ "sunat" ], "externalDocs": { "url": "https://datosperu.net/docs/sunat/guia/xml" }, "parameters": [ { "name": "numRuc", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[0-9]{11}$", "maxLength": 200, "minLength": 1 } }, { "name": "tipoDocumento", "in": "query", "required": true, "schema": { "type": "string", "maxLength": 200, "minLength": 1 } }, { "name": "numSerieComprobante", "in": "query", "required": true, "schema": { "type": "string", "maxLength": 200, "minLength": 1 } }, { "name": "numDocumentoComprobante", "in": "query", "required": true, "schema": { "type": "string", "maxLength": 200, "minLength": 1 } } ], "responses": { "200": { "description": "Consulta exitosa. Los campos opcionales dependen de la fuente; un resultado no equivale a una certificación oficial.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "meta" ], "additionalProperties": false, "properties": { "success": { "const": true }, "data": { "type": "object", "required": [ "content_base64", "mime_type" ], "additionalProperties": false, "properties": { "content_base64": { "type": [ "string", "null" ], "contentEncoding": "base64" }, "mime_type": { "type": "string", "const": "application/xml" } } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "description": "JSON inválido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "API Key ausente, inválida o revocada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Cuenta, verificación o permisos insuficientes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No se encontraron resultados", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Método no admitido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Cuerpo demasiado grande", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "415": { "description": "Content-Type no admitido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Parámetros inválidos", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Límite por minuto o cuota del periodo agotada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Error interno", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Error del proveedor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Servicio no disponible o pendiente de configuración", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "Tiempo de espera agotado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/sunat/guia/json": { "get": { "operationId": "consultar_sunat_guia_json", "summary": "Guía JSON", "description": "Guía JSON mediante una consulta autenticada.", "tags": [ "sunat" ], "externalDocs": { "url": "https://datosperu.net/docs/sunat/guia/json" }, "parameters": [ { "name": "numRuc", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[0-9]{11}$", "maxLength": 200, "minLength": 1 } }, { "name": "tipoDocumento", "in": "query", "required": true, "schema": { "type": "string", "maxLength": 200, "minLength": 1 } }, { "name": "numSerieComprobante", "in": "query", "required": true, "schema": { "type": "string", "maxLength": 200, "minLength": 1 } }, { "name": "numDocumentoComprobante", "in": "query", "required": true, "schema": { "type": "string", "maxLength": 200, "minLength": 1 } } ], "responses": { "200": { "description": "Consulta exitosa. Los campos opcionales dependen de la fuente; un resultado no equivale a una certificación oficial.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "meta" ], "additionalProperties": false, "properties": { "success": { "const": true }, "data": { "type": [ "object", "null" ], "description": "Datos detallados de la respuesta" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "description": "JSON inválido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "API Key ausente, inválida o revocada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Cuenta, verificación o permisos insuficientes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No se encontraron resultados", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Método no admitido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Cuerpo demasiado grande", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "415": { "description": "Content-Type no admitido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Parámetros inválidos", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Límite por minuto o cuota del periodo agotada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Error interno", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Error del proveedor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Servicio no disponible o pendiente de configuración", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "Tiempo de espera agotado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/vehiculo/placa": { "post": { "operationId": "consultar_vehiculo_placa", "summary": "Consulta por placa", "description": "Consulta por placa mediante una consulta autenticada.", "tags": [ "vehiculos" ], "externalDocs": { "url": "https://datosperu.net/docs/vehiculo/placa" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "placa" ], "properties": { "placa": { "type": "string", "description": "La placa a consultar", "pattern": "^[A-Za-z0-9-]{5,9}$", "maxLength": 200, "minLength": 1 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Consulta exitosa. Los campos opcionales dependen de la fuente; un resultado no equivale a una certificación oficial.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "meta" ], "additionalProperties": false, "properties": { "success": { "const": true }, "data": { "type": [ "object", "null" ], "description": "Datos detallados de la respuesta", "properties": { "placa": { "type": [ "string", "null" ], "description": "Placa del vehiculo" }, "marca": { "type": [ "string", "null" ], "description": "Marca del vehiculo" }, "modelo": { "type": [ "string", "null" ], "description": "Modelo del vehiculo" }, "serie": { "type": [ "string", "null" ], "description": "Serie del vehiculo" }, "color": { "type": [ "string", "null" ], "description": "Color del vehiculo" }, "motor": { "type": [ "string", "null" ], "description": "Motor del vehiculo" }, "vin": { "type": [ "string", "null" ], "description": "VIN del vehiculo" } }, "additionalProperties": false }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "description": "JSON inválido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "API Key ausente, inválida o revocada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Cuenta, verificación o permisos insuficientes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No se encontraron resultados", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Método no admitido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Cuerpo demasiado grande", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "415": { "description": "Content-Type no admitido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Parámetros inválidos", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Límite por minuto o cuota del periodo agotada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Error interno", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Error del proveedor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Servicio no disponible o pendiente de configuración", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "Tiempo de espera agotado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/soat": { "post": { "operationId": "consultar_soat", "summary": "SOAT por placa", "description": "SOAT por placa mediante una consulta autenticada.", "tags": [ "vehiculos" ], "externalDocs": { "url": "https://datosperu.net/docs/soat" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "placa" ], "properties": { "placa": { "type": "string", "description": "La placa a consultar", "pattern": "^[A-Za-z0-9-]{5,9}$", "maxLength": 200, "minLength": 1 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Consulta exitosa. Los campos opcionales dependen de la fuente; un resultado no equivale a una certificación oficial.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "meta" ], "additionalProperties": false, "properties": { "success": { "const": true }, "data": { "type": [ "object", "null" ], "description": "Datos detallados de la respuesta", "properties": { "placa": { "type": [ "string", "null" ], "description": "Placa del vehiculo" }, "nombre_compania": { "type": [ "string", "null" ], "description": "Nombre de la compañia" }, "fecha_inicio": { "type": [ "string", "null" ], "description": "Fecha de Inicio" }, "fecha_fin": { "type": [ "string", "null" ], "description": "Fecha Fin" }, "estado": { "type": [ "string", "null" ], "description": "Estado del SOAT" }, "numero_poliza": { "type": [ "string", "null" ], "description": "Numero de Poliza" } }, "additionalProperties": false }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "description": "JSON inválido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "API Key ausente, inválida o revocada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Cuenta, verificación o permisos insuficientes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No se encontraron resultados", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Método no admitido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Cuerpo demasiado grande", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "415": { "description": "Content-Type no admitido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Parámetros inválidos", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Límite por minuto o cuota del periodo agotada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Error interno", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Error del proveedor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Servicio no disponible o pendiente de configuración", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "Tiempo de espera agotado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/vehiculo/revision-tecnica": { "post": { "operationId": "consultar_vehiculo_revision_tecnica", "summary": "Revisión técnica", "description": "Revisión técnica mediante una consulta autenticada.", "tags": [ "vehiculos" ], "externalDocs": { "url": "https://datosperu.net/docs/vehiculo/revision-tecnica" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "placa" ], "properties": { "placa": { "type": "string", "description": "La placa a consultar", "pattern": "^[A-Za-z0-9-]{5,9}$", "maxLength": 200, "minLength": 1 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Consulta exitosa. Los campos opcionales dependen de la fuente; un resultado no equivale a una certificación oficial.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "meta" ], "additionalProperties": false, "properties": { "success": { "const": true }, "data": { "type": [ "array", "null" ], "description": "Historial de revisiones técnicas del vehículo", "items": { "type": [ "object", "null" ], "properties": { "placa": { "type": [ "string", "null" ], "description": "Placa del vehículo" }, "tipo_documento": { "type": [ "string", "null" ], "description": "Tipo de documento (NRO DE CERTIFICADO, NRO DE INFORME)" }, "numero_certificado": { "type": [ "string", "null" ], "description": "Número de certificado o informe" }, "vigente_desde": { "type": [ "string", "null" ], "description": "Fecha de inicio de vigencia" }, "vigente_hasta": { "type": [ "string", "null" ], "description": "Fecha de fin de vigencia" }, "resultado_inspeccion": { "type": [ "string", "null" ], "description": "Resultado de la inspección (APROBADO, DESAPROBADO)" }, "estado": { "type": [ "string", "null" ], "description": "Estado del certificado (VENCIDO, VIGENTE, etc.)" }, "empresa_certificadora": { "type": [ "string", "null" ], "description": "Nombre de la empresa certificadora" }, "direccion": { "type": [ "string", "null" ], "description": "Dirección del centro de inspección" }, "ambito": { "type": [ "string", "null" ], "description": "Ámbito de la inspección" }, "tipo_servicio": { "type": [ "string", "null" ], "description": "Tipo de servicio del vehículo (PARTICULAR, etc.)" }, "observaciones": { "type": [ "string", "null" ], "description": "Observaciones de la inspección" }, "orden": { "type": [ "string", "null" ], "description": "Orden cronológico del registro (ULTIMO, PENULTIMO, ANTEPENULTIMO)" } }, "additionalProperties": false } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "description": "JSON inválido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "API Key ausente, inválida o revocada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Cuenta, verificación o permisos insuficientes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No se encontraron resultados", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Método no admitido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Cuerpo demasiado grande", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "415": { "description": "Content-Type no admitido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Parámetros inválidos", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Límite por minuto o cuota del periodo agotada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Error interno", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Error del proveedor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Servicio no disponible o pendiente de configuración", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "Tiempo de espera agotado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/tipo-cambio": { "post": { "operationId": "consultar_tipo_cambio", "summary": "Tipo de cambio", "description": "Tipo de cambio mediante una consulta autenticada.", "tags": [ "finanzas" ], "externalDocs": { "url": "https://datosperu.net/docs/tipo-cambio" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "fecha" ], "properties": { "fecha": { "type": "string", "description": "Fecha de consulta en formato yyyy-mm-dd", "format": "date", "maxLength": 200, "minLength": 1 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Consulta exitosa. Los campos opcionales dependen de la fuente; un resultado no equivale a una certificación oficial.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "meta" ], "additionalProperties": false, "properties": { "success": { "const": true }, "data": { "type": "object", "additionalProperties": false, "properties": { "moneda": { "type": [ "string", "null" ], "description": "Código de la moneda consultada" }, "fecha": { "type": [ "string", "null" ], "description": "Última fecha disponible en SUNAT" }, "compra": { "type": [ "number", "null" ], "description": "Tipo de cambio compra" }, "venta": { "type": [ "number", "null" ], "description": "Tipo de cambio venta" } } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "description": "JSON inválido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "API Key ausente, inválida o revocada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Cuenta, verificación o permisos insuficientes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No se encontraron resultados", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Método no admitido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Cuerpo demasiado grande", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "415": { "description": "Content-Type no admitido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Parámetros inválidos", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Límite por minuto o cuota del periodo agotada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Error interno", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Error del proveedor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Servicio no disponible o pendiente de configuración", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "Tiempo de espera agotado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/afp": { "post": { "operationId": "consultar_afp", "summary": "Comisiones AFP", "description": "Comisiones AFP mediante una consulta autenticada.", "tags": [ "finanzas" ], "externalDocs": { "url": "https://datosperu.net/docs/afp" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "periodo" ], "properties": { "periodo": { "type": "string", "description": "Periodo de consulta en formato yyyy-MM", "pattern": "^[0-9]{4}-[0-9]{2}$", "maxLength": 200, "minLength": 1 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Consulta exitosa. Los campos opcionales dependen de la fuente; un resultado no equivale a una certificación oficial.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "meta" ], "additionalProperties": false, "properties": { "success": { "const": true }, "data": { "type": [ "array", "null" ], "description": "Listado de comisiones por AFP", "items": { "type": [ "object", "null" ], "properties": { "periodo": { "type": [ "string", "null" ], "description": "Periodo de la comisión en formato yyyy-MM" }, "afp": { "type": [ "string", "null" ], "description": "Nombre de la AFP" }, "comision_fija": { "type": [ "number", "null" ], "description": "Comisión fija (%)" }, "comision_flujo": { "type": [ "number", "null" ], "description": "Comisión por flujo (%)" }, "comision_mixta_flujo": { "type": [ "number", "null" ], "description": "Comisión mixta por flujo (%)" }, "comision_mixta_saldo": { "type": [ "number", "null" ], "description": "Comisión mixta por saldo (%)" }, "prima_de_seguro": { "type": [ "number", "null" ], "description": "Prima de seguro (%)" }, "aporte_obligatorio": { "type": [ "number", "null" ], "description": "Aporte obligatorio (%)" }, "remunaracion_maxima": { "type": [ "number", "null" ], "description": "Remuneración máxima asegurable (S/)" } }, "additionalProperties": false } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "description": "JSON inválido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "API Key ausente, inválida o revocada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Cuenta, verificación o permisos insuficientes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No se encontraron resultados", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Método no admitido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Cuerpo demasiado grande", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "415": { "description": "Content-Type no admitido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Parámetros inválidos", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Límite por minuto o cuota del periodo agotada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Error interno", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Error del proveedor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Servicio no disponible o pendiente de configuración", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "Tiempo de espera agotado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/recibos/luz-del-sur": { "post": { "operationId": "consultar_recibos_luz_del_sur", "summary": "Luz del Sur", "description": "Luz del Sur mediante una consulta autenticada.", "tags": [ "recibos" ], "externalDocs": { "url": "https://datosperu.net/docs/recibos/luz-del-sur" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "numero_suministro" ], "properties": { "numero_suministro": { "type": "string", "description": "Número de suministro del servicio (agua o luz)", "pattern": "^[A-Za-z0-9-]{1,20}$", "maxLength": 200, "minLength": 1 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Consulta exitosa. Los campos opcionales dependen de la fuente; un resultado no equivale a una certificación oficial.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "meta" ], "additionalProperties": false, "properties": { "success": { "const": true }, "data": { "type": "object", "required": [ "content_base64", "mime_type" ], "additionalProperties": false, "properties": { "content_base64": { "type": [ "string", "null" ], "contentEncoding": "base64" }, "mime_type": { "type": "string", "const": "image/jpeg" } } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "description": "JSON inválido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "API Key ausente, inválida o revocada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Cuenta, verificación o permisos insuficientes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No se encontraron resultados", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Método no admitido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Cuerpo demasiado grande", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "415": { "description": "Content-Type no admitido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Parámetros inválidos", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Límite por minuto o cuota del periodo agotada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Error interno", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Error del proveedor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Servicio no disponible o pendiente de configuración", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "Tiempo de espera agotado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/recibos/sedapal": { "post": { "operationId": "consultar_recibos_sedapal", "summary": "Sedapal", "description": "Sedapal mediante una consulta autenticada.", "tags": [ "recibos" ], "externalDocs": { "url": "https://datosperu.net/docs/recibos/sedapal" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "numero_suministro" ], "properties": { "numero_suministro": { "type": "string", "description": "Número de suministro del servicio (agua o luz)", "pattern": "^[A-Za-z0-9-]{1,20}$", "maxLength": 200, "minLength": 1 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Consulta exitosa. Los campos opcionales dependen de la fuente; un resultado no equivale a una certificación oficial.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data", "meta" ], "additionalProperties": false, "properties": { "success": { "const": true }, "data": { "type": "object", "required": [ "content_base64", "mime_type" ], "additionalProperties": false, "properties": { "content_base64": { "type": [ "string", "null" ], "contentEncoding": "base64" }, "mime_type": { "type": "string", "const": "image/jpeg" } } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "description": "JSON inválido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "API Key ausente, inválida o revocada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Cuenta, verificación o permisos insuficientes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No se encontraron resultados", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "405": { "description": "Método no admitido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "Cuerpo demasiado grande", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "415": { "description": "Content-Type no admitido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Parámetros inválidos", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Límite por minuto o cuota del periodo agotada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Error interno", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Error del proveedor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Servicio no disponible o pendiente de configuración", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "504": { "description": "Tiempo de espera agotado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } } } }