{
    "openapi": "3.1.0",
    "info": {
        "title": "FactosPerú API",
        "version": "1.1.0",
        "summary": "Consultas SUNAT, comprobantes, buzón SOL y datos públicos para integraciones de clientes.",
        "description": "API REST de FactosPerú para consultar SUNAT. **URL base de producción:** `https://api.factosperu.com`; todas las rutas canónicas cuelgan de `/api/v1`.\n\n**Autenticación:** token Bearer por cliente (`Authorization: Bearer <token>`), gestionado en el panel. Opcionalmente cada cliente puede limitar el acceso a una lista de IP.\n\n**Consumo:** cada consulta enviada al proveedor consume unidades del plan del ciclo vigente (1 por solicitud, o 1 por comprobante en los lotes). Al cambiar de plan dentro del ciclo se conserva el consumo y el nuevo límite reemplaza al anterior; las cuotas no se acumulan.\n\n**Límites:** además de la cuota del plan, cada cliente tiene un límite operativo por minuto (60 por defecto) que responde 429 con `Retry-After`.\n\n**Reintentos e idempotencia:** envíe `Idempotency-Key` para que un reintento de la misma solicitud no se cobre dos veces. Las respuestas de error incluyen `retryable`.\n\n**Versiones:** las rutas canónicas están bajo `/api/v1`. Los alias sin versión (`/api/ruc`, `/api/dni`, `/api/cpe`, `/api/validacion-multiple-cpe`) se conservan por compatibilidad y están marcados como obsoletos.\n\n**Datos sensibles:** la Clave SOL se reenvía al proveedor solo para la consulta y no se almacena ni registra. Use siempre HTTPS en producción.",
        "contact": {
            "name": "Soporte FactosPerú"
        }
    },
    "servers": [
        {
            "url": "https://api.factosperu.com",
            "description": "Producción · FactosPerú API"
        },
        {
            "url": "/",
            "description": "Mismo host que sirve esta documentación"
        }
    ],
    "security": [
        {
            "bearerAuth": []
        }
    ],
    "tags": [
        {
            "name": "Identidad",
            "description": "Consultas en línea de RUC y DNI."
        },
        {
            "name": "Consultas por GET",
            "description": "Consultas por GET"
        },
        {
            "name": "Comprobantes",
            "description": "Descarga y validación de comprobantes electrónicos con Clave SOL."
        },
        {
            "name": "Buzón SOL",
            "description": "Notificaciones y mensajes del buzón electrónico."
        },
        {
            "name": "Casilla SUNAFIL",
            "description": "Casilla SUNAFIL"
        },
        {
            "name": "Credenciales API SUNAT",
            "description": "Credenciales API SUNAT"
        },
        {
            "name": "SIRE",
            "description": "SIRE"
        },
        {
            "name": "Padrón y datos públicos",
            "description": "Padrón Reducido RUC y datasets oficiales importados (sin credenciales SOL)."
        },
        {
            "name": "Servicio",
            "description": "Estado del servicio."
        }
    ],
    "paths": {
        "/api/cpe": {
            "post": {
                "tags": [
                    "Comprobantes"
                ],
                "operationId": "cpeLegacy",
                "summary": "Consulta y descarga de CPE (alias sin versión)",
                "description": "Consulta comprobantes electrónicos con la Clave SOL del RUC y devuelve sus archivos PDF, XML y CDR en Base64.\n\n**Consumo:** 1 por comprobante del lote (máximo 100). Una consulta validada que se envía al proveedor consume cuota aunque el proveedor responda con error (ADR-005). Los rechazos de validación (422), autenticación, límite o duplicado no consumen.\n\n**Obsoleto:** alias temporal de `/api/v1/cpe` mantenido por compatibilidad; usar la ruta versionada.",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/IdempotencyKey"
                    }
                ],
                "deprecated": true,
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "ruc",
                                    "usuario_sol",
                                    "clave_sol",
                                    "comprobantes"
                                ],
                                "properties": {
                                    "ruc": {
                                        "type": "string",
                                        "pattern": "^\\d{11}$",
                                        "description": "RUC de 11 dígitos.",
                                        "example": "20123456789"
                                    },
                                    "usuario_sol": {
                                        "type": "string",
                                        "description": "Usuario SOL del RUC consultado. Se reenvía al proveedor y nunca se registra.",
                                        "example": "USUARIO_SOL"
                                    },
                                    "clave_sol": {
                                        "type": "string",
                                        "format": "password",
                                        "description": "Clave SOL. Se reenvía al proveedor y nunca se registra.",
                                        "example": "CLAVE_SOL"
                                    },
                                    "comprobantes": {
                                        "type": "array",
                                        "minItems": 1,
                                        "maxItems": 100,
                                        "items": {
                                            "type": "object",
                                            "description": "Comprobante a descargar. La API no valida su contenido.",
                                            "properties": {
                                                "tipo_consulta": {
                                                    "type": "string",
                                                    "example": "emitido"
                                                },
                                                "ruc_emisor": {
                                                    "type": "string",
                                                    "example": "20123456789"
                                                },
                                                "tipo": {
                                                    "type": "string",
                                                    "example": "01"
                                                },
                                                "serie": {
                                                    "type": "string",
                                                    "example": "F001"
                                                },
                                                "numero": {
                                                    "type": "string",
                                                    "example": "123"
                                                },
                                                "fecha": {
                                                    "type": "string",
                                                    "example": "FECHA_DE_EMISION"
                                                },
                                                "monto": {
                                                    "type": "string",
                                                    "example": "MONTO_DEL_COMPROBANTE"
                                                }
                                            },
                                            "additionalProperties": true
                                        }
                                    }
                                }
                            },
                            "example": {
                                "ruc": "20123456789",
                                "usuario_sol": "USUARIO_SOL",
                                "clave_sol": "CLAVE_SOL",
                                "comprobantes": [
                                    {
                                        "tipo_consulta": "emitido",
                                        "ruc_emisor": "20123456789",
                                        "tipo": "01",
                                        "serie": "F001",
                                        "numero": "123",
                                        "fecha": "FECHA_DE_EMISION",
                                        "monto": "MONTO_DEL_COMPROBANTE"
                                    }
                                ]
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Consulta resuelta.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/SuccessEnvelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "additionalProperties": true
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "success": true,
                                    "code": "found",
                                    "retryable": false,
                                    "data": {
                                        "total": 1,
                                        "exitosos": 1,
                                        "fallidos": 0,
                                        "comprobantes": [
                                            {
                                                "id": "1",
                                                "estado": "ok",
                                                "tipo": "01",
                                                "serie": "F001",
                                                "numero": "123",
                                                "fecha_emision": "FECHA_DE_EMISION",
                                                "total": "MONTO",
                                                "moneda": "PEN",
                                                "estado_cpe": "CODIGO_PROVEEDOR",
                                                "emisor": {
                                                    "ruc": "20123456789",
                                                    "razon_social": "EMPRESA DEMOSTRACION S.A.C.",
                                                    "direccion": "AV. EJEMPLO 123"
                                                },
                                                "receptor": {
                                                    "documento": "20987654321",
                                                    "razon_social": "CLIENTE DEMOSTRACION S.A."
                                                },
                                                "items": [],
                                                "archivos": {
                                                    "pdf": {
                                                        "ok": true,
                                                        "nombre": "F001-123.pdf",
                                                        "es_zip": false,
                                                        "contenido_base64": "BASE64",
                                                        "tamano_kb": 12.5
                                                    },
                                                    "xml": {
                                                        "ok": false,
                                                        "error": "No disponible"
                                                    },
                                                    "cdr": {
                                                        "ok": false,
                                                        "error": "No disponible"
                                                    }
                                                }
                                            }
                                        ]
                                    },
                                    "time": 0.42
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "409": {
                        "$ref": "#/components/responses/DuplicateRequest"
                    },
                    "422": {
                        "description": "Campos superiores inválidos (RUC no numérico, lote vacío o mayor a 100).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorEnvelope"
                                }
                            }
                        }
                    },
                    "429": {
                        "$ref": "#/components/responses/TooManyRequests"
                    },
                    "500": {
                        "description": "El proveedor informó un error global (`cpe_error`, reintentable).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorEnvelope"
                                }
                            }
                        }
                    },
                    "502": {
                        "description": "El servicio de consultas no pudo completar la solicitud (`servicio_error`, `retryable: true`).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorEnvelope"
                                }
                            }
                        }
                    },
                    "503": {
                        "description": "El servicio de consultas no está disponible (`servicio_no_disponible`, `retryable: true`). Reintente en unos segundos. También `rate_limit_unavailable` si el contador de límites no está disponible.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "oneOf": [
                                        {
                                            "$ref": "#/components/schemas/ErrorEnvelope"
                                        },
                                        {
                                            "$ref": "#/components/schemas/AccessError"
                                        }
                                    ]
                                }
                            }
                        }
                    }
                },
                "x-consumo-unidades": "1 por comprobante del lote (máximo 100)",
                "x-estado-verificacion": "pendiente_validacion_externa"
            }
        },
        "/api/dni": {
            "post": {
                "tags": [
                    "Identidad"
                ],
                "operationId": "dniLegacy",
                "summary": "Consulta DNI (alias sin versión)",
                "description": "Consulta el nombre asociado a un DNI por un solo filtro: primero el Padrón Reducido por el RUC 10 de la persona (`source: padron_reducido`) y, si no está, el portal público de SUNAT en línea (`source: sunat_en_linea`). Solo se encuentran personas registradas como contribuyentes en SUNAT. La respuesta trae apellidos y nombres por separado.\n\n**Consumo:** 1 por solicitud. Una consulta validada que se envía al proveedor consume cuota aunque el proveedor responda con error (ADR-005). Los rechazos de validación (422), autenticación, límite o duplicado no consumen.\n\n**Obsoleto:** alias temporal de `/api/v1/dni` mantenido por compatibilidad; usar la ruta versionada.",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/IdempotencyKey"
                    }
                ],
                "deprecated": true,
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "dni"
                                ],
                                "properties": {
                                    "dni": {
                                        "type": "string",
                                        "pattern": "^\\d{8}$",
                                        "example": "12345678"
                                    }
                                }
                            },
                            "example": {
                                "dni": "12345678"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Consulta resuelta.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/SuccessEnvelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "additionalProperties": true
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "success": true,
                                    "code": "found",
                                    "retryable": false,
                                    "data": {
                                        "numero": "12345678",
                                        "nombre_completo": "PEREZ LOPEZ ANA MARIA",
                                        "nombres": "ANA MARIA",
                                        "apellido_paterno": "PEREZ",
                                        "apellido_materno": "LOPEZ",
                                        "codigo_verificacion": 0
                                    },
                                    "time": 0.42,
                                    "source": "padron_reducido"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "description": "No hay un contribuyente con ese DNI (`not_found`, `retryable: false`) o el proveedor no pudo completar la consulta (código del proveedor, `retryable: true`).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorEnvelope"
                                }
                            }
                        }
                    },
                    "409": {
                        "$ref": "#/components/responses/DuplicateRequest"
                    },
                    "422": {
                        "description": "DNI inválido (`invalid_dni`) o campos faltantes.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorEnvelope"
                                }
                            }
                        }
                    },
                    "429": {
                        "$ref": "#/components/responses/TooManyRequests"
                    },
                    "502": {
                        "description": "El servicio de consultas no pudo completar la solicitud (`servicio_error`, `retryable: true`).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorEnvelope"
                                }
                            }
                        }
                    },
                    "503": {
                        "description": "El servicio de consultas no está disponible (`servicio_no_disponible`, `retryable: true`). Reintente en unos segundos. También `rate_limit_unavailable` si el contador de límites no está disponible.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "oneOf": [
                                        {
                                            "$ref": "#/components/schemas/ErrorEnvelope"
                                        },
                                        {
                                            "$ref": "#/components/schemas/AccessError"
                                        }
                                    ]
                                }
                            }
                        }
                    }
                },
                "x-consumo-unidades": "1 por solicitud",
                "x-estado-verificacion": "pendiente_validacion_externa"
            }
        },
        "/api/dni/{dni}": {
            "get": {
                "tags": [
                    "Consultas por GET"
                ],
                "operationId": "compatDni",
                "summary": "Consulta DNI por GET",
                "description": "Consulta los datos de una persona por su DNI. Es la misma consulta que `POST /api/v1/dni`, pero por GET y con un formato de respuesta alterno.\n\n**Campos que devuelve en `data`:** `numero`, `nombre_completo`, `nombres`, `apellido_paterno`, `apellido_materno` y `codigo_verificacion`.\n\n**Campos adicionales:** `direccion` (texto vacío `\"\"` si el proveedor no la entrega) y `ubigeo` (`[departamento, provincia, distrito]` como códigos, o `null` si no hay dato).\n\n**Consumo:** 1 unidad por solicitud.\n\n**Consumo:** 1 por solicitud. Una consulta validada que se envía al proveedor consume cuota aunque el proveedor responda con error (ADR-005). Los rechazos de validación (422), autenticación, límite o duplicado no consumen.",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/IdempotencyKey"
                    },
                    {
                        "name": "dni",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "pattern": "^\\d{8}$"
                        },
                        "example": "44556677"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Consulta resuelta.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/SuccessEnvelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "additionalProperties": true
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "success": true,
                                    "code": "found",
                                    "retryable": false,
                                    "data": {
                                        "numero": "44556677",
                                        "nombre_completo": "PEREZ GARCIA JUAN CARLOS",
                                        "nombres": "JUAN CARLOS",
                                        "apellido_paterno": "PEREZ",
                                        "apellido_materno": "GARCIA",
                                        "codigo_verificacion": 3
                                    },
                                    "time": 0.42
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "description": "No hay un contribuyente registrado en SUNAT con ese DNI (`not_found`, `retryable: false`).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorEnvelope"
                                }
                            }
                        }
                    },
                    "409": {
                        "$ref": "#/components/responses/DuplicateRequest"
                    },
                    "422": {
                        "description": "DNI inválido: debe tener 8 dígitos (`invalid_dni`, `retryable: false`).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorEnvelope"
                                }
                            }
                        }
                    },
                    "429": {
                        "$ref": "#/components/responses/TooManyRequests"
                    },
                    "503": {
                        "description": "Servicio no disponible (`servicio_no_disponible`, `retryable: true`). Reintentar en unos segundos. También `rate_limit_unavailable` si el contador de límites no está disponible.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "oneOf": [
                                        {
                                            "$ref": "#/components/schemas/ErrorEnvelope"
                                        },
                                        {
                                            "$ref": "#/components/schemas/AccessError"
                                        }
                                    ]
                                }
                            }
                        }
                    }
                },
                "x-consumo-unidades": "1 por solicitud",
                "x-estado-verificacion": "pendiente_validacion_externa"
            }
        },
        "/api/ruc": {
            "post": {
                "tags": [
                    "Identidad"
                ],
                "operationId": "rucLegacy",
                "summary": "Consulta RUC (alias sin versión)",
                "description": "Consulta un RUC por un solo filtro: primero el Padrón Reducido oficial (`source: padron_reducido`, instantáneo; trae razón social, estado, condición y domicilio) y, si el RUC no está ahí o el padrón no está disponible, el portal público de SUNAT en línea (`source: sunat_en_linea`, ficha completa). Si la consulta en línea está desactivada, solo responde el padrón.\n\n**Consumo:** 1 por solicitud. Una consulta validada que se envía al proveedor consume cuota aunque el proveedor responda con error (ADR-005). Los rechazos de validación (422), autenticación, límite o duplicado no consumen.\n\n**Obsoleto:** alias temporal de `/api/v1/ruc` mantenido por compatibilidad; usar la ruta versionada.",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/IdempotencyKey"
                    }
                ],
                "deprecated": true,
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "ruc"
                                ],
                                "properties": {
                                    "ruc": {
                                        "type": "string",
                                        "pattern": "^\\d{11}$",
                                        "description": "RUC de 11 dígitos.",
                                        "example": "20123456789"
                                    }
                                }
                            },
                            "example": {
                                "ruc": "20123456789"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Consulta resuelta.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/SuccessEnvelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "additionalProperties": true
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "success": true,
                                    "code": "found",
                                    "retryable": false,
                                    "data": {
                                        "ruc": "20123456789",
                                        "nombre_o_razon_social": "EMPRESA DEMOSTRACION S.A.C.",
                                        "estado": "ACTIVO",
                                        "condicion": "HABIDO",
                                        "direccion": "AV. EJEMPLO 123 LIMA - LIMA - LIMA",
                                        "departamento": "LIMA",
                                        "tipo_contribuyente": "SOCIEDAD ANONIMA CERRADA",
                                        "fecha_inscripcion": "01/01/2020",
                                        "fecha_inicio_actividades": "01/01/2020",
                                        "actividades_economicas": [
                                            "Principal - 6201 - ACTIVIDADES DE PROGRAMACION INFORMATICA"
                                        ],
                                        "sistema_emision": "MANUAL/COMPUTARIZADO",
                                        "sistema_contabilidad": "COMPUTARIZADO",
                                        "es_agente_de_retencion": "NO",
                                        "es_buen_contribuyente": "NO"
                                    },
                                    "time": 0.42,
                                    "source": "padron_reducido"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "description": "El RUC no existe en SUNAT (`not_found`, `retryable: false`) o SUNAT no respondió (`retryable: true`). Distinga ambos casos con `code` y `retryable`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorEnvelope"
                                }
                            }
                        }
                    },
                    "409": {
                        "$ref": "#/components/responses/DuplicateRequest"
                    },
                    "422": {
                        "description": "RUC inválido (`invalid_ruc`) o campos faltantes.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorEnvelope"
                                }
                            }
                        }
                    },
                    "429": {
                        "$ref": "#/components/responses/TooManyRequests"
                    },
                    "502": {
                        "description": "El servicio de consultas no pudo completar la solicitud (`servicio_error`, `retryable: true`).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorEnvelope"
                                }
                            }
                        }
                    },
                    "503": {
                        "description": "El servicio de consultas no está disponible (`servicio_no_disponible`, `retryable: true`). Reintente en unos segundos. También `rate_limit_unavailable` si el contador de límites no está disponible.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "oneOf": [
                                        {
                                            "$ref": "#/components/schemas/ErrorEnvelope"
                                        },
                                        {
                                            "$ref": "#/components/schemas/AccessError"
                                        }
                                    ]
                                }
                            }
                        }
                    }
                },
                "x-consumo-unidades": "1 por solicitud",
                "x-estado-verificacion": "pendiente_validacion_externa"
            }
        },
        "/api/ruc/excluido": {
            "post": {
                "tags": [
                    "Comprobantes"
                ],
                "operationId": "cpeRucExcluidoLegacy",
                "summary": "Consulta CPE de un RUC excluido (alias sin versión)",
                "description": "Consulta un comprobante en el proveedor alternativo configurado para RUC excluidos (portal público de Sovos, p. ej. BCP). Entrega PDF y XML; el CDR se devuelve como null porque la fuente no lo proporciona. `documento` trae el estado en el proveedor, emisor y receptor; `fuente` indica `en_linea` o `cache` (un comprobante ya consultado se responde desde la caché sin volver al proveedor).\n\n**Consumo:** 1 por solicitud. Una consulta validada que se envía al proveedor consume cuota aunque el proveedor responda con error (ADR-005). Los rechazos de validación (422), autenticación, límite o duplicado no consumen.\n\n**Obsoleto:** alias temporal de `/api/v1/ruc/excluido` mantenido por compatibilidad; usar la ruta versionada.",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/IdempotencyKey"
                    }
                ],
                "deprecated": true,
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "ruc",
                                    "tipo",
                                    "folio",
                                    "fecha",
                                    "total"
                                ],
                                "properties": {
                                    "ruc": {
                                        "type": "string",
                                        "pattern": "^\\d{11}$",
                                        "description": "RUC de 11 dígitos.",
                                        "example": "20123456789"
                                    },
                                    "tipo": {
                                        "type": "string",
                                        "enum": [
                                            "01",
                                            "03",
                                            "07",
                                            "08"
                                        ],
                                        "example": "01"
                                    },
                                    "folio": {
                                        "type": "string",
                                        "example": "FA02-0000000"
                                    },
                                    "fecha": {
                                        "type": "string",
                                        "format": "date",
                                        "example": "2026-10-08"
                                    },
                                    "total": {
                                        "type": "string",
                                        "example": "0.00"
                                    }
                                }
                            },
                            "example": {
                                "ruc": "20123456789",
                                "tipo": "01",
                                "folio": "FA02-0000000",
                                "fecha": "2026-10-08",
                                "total": "0.00"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Consulta resuelta.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/SuccessEnvelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "additionalProperties": true
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "success": true,
                                    "code": "found",
                                    "retryable": false,
                                    "data": {
                                        "provider": "bcp_sovos",
                                        "datos": {
                                            "ruc": "20123456789",
                                            "tipo": "01",
                                            "folio": "FA02-0000000",
                                            "fecha": "2026-10-08",
                                            "total": "0.00"
                                        },
                                        "archivos": {
                                            "pdf": {
                                                "base64": "BASE64_PDF",
                                                "mime": "application/pdf",
                                                "size": 12345
                                            },
                                            "xml": {
                                                "base64": "BASE64_XML",
                                                "mime": "application/xml",
                                                "size": 6789
                                            },
                                            "cdr": null
                                        },
                                        "documento": {
                                            "estado": "document.authorized",
                                            "estado_descripcion": "Authorized",
                                            "emisor": "BANCO DE CREDITO DEL PERU",
                                            "receptor": "EMPRESA DEMO SAC"
                                        },
                                        "fuente": "en_linea"
                                    },
                                    "time": 0.42
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "description": "El comprobante no existe en el proveedor (`not_found`, `retryable: false`): revise RUC, tipo, serie-número, fecha y total.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorEnvelope"
                                }
                            }
                        }
                    },
                    "409": {
                        "$ref": "#/components/responses/DuplicateRequest"
                    },
                    "422": {
                        "description": "Campos inválidos.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorEnvelope"
                                }
                            }
                        }
                    },
                    "429": {
                        "$ref": "#/components/responses/TooManyRequests"
                    },
                    "502": {
                        "description": "El proveedor alternativo no pudo completar la consulta (`proveedor_error`) o excedió el tiempo de espera (`timeout`); ambos reintentables.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorEnvelope"
                                }
                            }
                        }
                    },
                    "503": {
                        "description": "El proveedor alternativo no está habilitado (`proveedor_no_disponible`). También `rate_limit_unavailable` si el contador de límites no está disponible.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "oneOf": [
                                        {
                                            "$ref": "#/components/schemas/ErrorEnvelope"
                                        },
                                        {
                                            "$ref": "#/components/schemas/AccessError"
                                        }
                                    ]
                                }
                            }
                        }
                    }
                },
                "x-consumo-unidades": "1 por solicitud",
                "x-estado-verificacion": "pendiente_validacion_externa"
            }
        },
        "/api/ruc/{ruc}": {
            "get": {
                "tags": [
                    "Consultas por GET"
                ],
                "operationId": "compatRuc",
                "summary": "Consulta RUC por GET",
                "description": "Consulta la ficha de un RUC. Es la misma consulta que `POST /api/v1/ruc`, pero por GET y con un formato de respuesta alterno.\n\n**Campos que devuelve en `data`:** `ruc`, `nombre_o_razon_social`, `estado`, `condicion`, `direccion`, `departamento`, `tipo_contribuyente`, `fecha_inscripcion`, `fecha_inicio_actividades`, `actividades_economicas`, `sistema_emision`, `sistema_contabilidad`, `es_agente_de_retencion` (`SI`/`NO`) y `es_buen_contribuyente`.\n\n**Campos adicionales:** `ubigeo` (`[departamento, provincia, distrito]` como códigos, o `null` si no hay dato). `direccion` vale `\"\"` si no hay dato. El campo `source` va en el nivel superior de la respuesta, junto a `success`.\n\n**Consumo:** 1 unidad por solicitud.\n\n**Consumo:** 1 por solicitud. Una consulta validada que se envía al proveedor consume cuota aunque el proveedor responda con error (ADR-005). Los rechazos de validación (422), autenticación, límite o duplicado no consumen.",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/IdempotencyKey"
                    },
                    {
                        "name": "ruc",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "pattern": "^\\d{11}$"
                        },
                        "example": "20123456789"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Consulta resuelta.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/SuccessEnvelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "additionalProperties": true
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "success": true,
                                    "code": "found",
                                    "retryable": false,
                                    "data": {
                                        "ruc": "20123456789",
                                        "nombre_o_razon_social": "EMPRESA DEMOSTRACION S.A.C.",
                                        "estado": "ACTIVO",
                                        "condicion": "HABIDO",
                                        "direccion": "AV. EJEMPLO 123 LIMA - LIMA - LIMA",
                                        "departamento": "LIMA",
                                        "es_agente_de_retencion": "NO"
                                    },
                                    "time": 0.42
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "description": "El RUC no existe en SUNAT (`not_found`, `retryable: false`).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorEnvelope"
                                }
                            }
                        }
                    },
                    "409": {
                        "$ref": "#/components/responses/DuplicateRequest"
                    },
                    "422": {
                        "description": "RUC inválido: debe tener 11 dígitos (`invalid_ruc`, `retryable: false`).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorEnvelope"
                                }
                            }
                        }
                    },
                    "429": {
                        "$ref": "#/components/responses/TooManyRequests"
                    },
                    "502": {
                        "description": "Error del proveedor (`proveedor_error`, `retryable: true`).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorEnvelope"
                                }
                            }
                        }
                    },
                    "503": {
                        "description": "Servicio no disponible (`servicio_no_disponible`, `retryable: true`). Reintentar en unos segundos. También `rate_limit_unavailable` si el contador de límites no está disponible.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "oneOf": [
                                        {
                                            "$ref": "#/components/schemas/ErrorEnvelope"
                                        },
                                        {
                                            "$ref": "#/components/schemas/AccessError"
                                        }
                                    ]
                                }
                            }
                        }
                    }
                },
                "x-consumo-unidades": "1 por solicitud",
                "x-estado-verificacion": "pendiente_validacion_externa"
            }
        },
        "/api/status": {
            "get": {
                "tags": [
                    "Servicio"
                ],
                "operationId": "estadoServicio",
                "summary": "Estado del servicio",
                "description": "Comprobación pública de disponibilidad. No requiere token ni consume cuota.",
                "security": [],
                "responses": {
                    "200": {
                        "description": "Servicio disponible.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "required": [
                                        "success",
                                        "service",
                                        "timestamp"
                                    ],
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "const": true
                                        },
                                        "service": {
                                            "type": "string"
                                        },
                                        "timestamp": {
                                            "type": "string",
                                            "format": "date-time"
                                        }
                                    }
                                },
                                "example": {
                                    "success": true,
                                    "service": "FactosPeru API",
                                    "timestamp": "2026-10-10T12:00:00-05:00"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/v1/aeropuertos": {
            "get": {
                "tags": [
                    "Padrón y datos públicos"
                ],
                "operationId": "aeropuertos",
                "summary": "Aeropuertos (MTC)",
                "description": "Busca aeropuertos en el dataset oficial del MTC importado en el servicio.\n\n**Consumo:** 1 por solicitud. Una consulta validada que se envía al proveedor consume cuota aunque el proveedor responda con error (ADR-005). Los rechazos de validación (422), autenticación, límite o duplicado no consumen.",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/IdempotencyKey"
                    },
                    {
                        "name": "q",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "maxLength": 120
                        },
                        "description": "Texto a buscar en el registro. Vacío devuelve los primeros registros.",
                        "example": "LIMA"
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 100,
                            "default": 50
                        },
                        "description": "Máximo de registros."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Consulta resuelta.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/SuccessEnvelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "array",
                                                    "items": {
                                                        "type": "object",
                                                        "additionalProperties": true,
                                                        "description": "Registro del dataset oficial importado; las columnas dependen de la fuente."
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "success": true,
                                    "code": "found",
                                    "retryable": false,
                                    "data": [
                                        {
                                            "iata": "LIM",
                                            "nombre": "JORGE CHAVEZ"
                                        }
                                    ],
                                    "time": 0.42,
                                    "source": "aeropuertos"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "409": {
                        "$ref": "#/components/responses/DuplicateRequest"
                    },
                    "422": {
                        "description": "Parámetros inválidos.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorEnvelope"
                                }
                            }
                        }
                    },
                    "429": {
                        "$ref": "#/components/responses/TooManyRequests"
                    },
                    "502": {
                        "description": "Error del proveedor (`proveedor_error`).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorEnvelope"
                                }
                            }
                        }
                    },
                    "503": {
                        "description": "El dataset no está importado (`dataset_no_disponible`) o el servicio no responde (`servicio_no_disponible`). También `rate_limit_unavailable` si el contador de límites no está disponible.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "oneOf": [
                                        {
                                            "$ref": "#/components/schemas/ErrorEnvelope"
                                        },
                                        {
                                            "$ref": "#/components/schemas/AccessError"
                                        }
                                    ]
                                }
                            }
                        }
                    }
                },
                "x-consumo-unidades": "1 por solicitud",
                "x-estado-verificacion": "simulada"
            }
        },
        "/api/v1/buzon": {
            "post": {
                "tags": [
                    "Buzón SOL"
                ],
                "operationId": "buzon",
                "summary": "Consulta del buzón electrónico",
                "description": "Extrae notificaciones y mensajes del buzón SOL del RUC, con sus detalles y adjuntos.\n\n**Consumo:** 1 por solicitud. Una consulta validada que se envía al proveedor consume cuota aunque el proveedor responda con error (ADR-005). Los rechazos de validación (422), autenticación, límite o duplicado no consumen.",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/IdempotencyKey"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "ruc",
                                    "usuario_sol",
                                    "clave_sol"
                                ],
                                "properties": {
                                    "ruc": {
                                        "type": "string",
                                        "pattern": "^\\d{11}$",
                                        "description": "RUC de 11 dígitos.",
                                        "example": "20123456789"
                                    },
                                    "usuario_sol": {
                                        "type": "string",
                                        "description": "Usuario SOL del RUC consultado. Se reenvía al proveedor y nunca se registra.",
                                        "example": "USUARIO_SOL"
                                    },
                                    "clave_sol": {
                                        "type": "string",
                                        "format": "password",
                                        "description": "Clave SOL. Se reenvía al proveedor y nunca se registra.",
                                        "example": "CLAVE_SOL"
                                    },
                                    "omitir_detalle": {
                                        "type": "array",
                                        "items": {
                                            "type": "string"
                                        },
                                        "maxItems": 5000,
                                        "description": "Opcional. Códigos de mensajes cuyo detalle ya tiene el cliente: se listan igual, pero no se abre cada mensaje.",
                                        "example": [
                                            "1085681165"
                                        ]
                                    }
                                }
                            },
                            "example": {
                                "ruc": "20123456789",
                                "usuario_sol": "USUARIO_SOL",
                                "clave_sol": "CLAVE_SOL",
                                "omitir_detalle": [
                                    []
                                ]
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Consulta resuelta.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/SuccessEnvelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "additionalProperties": true
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "success": true,
                                    "code": "found",
                                    "retryable": false,
                                    "data": {
                                        "timestamp": "2026-10-10T12:00:00-05:00",
                                        "buzon_notificaciones": {
                                            "nombre": "",
                                            "contador": 0,
                                            "mensajes": []
                                        },
                                        "buzon_mensajes": {
                                            "nombre": "",
                                            "contador": 0,
                                            "mensajes": []
                                        },
                                        "mis_carpetas": [],
                                        "mis_etiquetas": [],
                                        "todos_los_mensajes": [],
                                        "detalles_mensajes": [],
                                        "ajax_notificaciones": [],
                                        "ajax_mensajes": [],
                                        "resumen": {
                                            "total_mensajes": 0,
                                            "total_detalles": 0,
                                            "total_carpetas": 0,
                                            "total_etiquetas": 0,
                                            "ajax_noti": 0,
                                            "ajax_msj": 0
                                        }
                                    },
                                    "time": 0.42
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "409": {
                        "$ref": "#/components/responses/DuplicateRequest"
                    },
                    "422": {
                        "description": "Campos inválidos.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorEnvelope"
                                }
                            }
                        }
                    },
                    "429": {
                        "$ref": "#/components/responses/TooManyRequests"
                    },
                    "500": {
                        "description": "El proveedor informó un error (`buzon_error` u otro código, reintentable).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorEnvelope"
                                }
                            }
                        }
                    },
                    "502": {
                        "description": "El servicio de consultas no pudo completar la solicitud (`servicio_error`, `retryable: true`).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorEnvelope"
                                }
                            }
                        }
                    },
                    "503": {
                        "description": "El servicio de consultas no está disponible (`servicio_no_disponible`, `retryable: true`). Reintente en unos segundos. También `rate_limit_unavailable` si el contador de límites no está disponible.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "oneOf": [
                                        {
                                            "$ref": "#/components/schemas/ErrorEnvelope"
                                        },
                                        {
                                            "$ref": "#/components/schemas/AccessError"
                                        }
                                    ]
                                }
                            }
                        }
                    }
                },
                "x-consumo-unidades": "1 por solicitud",
                "x-estado-verificacion": "pendiente_validacion_externa"
            }
        },
        "/api/v1/carnet-extranjeria": {
            "post": {
                "tags": [
                    "Identidad"
                ],
                "operationId": "carnetExtranjeria",
                "summary": "Consulta por Carnet de Extranjería",
                "description": "Busca en el portal público de SUNAT al contribuyente registrado con ese documento: nombre, RUC, estado y ubicación. Solo se encuentran personas inscritas en SUNAT. Si la consulta en línea está desactivada responde 503 `fuente_desactivada`.\n\n**Consumo:** 1 por solicitud. Una consulta validada que se envía al proveedor consume cuota aunque el proveedor responda con error (ADR-005). Los rechazos de validación (422), autenticación, límite o duplicado no consumen.",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/IdempotencyKey"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "numero"
                                ],
                                "properties": {
                                    "numero": {
                                        "type": "string",
                                        "pattern": "^[A-Za-z0-9]{4,15}$",
                                        "description": "Número del documento (4 a 15 letras o dígitos).",
                                        "example": "001234567"
                                    }
                                }
                            },
                            "example": {
                                "numero": "001234567"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Consulta resuelta.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/SuccessEnvelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "additionalProperties": true
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "success": true,
                                    "code": "found",
                                    "retryable": false,
                                    "data": {
                                        "tipo_documento": "carnet-extranjeria",
                                        "numero": "001234567",
                                        "nombre_completo": "PEREZ LOPEZ ANA MARIA",
                                        "nombres": "ANA MARIA",
                                        "apellido_paterno": "PEREZ",
                                        "apellido_materno": "LOPEZ",
                                        "ruc": "15600000001",
                                        "estado": "ACTIVO",
                                        "ubicacion": "LIMA - LIMA - MIRAFLORES"
                                    },
                                    "time": 0.42,
                                    "source": "sunat_en_linea"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "description": "No hay un contribuyente con ese documento (`not_found`, `retryable: false`).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorEnvelope"
                                }
                            }
                        }
                    },
                    "409": {
                        "$ref": "#/components/responses/DuplicateRequest"
                    },
                    "422": {
                        "description": "Número inválido (`invalid_documento`) o campo faltante.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorEnvelope"
                                }
                            }
                        }
                    },
                    "429": {
                        "$ref": "#/components/responses/TooManyRequests"
                    },
                    "502": {
                        "description": "Error del proveedor (`proveedor_error`, reintentable).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorEnvelope"
                                }
                            }
                        }
                    },
                    "503": {
                        "description": "Consulta en línea desactivada (`fuente_desactivada`) o servicio no disponible (`no_disponible`, `servicio_no_disponible`); reintentable. También `rate_limit_unavailable` si el contador de límites no está disponible.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "oneOf": [
                                        {
                                            "$ref": "#/components/schemas/ErrorEnvelope"
                                        },
                                        {
                                            "$ref": "#/components/schemas/AccessError"
                                        }
                                    ]
                                }
                            }
                        }
                    }
                },
                "x-consumo-unidades": "1 por solicitud",
                "x-estado-verificacion": "pendiente_validacion_externa"
            }
        },
        "/api/v1/cedula-diplomatica": {
            "post": {
                "tags": [
                    "Identidad"
                ],
                "operationId": "cedulaDiplomatica",
                "summary": "Consulta por Cédula Diplomática de Identidad",
                "description": "Busca en el portal público de SUNAT al contribuyente registrado con ese documento: nombre, RUC, estado y ubicación. Solo se encuentran personas inscritas en SUNAT. Si la consulta en línea está desactivada responde 503 `fuente_desactivada`.\n\n**Consumo:** 1 por solicitud. Una consulta validada que se envía al proveedor consume cuota aunque el proveedor responda con error (ADR-005). Los rechazos de validación (422), autenticación, límite o duplicado no consumen.",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/IdempotencyKey"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "numero"
                                ],
                                "properties": {
                                    "numero": {
                                        "type": "string",
                                        "pattern": "^[A-Za-z0-9]{4,15}$",
                                        "description": "Número del documento (4 a 15 letras o dígitos).",
                                        "example": "123456"
                                    }
                                }
                            },
                            "example": {
                                "numero": "123456"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Consulta resuelta.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/SuccessEnvelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "additionalProperties": true
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "success": true,
                                    "code": "found",
                                    "retryable": false,
                                    "data": {
                                        "tipo_documento": "cedula-diplomatica",
                                        "numero": "123456",
                                        "nombre_completo": "PEREZ LOPEZ ANA MARIA",
                                        "nombres": "ANA MARIA",
                                        "apellido_paterno": "PEREZ",
                                        "apellido_materno": "LOPEZ",
                                        "ruc": "15600000001",
                                        "estado": "ACTIVO",
                                        "ubicacion": "LIMA - LIMA - MIRAFLORES"
                                    },
                                    "time": 0.42,
                                    "source": "sunat_en_linea"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "description": "No hay un contribuyente con ese documento (`not_found`, `retryable: false`).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorEnvelope"
                                }
                            }
                        }
                    },
                    "409": {
                        "$ref": "#/components/responses/DuplicateRequest"
                    },
                    "422": {
                        "description": "Número inválido (`invalid_documento`) o campo faltante.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorEnvelope"
                                }
                            }
                        }
                    },
                    "429": {
                        "$ref": "#/components/responses/TooManyRequests"
                    },
                    "502": {
                        "description": "Error del proveedor (`proveedor_error`, reintentable).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorEnvelope"
                                }
                            }
                        }
                    },
                    "503": {
                        "description": "Consulta en línea desactivada (`fuente_desactivada`) o servicio no disponible (`no_disponible`, `servicio_no_disponible`); reintentable. También `rate_limit_unavailable` si el contador de límites no está disponible.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "oneOf": [
                                        {
                                            "$ref": "#/components/schemas/ErrorEnvelope"
                                        },
                                        {
                                            "$ref": "#/components/schemas/AccessError"
                                        }
                                    ]
                                }
                            }
                        }
                    }
                },
                "x-consumo-unidades": "1 por solicitud",
                "x-estado-verificacion": "pendiente_validacion_externa"
            }
        },
        "/api/v1/cpe": {
            "post": {
                "tags": [
                    "Comprobantes"
                ],
                "operationId": "cpe",
                "summary": "Consulta y descarga de CPE",
                "description": "Consulta comprobantes electrónicos con la Clave SOL del RUC y devuelve sus archivos PDF, XML y CDR en Base64.\n\n**Consumo:** 1 por comprobante del lote (máximo 100). Una consulta validada que se envía al proveedor consume cuota aunque el proveedor responda con error (ADR-005). Los rechazos de validación (422), autenticación, límite o duplicado no consumen.",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/IdempotencyKey"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "ruc",
                                    "usuario_sol",
                                    "clave_sol",
                                    "comprobantes"
                                ],
                                "properties": {
                                    "ruc": {
                                        "type": "string",
                                        "pattern": "^\\d{11}$",
                                        "description": "RUC de 11 dígitos.",
                                        "example": "20123456789"
                                    },
                                    "usuario_sol": {
                                        "type": "string",
                                        "description": "Usuario SOL del RUC consultado. Se reenvía al proveedor y nunca se registra.",
                                        "example": "USUARIO_SOL"
                                    },
                                    "clave_sol": {
                                        "type": "string",
                                        "format": "password",
                                        "description": "Clave SOL. Se reenvía al proveedor y nunca se registra.",
                                        "example": "CLAVE_SOL"
                                    },
                                    "comprobantes": {
                                        "type": "array",
                                        "minItems": 1,
                                        "maxItems": 100,
                                        "items": {
                                            "type": "object",
                                            "description": "Comprobante a descargar. La API no valida su contenido.",
                                            "properties": {
                                                "tipo_consulta": {
                                                    "type": "string",
                                                    "example": "emitido"
                                                },
                                                "ruc_emisor": {
                                                    "type": "string",
                                                    "example": "20123456789"
                                                },
                                                "tipo": {
                                                    "type": "string",
                                                    "example": "01"
                                                },
                                                "serie": {
                                                    "type": "string",
                                                    "example": "F001"
                                                },
                                                "numero": {
                                                    "type": "string",
                                                    "example": "123"
                                                },
                                                "fecha": {
                                                    "type": "string",
                                                    "example": "FECHA_DE_EMISION"
                                                },
                                                "monto": {
                                                    "type": "string",
                                                    "example": "MONTO_DEL_COMPROBANTE"
                                                }
                                            },
                                            "additionalProperties": true
                                        }
                                    }
                                }
                            },
                            "example": {
                                "ruc": "20123456789",
                                "usuario_sol": "USUARIO_SOL",
                                "clave_sol": "CLAVE_SOL",
                                "comprobantes": [
                                    {
                                        "tipo_consulta": "emitido",
                                        "ruc_emisor": "20123456789",
                                        "tipo": "01",
                                        "serie": "F001",
                                        "numero": "123",
                                        "fecha": "FECHA_DE_EMISION",
                                        "monto": "MONTO_DEL_COMPROBANTE"
                                    }
                                ]
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Consulta resuelta.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/SuccessEnvelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "additionalProperties": true
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "success": true,
                                    "code": "found",
                                    "retryable": false,
                                    "data": {
                                        "total": 1,
                                        "exitosos": 1,
                                        "fallidos": 0,
                                        "comprobantes": [
                                            {
                                                "id": "1",
                                                "estado": "ok",
                                                "tipo": "01",
                                                "serie": "F001",
                                                "numero": "123",
                                                "fecha_emision": "FECHA_DE_EMISION",
                                                "total": "MONTO",
                                                "moneda": "PEN",
                                                "estado_cpe": "CODIGO_PROVEEDOR",
                                                "emisor": {
                                                    "ruc": "20123456789",
                                                    "razon_social": "EMPRESA DEMOSTRACION S.A.C.",
                                                    "direccion": "AV. EJEMPLO 123"
                                                },
                                                "receptor": {
                                                    "documento": "20987654321",
                                                    "razon_social": "CLIENTE DEMOSTRACION S.A."
                                                },
                                                "items": [],
                                                "archivos": {
                                                    "pdf": {
                                                        "ok": true,
                                                        "nombre": "F001-123.pdf",
                                                        "es_zip": false,
                                                        "contenido_base64": "BASE64",
                                                        "tamano_kb": 12.5
                                                    },
                                                    "xml": {
                                                        "ok": false,
                                                        "error": "No disponible"
                                                    },
                                                    "cdr": {
                                                        "ok": false,
                                                        "error": "No disponible"
                                                    }
                                                }
                                            }
                                        ]
                                    },
                                    "time": 0.42
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "409": {
                        "$ref": "#/components/responses/DuplicateRequest"
                    },
                    "422": {
                        "description": "Campos superiores inválidos (RUC no numérico, lote vacío o mayor a 100).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorEnvelope"
                                }
                            }
                        }
                    },
                    "429": {
                        "$ref": "#/components/responses/TooManyRequests"
                    },
                    "500": {
                        "description": "El proveedor informó un error global (`cpe_error`, reintentable).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorEnvelope"
                                }
                            }
                        }
                    },
                    "502": {
                        "description": "El servicio de consultas no pudo completar la solicitud (`servicio_error`, `retryable: true`).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorEnvelope"
                                }
                            }
                        }
                    },
                    "503": {
                        "description": "El servicio de consultas no está disponible (`servicio_no_disponible`, `retryable: true`). Reintente en unos segundos. También `rate_limit_unavailable` si el contador de límites no está disponible.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "oneOf": [
                                        {
                                            "$ref": "#/components/schemas/ErrorEnvelope"
                                        },
                                        {
                                            "$ref": "#/components/schemas/AccessError"
                                        }
                                    ]
                                }
                            }
                        }
                    }
                },
                "x-consumo-unidades": "1 por comprobante del lote (máximo 100)",
                "x-estado-verificacion": "pendiente_validacion_externa"
            }
        },
        "/api/v1/credenciales-api": {
            "post": {
                "tags": [
                    "Credenciales API SUNAT"
                ],
                "operationId": "credencialesApi",
                "summary": "Extraer credenciales de API SUNAT",
                "description": "Abre «Gestión Credenciales de API SUNAT» del menú SOL y devuelve la aplicación registrada (ID y clave de la aplicación, alcance y APIs habilitadas) y el catálogo de APIs que se pueden elegir. Si el RUC no tiene aplicación, `tiene_aplicacion` es false: use `/credenciales-api/crear`. No cambia nada en SUNAT. Guarde la clave cifrada; esta API no la registra.\n\n**Consumo:** 1 por solicitud. Una consulta validada que se envía al proveedor consume cuota aunque el proveedor responda con error (ADR-005). Los rechazos de validación (422), autenticación, límite o duplicado no consumen.",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/IdempotencyKey"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "ruc",
                                    "usuario_sol",
                                    "clave_sol"
                                ],
                                "properties": {
                                    "ruc": {
                                        "type": "string",
                                        "pattern": "^\\d{11}$",
                                        "description": "RUC de 11 dígitos.",
                                        "example": "20123456789"
                                    },
                                    "usuario_sol": {
                                        "type": "string",
                                        "description": "Usuario SOL del RUC consultado. Se reenvía al proveedor y nunca se registra.",
                                        "example": "USUARIO_SOL"
                                    },
                                    "clave_sol": {
                                        "type": "string",
                                        "format": "password",
                                        "description": "Clave SOL. Se reenvía al proveedor y nunca se registra.",
                                        "example": "CLAVE_SOL"
                                    }
                                }
                            },
                            "example": {
                                "ruc": "20123456789",
                                "usuario_sol": "USUARIO_SOL",
                                "clave_sol": "CLAVE_SOL"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Consulta resuelta.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/SuccessEnvelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "additionalProperties": true
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "success": true,
                                    "code": "found",
                                    "retryable": false,
                                    "data": {
                                        "tiene_aplicacion": true,
                                        "aplicacion": {
                                            "id": "ID_INTERNO_SUNAT",
                                            "codigo_aplicacion": "2020000000",
                                            "nombre": "mi-sistema",
                                            "url": "https://mi-sistema.pe",
                                            "alcance": "desktop",
                                            "client_id": "CLIENT_ID_EJEMPLO",
                                            "client_secret": "CLIENT_SECRET_EJEMPLO",
                                            "recursos": [
                                                {
                                                    "recurso": "/v1/contribuyente/gem",
                                                    "nombre": "GRE Emision de Comprobantes"
                                                }
                                            ]
                                        },
                                        "catalogo": [
                                            {
                                                "codigo": "2",
                                                "nombre": "MIGE RCE y RVIE - SIRE",
                                                "recurso": "/v1/contribuyente/migeigv",
                                                "url_api": "https://api-sire.sunat.gob.pe"
                                            },
                                            {
                                                "codigo": "3",
                                                "nombre": "GRE Emision de Comprobantes",
                                                "recurso": "/v1/contribuyente/gem",
                                                "url_api": "https://api-cpe.sunat.gob.pe"
                                            }
                                        ]
                                    },
                                    "time": 0.42
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "409": {
                        "$ref": "#/components/responses/DuplicateRequest"
                    },
                    "422": {
                        "description": "Campos inválidos.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorEnvelope"
                                }
                            }
                        }
                    },
                    "429": {
                        "$ref": "#/components/responses/TooManyRequests"
                    },
                    "503": {
                        "description": "No se pudo iniciar sesión o abrir la gestión de credenciales (`servicio_no_disponible`, reintentable). También `rate_limit_unavailable` si el contador de límites no está disponible.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "oneOf": [
                                        {
                                            "$ref": "#/components/schemas/ErrorEnvelope"
                                        },
                                        {
                                            "$ref": "#/components/schemas/AccessError"
                                        }
                                    ]
                                }
                            }
                        }
                    }
                },
                "x-consumo-unidades": "1 por solicitud",
                "x-estado-verificacion": "pendiente_validacion_externa"
            }
        },
        "/api/v1/credenciales-api/crear": {
            "post": {
                "tags": [
                    "Credenciales API SUNAT"
                ],
                "operationId": "credencialesApiCrear",
                "summary": "Crear aplicación y generar credenciales de API SUNAT",
                "description": "Registra la aplicación del RUC en «Gestión Credenciales de API SUNAT». Por defecto marca todas las APIs del catálogo y alcance `desktop` (como en la pantalla); envíe `recursos` solo para limitar la selección. SUNAT genera el ID y la clave, que se devuelven en la respuesta. Cambia la cuenta SOL: SUNAT permite una aplicación por RUC; si ya existe responde 409 y se usa `/credenciales-api/editar`.\n\n**Consumo:** 1 por solicitud. Una consulta validada que se envía al proveedor consume cuota aunque el proveedor responda con error (ADR-005). Los rechazos de validación (422), autenticación, límite o duplicado no consumen.",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/IdempotencyKey"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "ruc",
                                    "usuario_sol",
                                    "clave_sol",
                                    "nombre",
                                    "url"
                                ],
                                "properties": {
                                    "ruc": {
                                        "type": "string",
                                        "pattern": "^\\d{11}$",
                                        "description": "RUC de 11 dígitos.",
                                        "example": "20123456789"
                                    },
                                    "usuario_sol": {
                                        "type": "string",
                                        "description": "Usuario SOL del RUC consultado. Se reenvía al proveedor y nunca se registra.",
                                        "example": "USUARIO_SOL"
                                    },
                                    "clave_sol": {
                                        "type": "string",
                                        "format": "password",
                                        "description": "Clave SOL. Se reenvía al proveedor y nunca se registra.",
                                        "example": "CLAVE_SOL"
                                    },
                                    "nombre": {
                                        "type": "string",
                                        "maxLength": 100,
                                        "description": "Nombre de la aplicación.",
                                        "example": "mi-sistema"
                                    },
                                    "url": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "description": "URL de la aplicación (http:// o https://).",
                                        "example": "https://mi-sistema.pe"
                                    },
                                    "alcance": {
                                        "type": "string",
                                        "enum": [
                                            "desktop",
                                            "web"
                                        ],
                                        "description": "Tipo de alcance de la aplicación. Por defecto desktop.",
                                        "example": "desktop"
                                    },
                                    "recursos": {
                                        "type": "array",
                                        "minItems": 1,
                                        "maxItems": 50,
                                        "items": {
                                            "type": "string"
                                        },
                                        "description": "Rutas (`recurso`) del catálogo que devuelve `/credenciales-api` que deben quedar habilitadas.",
                                        "example": [
                                            "/v1/contribuyente/gem"
                                        ]
                                    }
                                }
                            },
                            "example": {
                                "ruc": "20123456789",
                                "usuario_sol": "USUARIO_SOL",
                                "clave_sol": "CLAVE_SOL",
                                "nombre": "mi-sistema",
                                "url": "https://mi-sistema.pe",
                                "alcance": "desktop",
                                "recursos": [
                                    []
                                ]
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Consulta resuelta.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/SuccessEnvelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "additionalProperties": true
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "success": true,
                                    "code": "created",
                                    "retryable": false,
                                    "data": {
                                        "tiene_aplicacion": true,
                                        "aplicacion": {
                                            "id": "ID_INTERNO_SUNAT",
                                            "codigo_aplicacion": "2020000000",
                                            "nombre": "mi-sistema",
                                            "url": "https://mi-sistema.pe",
                                            "alcance": "desktop",
                                            "client_id": "CLIENT_ID_EJEMPLO",
                                            "client_secret": "CLIENT_SECRET_EJEMPLO",
                                            "recursos": [
                                                {
                                                    "recurso": "/v1/contribuyente/gem",
                                                    "nombre": "GRE Emision de Comprobantes"
                                                }
                                            ]
                                        },
                                        "catalogo": [
                                            {
                                                "codigo": "2",
                                                "nombre": "MIGE RCE y RVIE - SIRE",
                                                "recurso": "/v1/contribuyente/migeigv",
                                                "url_api": "https://api-sire.sunat.gob.pe"
                                            },
                                            {
                                                "codigo": "3",
                                                "nombre": "GRE Emision de Comprobantes",
                                                "recurso": "/v1/contribuyente/gem",
                                                "url_api": "https://api-cpe.sunat.gob.pe"
                                            }
                                        ]
                                    },
                                    "time": 0.42
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "409": {
                        "description": "El RUC ya tiene una aplicación registrada (`aplicacion_existente`).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorEnvelope"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Campos inválidos o APIs fuera del catálogo (`datos_invalidos`).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorEnvelope"
                                }
                            }
                        }
                    },
                    "429": {
                        "$ref": "#/components/responses/TooManyRequests"
                    },
                    "502": {
                        "description": "SUNAT no aceptó los datos (`sunat_rechazo`).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorEnvelope"
                                }
                            }
                        }
                    },
                    "503": {
                        "description": "No se pudo iniciar sesión o abrir la gestión de credenciales (`servicio_no_disponible`, reintentable). También `rate_limit_unavailable` si el contador de límites no está disponible.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "oneOf": [
                                        {
                                            "$ref": "#/components/schemas/ErrorEnvelope"
                                        },
                                        {
                                            "$ref": "#/components/schemas/AccessError"
                                        }
                                    ]
                                }
                            }
                        }
                    }
                },
                "x-consumo-unidades": "1 por solicitud",
                "x-estado-verificacion": "pendiente_validacion_externa"
            }
        },
        "/api/v1/credenciales-api/editar": {
            "post": {
                "tags": [
                    "Credenciales API SUNAT"
                ],
                "operationId": "credencialesApiEditar",
                "summary": "Editar aplicación de API SUNAT",
                "description": "Cambia nombre, URL, alcance o APIs habilitadas de la aplicación ya registrada. Envíe la lista completa de `recursos` que deben quedar. Cambia la cuenta SOL; si el RUC no tiene aplicación responde 404.\n\n**Consumo:** 1 por solicitud. Una consulta validada que se envía al proveedor consume cuota aunque el proveedor responda con error (ADR-005). Los rechazos de validación (422), autenticación, límite o duplicado no consumen.",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/IdempotencyKey"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "ruc",
                                    "usuario_sol",
                                    "clave_sol",
                                    "nombre",
                                    "url",
                                    "recursos"
                                ],
                                "properties": {
                                    "ruc": {
                                        "type": "string",
                                        "pattern": "^\\d{11}$",
                                        "description": "RUC de 11 dígitos.",
                                        "example": "20123456789"
                                    },
                                    "usuario_sol": {
                                        "type": "string",
                                        "description": "Usuario SOL del RUC consultado. Se reenvía al proveedor y nunca se registra.",
                                        "example": "USUARIO_SOL"
                                    },
                                    "clave_sol": {
                                        "type": "string",
                                        "format": "password",
                                        "description": "Clave SOL. Se reenvía al proveedor y nunca se registra.",
                                        "example": "CLAVE_SOL"
                                    },
                                    "nombre": {
                                        "type": "string",
                                        "maxLength": 100,
                                        "description": "Nombre de la aplicación.",
                                        "example": "mi-sistema"
                                    },
                                    "url": {
                                        "type": "string",
                                        "maxLength": 255,
                                        "description": "URL de la aplicación (http:// o https://).",
                                        "example": "https://mi-sistema.pe"
                                    },
                                    "alcance": {
                                        "type": "string",
                                        "enum": [
                                            "desktop",
                                            "web"
                                        ],
                                        "description": "Tipo de alcance de la aplicación. Por defecto desktop.",
                                        "example": "desktop"
                                    },
                                    "recursos": {
                                        "type": "array",
                                        "minItems": 1,
                                        "maxItems": 50,
                                        "items": {
                                            "type": "string"
                                        },
                                        "description": "Rutas (`recurso`) del catálogo que devuelve `/credenciales-api` que deben quedar habilitadas.",
                                        "example": [
                                            "/v1/contribuyente/gem"
                                        ]
                                    }
                                }
                            },
                            "example": {
                                "ruc": "20123456789",
                                "usuario_sol": "USUARIO_SOL",
                                "clave_sol": "CLAVE_SOL",
                                "nombre": "mi-sistema",
                                "url": "https://mi-sistema.pe",
                                "alcance": "desktop",
                                "recursos": [
                                    []
                                ]
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Consulta resuelta.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/SuccessEnvelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "additionalProperties": true
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "success": true,
                                    "code": "updated",
                                    "retryable": false,
                                    "data": {
                                        "tiene_aplicacion": true,
                                        "aplicacion": {
                                            "id": "ID_INTERNO_SUNAT",
                                            "codigo_aplicacion": "2020000000",
                                            "nombre": "mi-sistema",
                                            "url": "https://mi-sistema.pe",
                                            "alcance": "desktop",
                                            "client_id": "CLIENT_ID_EJEMPLO",
                                            "client_secret": "CLIENT_SECRET_EJEMPLO",
                                            "recursos": [
                                                {
                                                    "recurso": "/v1/contribuyente/gem",
                                                    "nombre": "GRE Emision de Comprobantes"
                                                }
                                            ]
                                        },
                                        "catalogo": [
                                            {
                                                "codigo": "2",
                                                "nombre": "MIGE RCE y RVIE - SIRE",
                                                "recurso": "/v1/contribuyente/migeigv",
                                                "url_api": "https://api-sire.sunat.gob.pe"
                                            },
                                            {
                                                "codigo": "3",
                                                "nombre": "GRE Emision de Comprobantes",
                                                "recurso": "/v1/contribuyente/gem",
                                                "url_api": "https://api-cpe.sunat.gob.pe"
                                            }
                                        ]
                                    },
                                    "time": 0.42
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "description": "El RUC no tiene aplicación registrada (`sin_aplicacion`).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorEnvelope"
                                }
                            }
                        }
                    },
                    "409": {
                        "$ref": "#/components/responses/DuplicateRequest"
                    },
                    "422": {
                        "description": "Campos inválidos o APIs fuera del catálogo (`datos_invalidos`).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorEnvelope"
                                }
                            }
                        }
                    },
                    "429": {
                        "$ref": "#/components/responses/TooManyRequests"
                    },
                    "502": {
                        "description": "SUNAT no aceptó los datos (`sunat_rechazo`).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorEnvelope"
                                }
                            }
                        }
                    },
                    "503": {
                        "description": "No se pudo iniciar sesión o abrir la gestión de credenciales (`servicio_no_disponible`, reintentable). También `rate_limit_unavailable` si el contador de límites no está disponible.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "oneOf": [
                                        {
                                            "$ref": "#/components/schemas/ErrorEnvelope"
                                        },
                                        {
                                            "$ref": "#/components/schemas/AccessError"
                                        }
                                    ]
                                }
                            }
                        }
                    }
                },
                "x-consumo-unidades": "1 por solicitud",
                "x-estado-verificacion": "pendiente_validacion_externa"
            }
        },
        "/api/v1/dni": {
            "post": {
                "tags": [
                    "Identidad"
                ],
                "operationId": "dni",
                "summary": "Consulta DNI",
                "description": "Consulta el nombre asociado a un DNI por un solo filtro: primero el Padrón Reducido por el RUC 10 de la persona (`source: padron_reducido`) y, si no está, el portal público de SUNAT en línea (`source: sunat_en_linea`). Solo se encuentran personas registradas como contribuyentes en SUNAT. La respuesta trae apellidos y nombres por separado.\n\n**Consumo:** 1 por solicitud. Una consulta validada que se envía al proveedor consume cuota aunque el proveedor responda con error (ADR-005). Los rechazos de validación (422), autenticación, límite o duplicado no consumen.",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/IdempotencyKey"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "dni"
                                ],
                                "properties": {
                                    "dni": {
                                        "type": "string",
                                        "pattern": "^\\d{8}$",
                                        "example": "12345678"
                                    }
                                }
                            },
                            "example": {
                                "dni": "12345678"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Consulta resuelta.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/SuccessEnvelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "additionalProperties": true
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "success": true,
                                    "code": "found",
                                    "retryable": false,
                                    "data": {
                                        "numero": "12345678",
                                        "nombre_completo": "PEREZ LOPEZ ANA MARIA",
                                        "nombres": "ANA MARIA",
                                        "apellido_paterno": "PEREZ",
                                        "apellido_materno": "LOPEZ",
                                        "codigo_verificacion": 0
                                    },
                                    "time": 0.42,
                                    "source": "padron_reducido"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "description": "No hay un contribuyente con ese DNI (`not_found`, `retryable: false`) o el proveedor no pudo completar la consulta (código del proveedor, `retryable: true`).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorEnvelope"
                                }
                            }
                        }
                    },
                    "409": {
                        "$ref": "#/components/responses/DuplicateRequest"
                    },
                    "422": {
                        "description": "DNI inválido (`invalid_dni`) o campos faltantes.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorEnvelope"
                                }
                            }
                        }
                    },
                    "429": {
                        "$ref": "#/components/responses/TooManyRequests"
                    },
                    "502": {
                        "description": "El servicio de consultas no pudo completar la solicitud (`servicio_error`, `retryable: true`).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorEnvelope"
                                }
                            }
                        }
                    },
                    "503": {
                        "description": "El servicio de consultas no está disponible (`servicio_no_disponible`, `retryable: true`). Reintente en unos segundos. También `rate_limit_unavailable` si el contador de límites no está disponible.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "oneOf": [
                                        {
                                            "$ref": "#/components/schemas/ErrorEnvelope"
                                        },
                                        {
                                            "$ref": "#/components/schemas/AccessError"
                                        }
                                    ]
                                }
                            }
                        }
                    }
                },
                "x-consumo-unidades": "1 por solicitud",
                "x-estado-verificacion": "pendiente_validacion_externa"
            }
        },
        "/api/v1/dni-ruc": {
            "post": {
                "tags": [
                    "Identidad"
                ],
                "operationId": "dniRuc",
                "summary": "Consulta RUC por DNI",
                "description": "Devuelve el RUC asociado a un DNI. Si el DNI no tiene RUC, responde 404 `document_not_found`.\n\n**Consumo:** 1 por solicitud. Una consulta validada que se envía al proveedor consume cuota aunque el proveedor responda con error (ADR-005). Los rechazos de validación (422), autenticación, límite o duplicado no consumen.",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/IdempotencyKey"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "dni"
                                ],
                                "properties": {
                                    "dni": {
                                        "type": "string",
                                        "pattern": "^\\d{8}$",
                                        "description": "Número de DNI de 8 dígitos.",
                                        "example": "44556677"
                                    }
                                }
                            },
                            "example": {
                                "dni": "44556677"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Consulta resuelta.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/SuccessEnvelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "additionalProperties": true
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "success": true,
                                    "code": "found",
                                    "retryable": false,
                                    "data": {
                                        "ruc": "10445566778"
                                    },
                                    "time": 0.42
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "DNI inválido (`invalid_input`, `retryable: false`).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorEnvelope"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "description": "El DNI no cuenta con RUC (`document_not_found`, `retryable: false`).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorEnvelope"
                                }
                            }
                        }
                    },
                    "409": {
                        "$ref": "#/components/responses/DuplicateRequest"
                    },
                    "429": {
                        "$ref": "#/components/responses/TooManyRequests"
                    },
                    "503": {
                        "description": "Servicio de consulta no disponible (`upstream_unavailable`, `retryable: true`). Reintentar en unos segundos. También `rate_limit_unavailable` si el contador de límites no está disponible.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "oneOf": [
                                        {
                                            "$ref": "#/components/schemas/ErrorEnvelope"
                                        },
                                        {
                                            "$ref": "#/components/schemas/AccessError"
                                        }
                                    ]
                                }
                            }
                        }
                    }
                },
                "x-consumo-unidades": "1 por solicitud",
                "x-estado-verificacion": "pendiente_validacion_externa"
            }
        },
        "/api/v1/padron/buscar": {
            "get": {
                "tags": [
                    "Padrón y datos públicos"
                ],
                "operationId": "padronBusqueda",
                "summary": "Búsqueda por razón social",
                "description": "Busca contribuyentes por razón social en la copia local del Padrón Reducido. Devuelve una lista (vacía si no hay coincidencias).\n\n**Consumo:** 1 por solicitud. Una consulta validada que se envía al proveedor consume cuota aunque el proveedor responda con error (ADR-005). Los rechazos de validación (422), autenticación, límite o duplicado no consumen.",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/IdempotencyKey"
                    },
                    {
                        "name": "q",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "minLength": 2,
                            "maxLength": 120
                        },
                        "description": "Texto de la razón social.",
                        "example": "DEMOSTRACION"
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 100,
                            "default": 20
                        },
                        "description": "Máximo de resultados."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Consulta resuelta.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/SuccessEnvelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "array",
                                                    "items": {
                                                        "type": "object",
                                                        "additionalProperties": true
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "success": true,
                                    "code": "found",
                                    "retryable": false,
                                    "data": [
                                        {
                                            "ruc": "20123456789",
                                            "nombre_razon_social": "EMPRESA DEMOSTRACION S.A.C.",
                                            "estado": "ACTIVO",
                                            "condicion": "HABIDO",
                                            "ubigeo": "150101",
                                            "domicilio_fiscal": "AV. EJEMPLO 123",
                                            "updated_at": "2026-10-01T00:00:00+00:00"
                                        }
                                    ],
                                    "time": 0.42,
                                    "source": "sunat_padron_reducido"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "409": {
                        "$ref": "#/components/responses/DuplicateRequest"
                    },
                    "422": {
                        "description": "Texto de búsqueda ausente o fuera de rango.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorEnvelope"
                                }
                            }
                        }
                    },
                    "429": {
                        "$ref": "#/components/responses/TooManyRequests"
                    },
                    "502": {
                        "description": "Error del proveedor (`proveedor_error`).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorEnvelope"
                                }
                            }
                        }
                    },
                    "503": {
                        "description": "El dataset no está importado (`dataset_no_disponible`) o el servicio no responde (`servicio_no_disponible`). También `rate_limit_unavailable` si el contador de límites no está disponible.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "oneOf": [
                                        {
                                            "$ref": "#/components/schemas/ErrorEnvelope"
                                        },
                                        {
                                            "$ref": "#/components/schemas/AccessError"
                                        }
                                    ]
                                }
                            }
                        }
                    }
                },
                "x-consumo-unidades": "1 por solicitud",
                "x-estado-verificacion": "simulada"
            }
        },
        "/api/v1/padron/ruc": {
            "post": {
                "tags": [
                    "Padrón y datos públicos"
                ],
                "operationId": "padronRuc",
                "summary": "Consulta RUC en el Padrón Reducido",
                "description": "Busca el RUC en la copia local del Padrón Reducido oficial de SUNAT importada en el servicio. No usa navegador ni credenciales. Responde 404 si el RUC no figura en la copia local (incluido el caso de un padrón aún no importado).\n\n**Consumo:** 1 por solicitud. Una consulta validada que se envía al proveedor consume cuota aunque el proveedor responda con error (ADR-005). Los rechazos de validación (422), autenticación, límite o duplicado no consumen.",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/IdempotencyKey"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "ruc"
                                ],
                                "properties": {
                                    "ruc": {
                                        "type": "string",
                                        "pattern": "^\\d{11}$",
                                        "description": "RUC de 11 dígitos.",
                                        "example": "20123456789"
                                    }
                                }
                            },
                            "example": {
                                "ruc": "20123456789"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Consulta resuelta.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/SuccessEnvelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "additionalProperties": true
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "success": true,
                                    "code": "found",
                                    "retryable": false,
                                    "data": {
                                        "ruc": "20123456789",
                                        "nombre_razon_social": "EMPRESA DEMOSTRACION S.A.C.",
                                        "estado": "ACTIVO",
                                        "condicion": "HABIDO",
                                        "ubigeo": "150101",
                                        "domicilio_fiscal": "AV. EJEMPLO 123",
                                        "updated_at": "2026-10-01T00:00:00+00:00"
                                    },
                                    "time": 0.42,
                                    "source": "sunat_padron_reducido"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "description": "Registro no encontrado en la fuente local (`not_found`).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorEnvelope"
                                }
                            }
                        }
                    },
                    "409": {
                        "$ref": "#/components/responses/DuplicateRequest"
                    },
                    "422": {
                        "description": "RUC inválido.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorEnvelope"
                                }
                            }
                        }
                    },
                    "429": {
                        "$ref": "#/components/responses/TooManyRequests"
                    },
                    "502": {
                        "description": "Error del proveedor (`proveedor_error`).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorEnvelope"
                                }
                            }
                        }
                    },
                    "503": {
                        "description": "El dataset no está importado (`dataset_no_disponible`) o el servicio no responde (`servicio_no_disponible`). También `rate_limit_unavailable` si el contador de límites no está disponible.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "oneOf": [
                                        {
                                            "$ref": "#/components/schemas/ErrorEnvelope"
                                        },
                                        {
                                            "$ref": "#/components/schemas/AccessError"
                                        }
                                    ]
                                }
                            }
                        }
                    }
                },
                "x-consumo-unidades": "1 por solicitud",
                "x-estado-verificacion": "simulada"
            }
        },
        "/api/v1/pasaporte": {
            "post": {
                "tags": [
                    "Identidad"
                ],
                "operationId": "pasaporte",
                "summary": "Consulta por Pasaporte",
                "description": "Busca en el portal público de SUNAT al contribuyente registrado con ese documento: nombre, RUC, estado y ubicación. Solo se encuentran personas inscritas en SUNAT. Si la consulta en línea está desactivada responde 503 `fuente_desactivada`.\n\n**Consumo:** 1 por solicitud. Una consulta validada que se envía al proveedor consume cuota aunque el proveedor responda con error (ADR-005). Los rechazos de validación (422), autenticación, límite o duplicado no consumen.",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/IdempotencyKey"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "numero"
                                ],
                                "properties": {
                                    "numero": {
                                        "type": "string",
                                        "pattern": "^[A-Za-z0-9]{4,15}$",
                                        "description": "Número del documento (4 a 15 letras o dígitos).",
                                        "example": "X1234567"
                                    }
                                }
                            },
                            "example": {
                                "numero": "X1234567"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Consulta resuelta.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/SuccessEnvelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "additionalProperties": true
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "success": true,
                                    "code": "found",
                                    "retryable": false,
                                    "data": {
                                        "tipo_documento": "pasaporte",
                                        "numero": "X1234567",
                                        "nombre_completo": "PEREZ LOPEZ ANA MARIA",
                                        "nombres": "ANA MARIA",
                                        "apellido_paterno": "PEREZ",
                                        "apellido_materno": "LOPEZ",
                                        "ruc": "15600000001",
                                        "estado": "ACTIVO",
                                        "ubicacion": "LIMA - LIMA - MIRAFLORES"
                                    },
                                    "time": 0.42,
                                    "source": "sunat_en_linea"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "description": "No hay un contribuyente con ese documento (`not_found`, `retryable: false`).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorEnvelope"
                                }
                            }
                        }
                    },
                    "409": {
                        "$ref": "#/components/responses/DuplicateRequest"
                    },
                    "422": {
                        "description": "Número inválido (`invalid_documento`) o campo faltante.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorEnvelope"
                                }
                            }
                        }
                    },
                    "429": {
                        "$ref": "#/components/responses/TooManyRequests"
                    },
                    "502": {
                        "description": "Error del proveedor (`proveedor_error`, reintentable).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorEnvelope"
                                }
                            }
                        }
                    },
                    "503": {
                        "description": "Consulta en línea desactivada (`fuente_desactivada`) o servicio no disponible (`no_disponible`, `servicio_no_disponible`); reintentable. También `rate_limit_unavailable` si el contador de límites no está disponible.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "oneOf": [
                                        {
                                            "$ref": "#/components/schemas/ErrorEnvelope"
                                        },
                                        {
                                            "$ref": "#/components/schemas/AccessError"
                                        }
                                    ]
                                }
                            }
                        }
                    }
                },
                "x-consumo-unidades": "1 por solicitud",
                "x-estado-verificacion": "pendiente_validacion_externa"
            }
        },
        "/api/v1/puertos": {
            "get": {
                "tags": [
                    "Padrón y datos públicos"
                ],
                "operationId": "puertos",
                "summary": "Puertos (MTC)",
                "description": "Busca puertos en el dataset oficial del MTC importado en el servicio.\n\n**Consumo:** 1 por solicitud. Una consulta validada que se envía al proveedor consume cuota aunque el proveedor responda con error (ADR-005). Los rechazos de validación (422), autenticación, límite o duplicado no consumen.",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/IdempotencyKey"
                    },
                    {
                        "name": "q",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "maxLength": 120
                        },
                        "description": "Texto a buscar en el registro. Vacío devuelve los primeros registros.",
                        "example": "LIMA"
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 100,
                            "default": 50
                        },
                        "description": "Máximo de registros."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Consulta resuelta.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/SuccessEnvelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "array",
                                                    "items": {
                                                        "type": "object",
                                                        "additionalProperties": true,
                                                        "description": "Registro del dataset oficial importado; las columnas dependen de la fuente."
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "success": true,
                                    "code": "found",
                                    "retryable": false,
                                    "data": [
                                        {
                                            "codigo": "PECLL",
                                            "nombre": "CALLAO"
                                        }
                                    ],
                                    "time": 0.42,
                                    "source": "puertos"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "409": {
                        "$ref": "#/components/responses/DuplicateRequest"
                    },
                    "422": {
                        "description": "Parámetros inválidos.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorEnvelope"
                                }
                            }
                        }
                    },
                    "429": {
                        "$ref": "#/components/responses/TooManyRequests"
                    },
                    "502": {
                        "description": "Error del proveedor (`proveedor_error`).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorEnvelope"
                                }
                            }
                        }
                    },
                    "503": {
                        "description": "El dataset no está importado (`dataset_no_disponible`) o el servicio no responde (`servicio_no_disponible`). También `rate_limit_unavailable` si el contador de límites no está disponible.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "oneOf": [
                                        {
                                            "$ref": "#/components/schemas/ErrorEnvelope"
                                        },
                                        {
                                            "$ref": "#/components/schemas/AccessError"
                                        }
                                    ]
                                }
                            }
                        }
                    }
                },
                "x-consumo-unidades": "1 por solicitud",
                "x-estado-verificacion": "simulada"
            }
        },
        "/api/v1/razon-social": {
            "post": {
                "tags": [
                    "Identidad"
                ],
                "operationId": "razonSocial",
                "summary": "Búsqueda por razón social en línea",
                "description": "Busca contribuyentes por nombre o razón social en el portal público de SUNAT. Para una búsqueda sin navegador, usar `/api/v1/padron/buscar`.\n\n**Consumo:** 1 por solicitud. Una consulta validada que se envía al proveedor consume cuota aunque el proveedor responda con error (ADR-005). Los rechazos de validación (422), autenticación, límite o duplicado no consumen.",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/IdempotencyKey"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "razon_social"
                                ],
                                "properties": {
                                    "razon_social": {
                                        "type": "string",
                                        "minLength": 3,
                                        "maxLength": 120,
                                        "example": "EMPRESA DEMOSTRACION"
                                    }
                                }
                            },
                            "example": {
                                "razon_social": "EMPRESA DEMOSTRACION"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Consulta resuelta.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/SuccessEnvelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "additionalProperties": true
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "success": true,
                                    "code": "found",
                                    "retryable": false,
                                    "data": {
                                        "resultados": [
                                            {
                                                "ruc": "20123456789",
                                                "razon_social": "EMPRESA DEMOSTRACION S.A.C."
                                            }
                                        ]
                                    },
                                    "time": 0.42
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "description": "Sin coincidencias (`not_found`).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorEnvelope"
                                }
                            }
                        }
                    },
                    "409": {
                        "$ref": "#/components/responses/DuplicateRequest"
                    },
                    "422": {
                        "description": "Texto ausente, menor de 3 caracteres o mayor de 120.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorEnvelope"
                                }
                            }
                        }
                    },
                    "429": {
                        "$ref": "#/components/responses/TooManyRequests"
                    },
                    "502": {
                        "description": "El proveedor no pudo completar la consulta (código del proveedor, `retryable: true`).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorEnvelope"
                                }
                            }
                        }
                    },
                    "503": {
                        "description": "El servicio de consultas no está disponible (`servicio_no_disponible`, `retryable: true`). Reintente en unos segundos. También `rate_limit_unavailable` si el contador de límites no está disponible.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "oneOf": [
                                        {
                                            "$ref": "#/components/schemas/ErrorEnvelope"
                                        },
                                        {
                                            "$ref": "#/components/schemas/AccessError"
                                        }
                                    ]
                                }
                            }
                        }
                    }
                },
                "x-consumo-unidades": "1 por solicitud",
                "x-estado-verificacion": "pendiente_validacion_externa"
            }
        },
        "/api/v1/ruc": {
            "post": {
                "tags": [
                    "Identidad"
                ],
                "operationId": "ruc",
                "summary": "Consulta RUC",
                "description": "Consulta un RUC por un solo filtro: primero el Padrón Reducido oficial (`source: padron_reducido`, instantáneo; trae razón social, estado, condición y domicilio) y, si el RUC no está ahí o el padrón no está disponible, el portal público de SUNAT en línea (`source: sunat_en_linea`, ficha completa). Si la consulta en línea está desactivada, solo responde el padrón.\n\n**Consumo:** 1 por solicitud. Una consulta validada que se envía al proveedor consume cuota aunque el proveedor responda con error (ADR-005). Los rechazos de validación (422), autenticación, límite o duplicado no consumen.",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/IdempotencyKey"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "ruc"
                                ],
                                "properties": {
                                    "ruc": {
                                        "type": "string",
                                        "pattern": "^\\d{11}$",
                                        "description": "RUC de 11 dígitos.",
                                        "example": "20123456789"
                                    }
                                }
                            },
                            "example": {
                                "ruc": "20123456789"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Consulta resuelta.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/SuccessEnvelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "additionalProperties": true
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "success": true,
                                    "code": "found",
                                    "retryable": false,
                                    "data": {
                                        "ruc": "20123456789",
                                        "nombre_o_razon_social": "EMPRESA DEMOSTRACION S.A.C.",
                                        "estado": "ACTIVO",
                                        "condicion": "HABIDO",
                                        "direccion": "AV. EJEMPLO 123 LIMA - LIMA - LIMA",
                                        "departamento": "LIMA",
                                        "tipo_contribuyente": "SOCIEDAD ANONIMA CERRADA",
                                        "fecha_inscripcion": "01/01/2020",
                                        "fecha_inicio_actividades": "01/01/2020",
                                        "actividades_economicas": [
                                            "Principal - 6201 - ACTIVIDADES DE PROGRAMACION INFORMATICA"
                                        ],
                                        "sistema_emision": "MANUAL/COMPUTARIZADO",
                                        "sistema_contabilidad": "COMPUTARIZADO",
                                        "es_agente_de_retencion": "NO",
                                        "es_buen_contribuyente": "NO"
                                    },
                                    "time": 0.42,
                                    "source": "padron_reducido"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "description": "El RUC no existe en SUNAT (`not_found`, `retryable: false`) o SUNAT no respondió (`retryable: true`). Distinga ambos casos con `code` y `retryable`.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorEnvelope"
                                }
                            }
                        }
                    },
                    "409": {
                        "$ref": "#/components/responses/DuplicateRequest"
                    },
                    "422": {
                        "description": "RUC inválido (`invalid_ruc`) o campos faltantes.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorEnvelope"
                                }
                            }
                        }
                    },
                    "429": {
                        "$ref": "#/components/responses/TooManyRequests"
                    },
                    "502": {
                        "description": "El servicio de consultas no pudo completar la solicitud (`servicio_error`, `retryable: true`).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorEnvelope"
                                }
                            }
                        }
                    },
                    "503": {
                        "description": "El servicio de consultas no está disponible (`servicio_no_disponible`, `retryable: true`). Reintente en unos segundos. También `rate_limit_unavailable` si el contador de límites no está disponible.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "oneOf": [
                                        {
                                            "$ref": "#/components/schemas/ErrorEnvelope"
                                        },
                                        {
                                            "$ref": "#/components/schemas/AccessError"
                                        }
                                    ]
                                }
                            }
                        }
                    }
                },
                "x-consumo-unidades": "1 por solicitud",
                "x-estado-verificacion": "pendiente_validacion_externa"
            }
        },
        "/api/v1/ruc-sunat": {
            "post": {
                "tags": [
                    "Identidad"
                ],
                "operationId": "rucSunat",
                "summary": "Consulta RUC (ficha SUNAT)",
                "description": "Consulta un RUC y devuelve la ficha con la dirección completa, tipo de contribuyente, fecha de inscripción y actividades económicas. Mismos datos que `/api/v1/ruc`, con el formato de respuesta publicado para integraciones tipo FactosPerú.\n\n**Consumo:** 1 por solicitud. Una consulta validada que se envía al proveedor consume cuota aunque el proveedor responda con error (ADR-005). Los rechazos de validación (422), autenticación, límite o duplicado no consumen.",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/IdempotencyKey"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "ruc"
                                ],
                                "properties": {
                                    "ruc": {
                                        "type": "string",
                                        "pattern": "^\\d{11}$",
                                        "description": "RUC de 11 dígitos.",
                                        "example": "20123456789"
                                    }
                                }
                            },
                            "example": {
                                "ruc": "20123456789"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Consulta resuelta.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/SuccessEnvelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "additionalProperties": true
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "success": true,
                                    "code": "found",
                                    "retryable": false,
                                    "data": {
                                        "ruc": "20123456789",
                                        "nombre_o_razon_social": "EMPRESA DEMOSTRACION S.A.C.",
                                        "estado": "ACTIVO",
                                        "condicion": "HABIDO",
                                        "direccion_completa": "AV. EJEMPLO 123 LIMA - LIMA - LIMA",
                                        "tipo_contribuyente": "SOCIEDAD ANONIMA CERRADA",
                                        "fecha_inscripcion": "01/01/2020",
                                        "actividades_economicas": [
                                            "Principal - 6201 - ACTIVIDADES DE PROGRAMACION INFORMATICA"
                                        ]
                                    },
                                    "time": 0.42
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "RUC inválido (`invalid_input`, `retryable: false`).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorEnvelope"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "description": "El RUC no existe (`document_not_found`, `retryable: false`).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorEnvelope"
                                }
                            }
                        }
                    },
                    "409": {
                        "$ref": "#/components/responses/DuplicateRequest"
                    },
                    "429": {
                        "$ref": "#/components/responses/TooManyRequests"
                    },
                    "503": {
                        "description": "Servicio de consulta no disponible (`upstream_unavailable`, `retryable: true`). Reintentar en unos segundos. También `rate_limit_unavailable` si el contador de límites no está disponible.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "oneOf": [
                                        {
                                            "$ref": "#/components/schemas/ErrorEnvelope"
                                        },
                                        {
                                            "$ref": "#/components/schemas/AccessError"
                                        }
                                    ]
                                }
                            }
                        }
                    }
                },
                "x-consumo-unidades": "1 por solicitud",
                "x-estado-verificacion": "pendiente_validacion_externa"
            }
        },
        "/api/v1/ruc/excluido": {
            "post": {
                "tags": [
                    "Comprobantes"
                ],
                "operationId": "cpeRucExcluido",
                "summary": "Consulta CPE de un RUC excluido",
                "description": "Consulta un comprobante en el proveedor alternativo configurado para RUC excluidos (portal público de Sovos, p. ej. BCP). Entrega PDF y XML; el CDR se devuelve como null porque la fuente no lo proporciona. `documento` trae el estado en el proveedor, emisor y receptor; `fuente` indica `en_linea` o `cache` (un comprobante ya consultado se responde desde la caché sin volver al proveedor).\n\n**Consumo:** 1 por solicitud. Una consulta validada que se envía al proveedor consume cuota aunque el proveedor responda con error (ADR-005). Los rechazos de validación (422), autenticación, límite o duplicado no consumen.",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/IdempotencyKey"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "ruc",
                                    "tipo",
                                    "folio",
                                    "fecha",
                                    "total"
                                ],
                                "properties": {
                                    "ruc": {
                                        "type": "string",
                                        "pattern": "^\\d{11}$",
                                        "description": "RUC de 11 dígitos.",
                                        "example": "20123456789"
                                    },
                                    "tipo": {
                                        "type": "string",
                                        "enum": [
                                            "01",
                                            "03",
                                            "07",
                                            "08"
                                        ],
                                        "example": "01"
                                    },
                                    "folio": {
                                        "type": "string",
                                        "example": "FA02-0000000"
                                    },
                                    "fecha": {
                                        "type": "string",
                                        "format": "date",
                                        "example": "2026-10-08"
                                    },
                                    "total": {
                                        "type": "string",
                                        "example": "0.00"
                                    }
                                }
                            },
                            "example": {
                                "ruc": "20123456789",
                                "tipo": "01",
                                "folio": "FA02-0000000",
                                "fecha": "2026-10-08",
                                "total": "0.00"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Consulta resuelta.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/SuccessEnvelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "additionalProperties": true
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "success": true,
                                    "code": "found",
                                    "retryable": false,
                                    "data": {
                                        "provider": "bcp_sovos",
                                        "datos": {
                                            "ruc": "20123456789",
                                            "tipo": "01",
                                            "folio": "FA02-0000000",
                                            "fecha": "2026-10-08",
                                            "total": "0.00"
                                        },
                                        "archivos": {
                                            "pdf": {
                                                "base64": "BASE64_PDF",
                                                "mime": "application/pdf",
                                                "size": 12345
                                            },
                                            "xml": {
                                                "base64": "BASE64_XML",
                                                "mime": "application/xml",
                                                "size": 6789
                                            },
                                            "cdr": null
                                        },
                                        "documento": {
                                            "estado": "document.authorized",
                                            "estado_descripcion": "Authorized",
                                            "emisor": "BANCO DE CREDITO DEL PERU",
                                            "receptor": "EMPRESA DEMO SAC"
                                        },
                                        "fuente": "en_linea"
                                    },
                                    "time": 0.42
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "description": "El comprobante no existe en el proveedor (`not_found`, `retryable: false`): revise RUC, tipo, serie-número, fecha y total.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorEnvelope"
                                }
                            }
                        }
                    },
                    "409": {
                        "$ref": "#/components/responses/DuplicateRequest"
                    },
                    "422": {
                        "description": "Campos inválidos.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorEnvelope"
                                }
                            }
                        }
                    },
                    "429": {
                        "$ref": "#/components/responses/TooManyRequests"
                    },
                    "502": {
                        "description": "El proveedor alternativo no pudo completar la consulta (`proveedor_error`) o excedió el tiempo de espera (`timeout`); ambos reintentables.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorEnvelope"
                                }
                            }
                        }
                    },
                    "503": {
                        "description": "El proveedor alternativo no está habilitado (`proveedor_no_disponible`). También `rate_limit_unavailable` si el contador de límites no está disponible.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "oneOf": [
                                        {
                                            "$ref": "#/components/schemas/ErrorEnvelope"
                                        },
                                        {
                                            "$ref": "#/components/schemas/AccessError"
                                        }
                                    ]
                                }
                            }
                        }
                    }
                },
                "x-consumo-unidades": "1 por solicitud",
                "x-estado-verificacion": "pendiente_validacion_externa"
            }
        },
        "/api/v1/ruc/{ruc}/establecimientos": {
            "get": {
                "tags": [
                    "Padrón y datos públicos"
                ],
                "operationId": "establecimientos",
                "summary": "Establecimientos anexos de un RUC",
                "description": "Lista los establecimientos anexos del RUC según el dataset oficial importado en el servicio.\n\n**Consumo:** 1 por solicitud. Una consulta validada que se envía al proveedor consume cuota aunque el proveedor responda con error (ADR-005). Los rechazos de validación (422), autenticación, límite o duplicado no consumen.",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/IdempotencyKey"
                    },
                    {
                        "name": "ruc",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "pattern": "^\\d{11}$"
                        },
                        "example": "20123456789"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Consulta resuelta.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/SuccessEnvelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "array",
                                                    "items": {
                                                        "type": "object",
                                                        "additionalProperties": true,
                                                        "description": "Registro del dataset oficial importado; las columnas dependen de la fuente."
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "success": true,
                                    "code": "found",
                                    "retryable": false,
                                    "data": [
                                        {
                                            "ruc": "20123456789",
                                            "codigo": "0001",
                                            "tipo": "SUCURSAL",
                                            "direccion": "AV. EJEMPLO 456"
                                        }
                                    ],
                                    "time": 0.42,
                                    "source": "sunat_establecimientos"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "description": "Registro no encontrado en la fuente local (`not_found`).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorEnvelope"
                                }
                            }
                        }
                    },
                    "409": {
                        "$ref": "#/components/responses/DuplicateRequest"
                    },
                    "422": {
                        "description": "RUC inválido.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorEnvelope"
                                }
                            }
                        }
                    },
                    "429": {
                        "$ref": "#/components/responses/TooManyRequests"
                    },
                    "502": {
                        "description": "Error del proveedor (`proveedor_error`).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorEnvelope"
                                }
                            }
                        }
                    },
                    "503": {
                        "description": "El dataset no está importado (`dataset_no_disponible`) o el servicio no responde (`servicio_no_disponible`). También `rate_limit_unavailable` si el contador de límites no está disponible.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "oneOf": [
                                        {
                                            "$ref": "#/components/schemas/ErrorEnvelope"
                                        },
                                        {
                                            "$ref": "#/components/schemas/AccessError"
                                        }
                                    ]
                                }
                            }
                        }
                    }
                },
                "x-consumo-unidades": "1 por solicitud",
                "x-estado-verificacion": "simulada"
            }
        },
        "/api/v1/sire/token": {
            "post": {
                "tags": [
                    "SIRE"
                ],
                "operationId": "sireToken",
                "summary": "Obtener token de pantalla SIRE",
                "description": "Obtiene el token de Ventas o Compras mediante SOL. No presenta libros. No se garantiza equivalencia con el token OAuth de la API pública SIRE. La respuesta no debe almacenarse ni registrarse.\n\n**Consumo:** 1 por solicitud. Una consulta validada que se envía al proveedor consume cuota aunque el proveedor responda con error (ADR-005). Los rechazos de validación (422), autenticación, límite o duplicado no consumen.",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/IdempotencyKey"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "ruc",
                                    "usuario_sol",
                                    "clave_sol",
                                    "libro"
                                ],
                                "properties": {
                                    "ruc": {
                                        "type": "string",
                                        "pattern": "^\\d{11}$",
                                        "description": "RUC de 11 dígitos.",
                                        "example": "20123456789"
                                    },
                                    "usuario_sol": {
                                        "type": "string",
                                        "description": "Usuario SOL del RUC consultado. Se reenvía al proveedor y nunca se registra.",
                                        "example": "USUARIO_SOL"
                                    },
                                    "clave_sol": {
                                        "type": "string",
                                        "format": "password",
                                        "description": "Clave SOL. Se reenvía al proveedor y nunca se registra.",
                                        "example": "CLAVE_SOL"
                                    },
                                    "libro": {
                                        "type": "string",
                                        "enum": [
                                            "ventas",
                                            "compras"
                                        ],
                                        "example": "ventas"
                                    }
                                }
                            },
                            "example": {
                                "ruc": "20123456789",
                                "usuario_sol": "USUARIO_SOL",
                                "clave_sol": "CLAVE_SOL",
                                "libro": "ventas"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Consulta resuelta.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/SuccessEnvelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "additionalProperties": true
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "success": true,
                                    "code": "found",
                                    "retryable": false,
                                    "data": {
                                        "access_token": "TOKEN_FICTICIO",
                                        "token_type": "Bearer",
                                        "libro": "ventas",
                                        "menu": "60.2.1.1.1",
                                        "origen": "menu_sol"
                                    },
                                    "time": 0.42
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "409": {
                        "$ref": "#/components/responses/DuplicateRequest"
                    },
                    "422": {
                        "description": "Campos inválidos.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorEnvelope"
                                }
                            }
                        }
                    },
                    "429": {
                        "$ref": "#/components/responses/TooManyRequests"
                    },
                    "503": {
                        "description": "Token no disponible; error genérico sin secretos. También `rate_limit_unavailable` si el contador de límites no está disponible.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "oneOf": [
                                        {
                                            "$ref": "#/components/schemas/ErrorEnvelope"
                                        },
                                        {
                                            "$ref": "#/components/schemas/AccessError"
                                        }
                                    ]
                                }
                            }
                        }
                    }
                },
                "x-consumo-unidades": "1 por solicitud",
                "x-estado-verificacion": "pendiente_validacion_externa"
            }
        },
        "/api/v1/ssco/{ruc}": {
            "get": {
                "tags": [
                    "Padrón y datos públicos"
                ],
                "operationId": "ssco",
                "summary": "Sujeto sin capacidad operativa (SSCO)",
                "description": "Indica si el RUC figura en el padrón oficial de Sujetos Sin Capacidad Operativa importado en el servicio. 404 significa que no figura en la copia importada.\n\n**Consumo:** 1 por solicitud. Una consulta validada que se envía al proveedor consume cuota aunque el proveedor responda con error (ADR-005). Los rechazos de validación (422), autenticación, límite o duplicado no consumen.",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/IdempotencyKey"
                    },
                    {
                        "name": "ruc",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "pattern": "^\\d{11}$"
                        },
                        "example": "20123456789"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Consulta resuelta.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/SuccessEnvelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "additionalProperties": true,
                                                    "description": "Registro del dataset oficial importado; las columnas dependen de la fuente."
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "success": true,
                                    "code": "found",
                                    "retryable": false,
                                    "data": {
                                        "RUC": "20123456789",
                                        "RAZON SOCIAL": "EMPRESA DEMOSTRACION S.A.C."
                                    },
                                    "time": 0.42,
                                    "source": "ssco"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "description": "Registro no encontrado en la fuente local (`not_found`).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorEnvelope"
                                }
                            }
                        }
                    },
                    "409": {
                        "$ref": "#/components/responses/DuplicateRequest"
                    },
                    "422": {
                        "description": "RUC inválido.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorEnvelope"
                                }
                            }
                        }
                    },
                    "429": {
                        "$ref": "#/components/responses/TooManyRequests"
                    },
                    "502": {
                        "description": "Error del proveedor (`proveedor_error`).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorEnvelope"
                                }
                            }
                        }
                    },
                    "503": {
                        "description": "El dataset no está importado (`dataset_no_disponible`) o el servicio no responde (`servicio_no_disponible`). También `rate_limit_unavailable` si el contador de límites no está disponible.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "oneOf": [
                                        {
                                            "$ref": "#/components/schemas/ErrorEnvelope"
                                        },
                                        {
                                            "$ref": "#/components/schemas/AccessError"
                                        }
                                    ]
                                }
                            }
                        }
                    }
                },
                "x-consumo-unidades": "1 por solicitud",
                "x-estado-verificacion": "simulada"
            }
        },
        "/api/v1/sunafil/casilla": {
            "post": {
                "tags": [
                    "Casilla SUNAFIL"
                ],
                "operationId": "sunafilCasilla",
                "summary": "Consulta de la casilla electrónica SUNAFIL",
                "description": "Lee las categorías de la casilla electrónica SUNAFIL del RUC (notificaciones, acciones previas, orientación) con las credenciales SOL.\n\n**Consumo:** 1 por solicitud. Una consulta validada que se envía al proveedor consume cuota aunque el proveedor responda con error (ADR-005). Los rechazos de validación (422), autenticación, límite o duplicado no consumen.",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/IdempotencyKey"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "ruc",
                                    "usuario_sol",
                                    "clave_sol"
                                ],
                                "properties": {
                                    "ruc": {
                                        "type": "string",
                                        "pattern": "^\\d{11}$",
                                        "description": "RUC de 11 dígitos.",
                                        "example": "20123456789"
                                    },
                                    "usuario_sol": {
                                        "type": "string",
                                        "description": "Usuario SOL del RUC consultado. Se reenvía al proveedor y nunca se registra.",
                                        "example": "USUARIO_SOL"
                                    },
                                    "clave_sol": {
                                        "type": "string",
                                        "format": "password",
                                        "description": "Clave SOL. Se reenvía al proveedor y nunca se registra.",
                                        "example": "CLAVE_SOL"
                                    }
                                }
                            },
                            "example": {
                                "ruc": "20123456789",
                                "usuario_sol": "USUARIO_SOL",
                                "clave_sol": "CLAVE_SOL"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Consulta resuelta.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/SuccessEnvelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "additionalProperties": true
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "success": true,
                                    "code": "found",
                                    "retryable": false,
                                    "data": {
                                        "total": 0,
                                        "categorias": [
                                            {
                                                "nombre": "Orientación",
                                                "total": 0,
                                                "registros": []
                                            }
                                        ]
                                    },
                                    "time": 0.42
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "409": {
                        "$ref": "#/components/responses/DuplicateRequest"
                    },
                    "422": {
                        "description": "Campos inválidos.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorEnvelope"
                                }
                            }
                        }
                    },
                    "429": {
                        "$ref": "#/components/responses/TooManyRequests"
                    },
                    "500": {
                        "description": "El proveedor informó un error (`sunafil_error` u otro código, reintentable).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorEnvelope"
                                }
                            }
                        }
                    },
                    "502": {
                        "description": "El servicio de consultas no pudo completar la solicitud (`servicio_error`, `retryable: true`).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorEnvelope"
                                }
                            }
                        }
                    },
                    "503": {
                        "description": "El servicio de consultas no está disponible (`servicio_no_disponible`, `retryable: true`). Reintente en unos segundos. También `rate_limit_unavailable` si el contador de límites no está disponible.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "oneOf": [
                                        {
                                            "$ref": "#/components/schemas/ErrorEnvelope"
                                        },
                                        {
                                            "$ref": "#/components/schemas/AccessError"
                                        }
                                    ]
                                }
                            }
                        }
                    }
                },
                "x-consumo-unidades": "1 por solicitud",
                "x-estado-verificacion": "pendiente_validacion_externa"
            }
        },
        "/api/v1/sunafil/documento": {
            "post": {
                "tags": [
                    "Casilla SUNAFIL"
                ],
                "operationId": "sunafilDocumento",
                "summary": "Descarga de documento SUNAFIL (en memoria)",
                "description": "Devuelve en base64 los PDF de una fila de Acciones Previas (constancia de depósito y acuse). Cada uno trae su nombre y su huella SHA-256; el servicio no los almacena.\n\n**Consumo:** 1 por solicitud. Una consulta validada que se envía al proveedor consume cuota aunque el proveedor responda con error (ADR-005). Los rechazos de validación (422), autenticación, límite o duplicado no consumen.",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/IdempotencyKey"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "ruc",
                                    "usuario_sol",
                                    "clave_sol",
                                    "indice"
                                ],
                                "properties": {
                                    "ruc": {
                                        "type": "string",
                                        "pattern": "^\\d{11}$",
                                        "description": "RUC de 11 dígitos.",
                                        "example": "20123456789"
                                    },
                                    "usuario_sol": {
                                        "type": "string",
                                        "description": "Usuario SOL del RUC consultado. Se reenvía al proveedor y nunca se registra.",
                                        "example": "USUARIO_SOL"
                                    },
                                    "clave_sol": {
                                        "type": "string",
                                        "format": "password",
                                        "description": "Clave SOL. Se reenvía al proveedor y nunca se registra.",
                                        "example": "CLAVE_SOL"
                                    },
                                    "indice": {
                                        "type": "integer",
                                        "minimum": 0,
                                        "maximum": 999,
                                        "description": "Posición de la fila en la tabla de Acciones Previas (base 0).",
                                        "example": 0
                                    }
                                }
                            },
                            "example": {
                                "ruc": "20123456789",
                                "usuario_sol": "USUARIO_SOL",
                                "clave_sol": "CLAVE_SOL",
                                "indice": 0
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Consulta resuelta.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/SuccessEnvelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "additionalProperties": true
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "success": true,
                                    "code": "found",
                                    "retryable": false,
                                    "data": {
                                        "documentos": [
                                            {
                                                "nombre": "CONSTANCIA_DEPOSITO_EJEMPLO.pdf",
                                                "bytes": 25580,
                                                "sha256": "0000000000000000000000000000000000000000000000000000000000000000",
                                                "pdf_base64": "JVBERi0x"
                                            }
                                        ]
                                    },
                                    "time": 0.42
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "description": "No existe documento en esa posición (`documento_no_disponible`).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorEnvelope"
                                }
                            }
                        }
                    },
                    "409": {
                        "$ref": "#/components/responses/DuplicateRequest"
                    },
                    "422": {
                        "description": "Campos inválidos.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorEnvelope"
                                }
                            }
                        }
                    },
                    "429": {
                        "$ref": "#/components/responses/TooManyRequests"
                    },
                    "500": {
                        "description": "El proveedor informó un error (`sunafil_error` u otro código, reintentable).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorEnvelope"
                                }
                            }
                        }
                    },
                    "502": {
                        "description": "El servicio de consultas no pudo completar la solicitud (`servicio_error`, `retryable: true`).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorEnvelope"
                                }
                            }
                        }
                    },
                    "503": {
                        "description": "El servicio de consultas no está disponible (`servicio_no_disponible`, `retryable: true`). Reintente en unos segundos. También `rate_limit_unavailable` si el contador de límites no está disponible.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "oneOf": [
                                        {
                                            "$ref": "#/components/schemas/ErrorEnvelope"
                                        },
                                        {
                                            "$ref": "#/components/schemas/AccessError"
                                        }
                                    ]
                                }
                            }
                        }
                    }
                },
                "x-consumo-unidades": "1 por solicitud",
                "x-estado-verificacion": "pendiente_validacion_externa"
            }
        },
        "/api/v1/tipo-cambio": {
            "get": {
                "tags": [
                    "Padrón y datos públicos"
                ],
                "operationId": "tipoCambio",
                "summary": "Tipo de cambio",
                "description": "Devuelve el tipo de cambio de una fecha y moneda (SBS; historial en caché del proveedor). Si ese día no hubo publicación (fin de semana o feriado) responde 404. Para el último publicado usar `GET /api/v1/tipo-cambio/actual`.\n\n**Consumo:** 1 por solicitud. Una consulta validada que se envía al proveedor consume cuota aunque el proveedor responda con error (ADR-005). Los rechazos de validación (422), autenticación, límite o duplicado no consumen.",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/IdempotencyKey"
                    },
                    {
                        "name": "fecha",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "format": "date"
                        },
                        "description": "Fecha en formato AAAA-MM-DD.",
                        "example": "2026-10-09"
                    },
                    {
                        "name": "moneda",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "pattern": "^[A-Za-z]{3}$",
                            "default": "USD"
                        },
                        "description": "Código ISO de la moneda."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Consulta resuelta.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/SuccessEnvelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "additionalProperties": true,
                                                    "description": "Registro del dataset oficial importado; las columnas dependen de la fuente."
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "success": true,
                                    "code": "found",
                                    "retryable": false,
                                    "data": {
                                        "fecha": "2026-10-09",
                                        "moneda": "USD",
                                        "compra": "VALOR",
                                        "venta": "VALOR"
                                    },
                                    "time": 0.42,
                                    "source": "tipo_cambio"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "description": "Registro no encontrado en la fuente local (`not_found`).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorEnvelope"
                                }
                            }
                        }
                    },
                    "409": {
                        "$ref": "#/components/responses/DuplicateRequest"
                    },
                    "422": {
                        "description": "Fecha o moneda inválida.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorEnvelope"
                                }
                            }
                        }
                    },
                    "429": {
                        "$ref": "#/components/responses/TooManyRequests"
                    },
                    "502": {
                        "description": "Error del proveedor (`proveedor_error`).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorEnvelope"
                                }
                            }
                        }
                    },
                    "503": {
                        "description": "El dataset no está importado (`dataset_no_disponible`) o el servicio no responde (`servicio_no_disponible`). También `rate_limit_unavailable` si el contador de límites no está disponible.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "oneOf": [
                                        {
                                            "$ref": "#/components/schemas/ErrorEnvelope"
                                        },
                                        {
                                            "$ref": "#/components/schemas/AccessError"
                                        }
                                    ]
                                }
                            }
                        }
                    }
                },
                "x-consumo-unidades": "1 por solicitud",
                "x-estado-verificacion": "pendiente_validacion_externa"
            }
        },
        "/api/v1/tipo-cambio/actual": {
            "get": {
                "tags": [
                    "Padrón y datos públicos"
                ],
                "operationId": "tipoCambioActual",
                "summary": "Tipo de cambio actual",
                "description": "Devuelve el último tipo de cambio publicado hasta hoy: el de hoy si ya está publicado; si no, el del día anterior más cercano. `data.fecha` indica a qué día corresponde.\n\n**Consumo:** 1 por solicitud. Una consulta validada que se envía al proveedor consume cuota aunque el proveedor responda con error (ADR-005). Los rechazos de validación (422), autenticación, límite o duplicado no consumen.",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/IdempotencyKey"
                    },
                    {
                        "name": "moneda",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "pattern": "^[A-Za-z]{3}$",
                            "default": "USD"
                        },
                        "description": "Código ISO de la moneda."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Consulta resuelta.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/SuccessEnvelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "additionalProperties": true,
                                                    "description": "Registro del dataset oficial importado; las columnas dependen de la fuente."
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "success": true,
                                    "code": "found",
                                    "retryable": false,
                                    "data": {
                                        "fecha": "2026-10-09",
                                        "moneda": "USD",
                                        "compra": "VALOR",
                                        "venta": "VALOR"
                                    },
                                    "time": 0.42,
                                    "source": "tipo_cambio"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "description": "Registro no encontrado en la fuente local (`not_found`).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorEnvelope"
                                }
                            }
                        }
                    },
                    "409": {
                        "$ref": "#/components/responses/DuplicateRequest"
                    },
                    "422": {
                        "description": "Moneda inválida.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorEnvelope"
                                }
                            }
                        }
                    },
                    "429": {
                        "$ref": "#/components/responses/TooManyRequests"
                    },
                    "502": {
                        "description": "Error del proveedor (`proveedor_error`).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorEnvelope"
                                }
                            }
                        }
                    },
                    "503": {
                        "description": "El dataset no está importado (`dataset_no_disponible`) o el servicio no responde (`servicio_no_disponible`). También `rate_limit_unavailable` si el contador de límites no está disponible.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "oneOf": [
                                        {
                                            "$ref": "#/components/schemas/ErrorEnvelope"
                                        },
                                        {
                                            "$ref": "#/components/schemas/AccessError"
                                        }
                                    ]
                                }
                            }
                        }
                    }
                },
                "x-consumo-unidades": "1 por solicitud",
                "x-estado-verificacion": "pendiente_validacion_externa"
            }
        },
        "/api/v1/ubigeos": {
            "get": {
                "tags": [
                    "Padrón y datos públicos"
                ],
                "operationId": "ubigeos",
                "summary": "Ubigeos (INEI)",
                "description": "Busca códigos de ubigeo en el dataset oficial importado en el servicio.\n\n**Consumo:** 1 por solicitud. Una consulta validada que se envía al proveedor consume cuota aunque el proveedor responda con error (ADR-005). Los rechazos de validación (422), autenticación, límite o duplicado no consumen.",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/IdempotencyKey"
                    },
                    {
                        "name": "q",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "maxLength": 120
                        },
                        "description": "Texto a buscar en el registro. Vacío devuelve los primeros registros.",
                        "example": "LIMA"
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 100,
                            "default": 50
                        },
                        "description": "Máximo de registros."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Consulta resuelta.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/SuccessEnvelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "array",
                                                    "items": {
                                                        "type": "object",
                                                        "additionalProperties": true,
                                                        "description": "Registro del dataset oficial importado; las columnas dependen de la fuente."
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "success": true,
                                    "code": "found",
                                    "retryable": false,
                                    "data": [
                                        {
                                            "ubigeo": "150101",
                                            "departamento": "LIMA",
                                            "provincia": "LIMA",
                                            "distrito": "LIMA"
                                        }
                                    ],
                                    "time": 0.42,
                                    "source": "ubigeos"
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "409": {
                        "$ref": "#/components/responses/DuplicateRequest"
                    },
                    "422": {
                        "description": "Parámetros inválidos.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorEnvelope"
                                }
                            }
                        }
                    },
                    "429": {
                        "$ref": "#/components/responses/TooManyRequests"
                    },
                    "502": {
                        "description": "Error del proveedor (`proveedor_error`).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorEnvelope"
                                }
                            }
                        }
                    },
                    "503": {
                        "description": "El dataset no está importado (`dataset_no_disponible`) o el servicio no responde (`servicio_no_disponible`). También `rate_limit_unavailable` si el contador de límites no está disponible.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "oneOf": [
                                        {
                                            "$ref": "#/components/schemas/ErrorEnvelope"
                                        },
                                        {
                                            "$ref": "#/components/schemas/AccessError"
                                        }
                                    ]
                                }
                            }
                        }
                    }
                },
                "x-consumo-unidades": "1 por solicitud",
                "x-estado-verificacion": "simulada"
            }
        },
        "/api/v1/validacion-multiple-cpe": {
            "post": {
                "tags": [
                    "Comprobantes"
                ],
                "operationId": "validacion",
                "summary": "Validación múltiple de CPE",
                "description": "Consulta el estado de varios comprobantes en SUNAT con la Clave SOL del RUC (estado del comprobante, del contribuyente y condición de domicilio).\n\n**Consumo:** 1 por comprobante del lote (máximo 100). Una consulta validada que se envía al proveedor consume cuota aunque el proveedor responda con error (ADR-005). Los rechazos de validación (422), autenticación, límite o duplicado no consumen.",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/IdempotencyKey"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "ruc",
                                    "usuario_sol",
                                    "clave_sol",
                                    "comprobantes"
                                ],
                                "properties": {
                                    "ruc": {
                                        "type": "string",
                                        "pattern": "^\\d{11}$",
                                        "description": "RUC de 11 dígitos.",
                                        "example": "20123456789"
                                    },
                                    "usuario_sol": {
                                        "type": "string",
                                        "description": "Usuario SOL del RUC consultado. Se reenvía al proveedor y nunca se registra.",
                                        "example": "USUARIO_SOL"
                                    },
                                    "clave_sol": {
                                        "type": "string",
                                        "format": "password",
                                        "description": "Clave SOL. Se reenvía al proveedor y nunca se registra.",
                                        "example": "CLAVE_SOL"
                                    },
                                    "comprobantes": {
                                        "type": "array",
                                        "minItems": 1,
                                        "maxItems": 100,
                                        "items": {
                                            "type": "object",
                                            "description": "Campos que se envían tal cual a SUNAT; la API no valida su contenido.",
                                            "properties": {
                                                "tipo": {
                                                    "type": "string",
                                                    "example": "01"
                                                },
                                                "serie": {
                                                    "type": "string",
                                                    "example": "F001"
                                                },
                                                "numero": {
                                                    "type": "string",
                                                    "example": "123"
                                                },
                                                "fecha": {
                                                    "type": "string",
                                                    "example": "FECHA_DE_EMISION"
                                                },
                                                "monto": {
                                                    "type": "string",
                                                    "example": "MONTO_DEL_COMPROBANTE"
                                                }
                                            },
                                            "additionalProperties": true
                                        }
                                    }
                                }
                            },
                            "example": {
                                "ruc": "20123456789",
                                "usuario_sol": "USUARIO_SOL",
                                "clave_sol": "CLAVE_SOL",
                                "comprobantes": [
                                    {
                                        "tipo": "01",
                                        "serie": "F001",
                                        "numero": "123",
                                        "fecha": "FECHA_DE_EMISION",
                                        "monto": "MONTO_DEL_COMPROBANTE"
                                    }
                                ]
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Consulta resuelta.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/SuccessEnvelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "additionalProperties": true
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "success": true,
                                    "code": "found",
                                    "retryable": false,
                                    "data": {
                                        "total": 1,
                                        "exitosos": 1,
                                        "fallidos": 0,
                                        "comprobantes": [
                                            {
                                                "tipo": "01",
                                                "serie": "F001",
                                                "numero": "123",
                                                "fecha": "FECHA_DE_EMISION",
                                                "monto": "MONTO_DEL_COMPROBANTE",
                                                "exito": true,
                                                "estado_comprobante": "ESTADO_INFORMADO_POR_SUNAT",
                                                "estado_contribuyente": "ACTIVO",
                                                "condicion_domicilio": "HABIDO",
                                                "observaciones": "",
                                                "error": null,
                                                "intentos": 1
                                            }
                                        ],
                                        "tiempo_ms": 1500
                                    },
                                    "time": 0.42
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "409": {
                        "$ref": "#/components/responses/DuplicateRequest"
                    },
                    "422": {
                        "description": "Campos superiores inválidos.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorEnvelope"
                                }
                            }
                        }
                    },
                    "429": {
                        "$ref": "#/components/responses/TooManyRequests"
                    },
                    "500": {
                        "description": "El proveedor informó un error global (`validacion_error`, reintentable).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorEnvelope"
                                }
                            }
                        }
                    },
                    "502": {
                        "description": "El servicio de consultas no pudo completar la solicitud (`servicio_error`, `retryable: true`).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorEnvelope"
                                }
                            }
                        }
                    },
                    "503": {
                        "description": "El servicio de consultas no está disponible (`servicio_no_disponible`, `retryable: true`). Reintente en unos segundos. También `rate_limit_unavailable` si el contador de límites no está disponible.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "oneOf": [
                                        {
                                            "$ref": "#/components/schemas/ErrorEnvelope"
                                        },
                                        {
                                            "$ref": "#/components/schemas/AccessError"
                                        }
                                    ]
                                }
                            }
                        }
                    }
                },
                "x-consumo-unidades": "1 por comprobante del lote (máximo 100)",
                "x-estado-verificacion": "pendiente_validacion_externa"
            }
        },
        "/api/validacion-multiple-cpe": {
            "post": {
                "tags": [
                    "Comprobantes"
                ],
                "operationId": "validacionLegacy",
                "summary": "Validación múltiple de CPE (alias sin versión)",
                "description": "Consulta el estado de varios comprobantes en SUNAT con la Clave SOL del RUC (estado del comprobante, del contribuyente y condición de domicilio).\n\n**Consumo:** 1 por comprobante del lote (máximo 100). Una consulta validada que se envía al proveedor consume cuota aunque el proveedor responda con error (ADR-005). Los rechazos de validación (422), autenticación, límite o duplicado no consumen.\n\n**Obsoleto:** alias temporal de `/api/v1/validacion-multiple-cpe` mantenido por compatibilidad; usar la ruta versionada.",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/IdempotencyKey"
                    }
                ],
                "deprecated": true,
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "ruc",
                                    "usuario_sol",
                                    "clave_sol",
                                    "comprobantes"
                                ],
                                "properties": {
                                    "ruc": {
                                        "type": "string",
                                        "pattern": "^\\d{11}$",
                                        "description": "RUC de 11 dígitos.",
                                        "example": "20123456789"
                                    },
                                    "usuario_sol": {
                                        "type": "string",
                                        "description": "Usuario SOL del RUC consultado. Se reenvía al proveedor y nunca se registra.",
                                        "example": "USUARIO_SOL"
                                    },
                                    "clave_sol": {
                                        "type": "string",
                                        "format": "password",
                                        "description": "Clave SOL. Se reenvía al proveedor y nunca se registra.",
                                        "example": "CLAVE_SOL"
                                    },
                                    "comprobantes": {
                                        "type": "array",
                                        "minItems": 1,
                                        "maxItems": 100,
                                        "items": {
                                            "type": "object",
                                            "description": "Campos que se envían tal cual a SUNAT; la API no valida su contenido.",
                                            "properties": {
                                                "tipo": {
                                                    "type": "string",
                                                    "example": "01"
                                                },
                                                "serie": {
                                                    "type": "string",
                                                    "example": "F001"
                                                },
                                                "numero": {
                                                    "type": "string",
                                                    "example": "123"
                                                },
                                                "fecha": {
                                                    "type": "string",
                                                    "example": "FECHA_DE_EMISION"
                                                },
                                                "monto": {
                                                    "type": "string",
                                                    "example": "MONTO_DEL_COMPROBANTE"
                                                }
                                            },
                                            "additionalProperties": true
                                        }
                                    }
                                }
                            },
                            "example": {
                                "ruc": "20123456789",
                                "usuario_sol": "USUARIO_SOL",
                                "clave_sol": "CLAVE_SOL",
                                "comprobantes": [
                                    {
                                        "tipo": "01",
                                        "serie": "F001",
                                        "numero": "123",
                                        "fecha": "FECHA_DE_EMISION",
                                        "monto": "MONTO_DEL_COMPROBANTE"
                                    }
                                ]
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Consulta resuelta.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/SuccessEnvelope"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "data": {
                                                    "type": "object",
                                                    "additionalProperties": true
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "success": true,
                                    "code": "found",
                                    "retryable": false,
                                    "data": {
                                        "total": 1,
                                        "exitosos": 1,
                                        "fallidos": 0,
                                        "comprobantes": [
                                            {
                                                "tipo": "01",
                                                "serie": "F001",
                                                "numero": "123",
                                                "fecha": "FECHA_DE_EMISION",
                                                "monto": "MONTO_DEL_COMPROBANTE",
                                                "exito": true,
                                                "estado_comprobante": "ESTADO_INFORMADO_POR_SUNAT",
                                                "estado_contribuyente": "ACTIVO",
                                                "condicion_domicilio": "HABIDO",
                                                "observaciones": "",
                                                "error": null,
                                                "intentos": 1
                                            }
                                        ],
                                        "tiempo_ms": 1500
                                    },
                                    "time": 0.42
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "409": {
                        "$ref": "#/components/responses/DuplicateRequest"
                    },
                    "422": {
                        "description": "Campos superiores inválidos.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorEnvelope"
                                }
                            }
                        }
                    },
                    "429": {
                        "$ref": "#/components/responses/TooManyRequests"
                    },
                    "500": {
                        "description": "El proveedor informó un error global (`validacion_error`, reintentable).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorEnvelope"
                                }
                            }
                        }
                    },
                    "502": {
                        "description": "El servicio de consultas no pudo completar la solicitud (`servicio_error`, `retryable: true`).",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorEnvelope"
                                }
                            }
                        }
                    },
                    "503": {
                        "description": "El servicio de consultas no está disponible (`servicio_no_disponible`, `retryable: true`). Reintente en unos segundos. También `rate_limit_unavailable` si el contador de límites no está disponible.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "oneOf": [
                                        {
                                            "$ref": "#/components/schemas/ErrorEnvelope"
                                        },
                                        {
                                            "$ref": "#/components/schemas/AccessError"
                                        }
                                    ]
                                }
                            }
                        }
                    }
                },
                "x-consumo-unidades": "1 por comprobante del lote (máximo 100)",
                "x-estado-verificacion": "pendiente_validacion_externa"
            }
        }
    },
    "components": {
        "securitySchemes": {
            "bearerAuth": {
                "type": "http",
                "scheme": "bearer",
                "description": "Token del cliente generado en el panel (Tokens API). Se envía como `Authorization: Bearer <token>`. Nunca se registra en logs."
            }
        },
        "parameters": {
            "IdempotencyKey": {
                "name": "Idempotency-Key",
                "in": "header",
                "required": false,
                "schema": {
                    "type": "string",
                    "maxLength": 255
                },
                "description": "Clave opcional para evitar cobros duplicados por reintentos: si se repite para el mismo cliente, responde 409 sin volver a consultar ni consumir."
            }
        },
        "schemas": {
            "SuccessEnvelope": {
                "type": "object",
                "required": [
                    "success",
                    "code",
                    "retryable",
                    "data",
                    "time"
                ],
                "properties": {
                    "success": {
                        "type": "boolean",
                        "const": true
                    },
                    "code": {
                        "type": "string",
                        "examples": [
                            "found"
                        ]
                    },
                    "retryable": {
                        "type": "boolean",
                        "const": false
                    },
                    "data": {
                        "description": "Resultado de la operación."
                    },
                    "source": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "description": "Fuente de datos: datos públicos y, en RUC/DNI, `padron_reducido` o `sunat_en_linea`."
                    },
                    "time": {
                        "type": "number",
                        "description": "Segundos empleados por el proveedor."
                    }
                }
            },
            "ErrorEnvelope": {
                "type": "object",
                "required": [
                    "success",
                    "code",
                    "retryable",
                    "message"
                ],
                "properties": {
                    "success": {
                        "type": "boolean",
                        "const": false
                    },
                    "code": {
                        "type": "string",
                        "description": "Código estable del error (p. ej. not_found, dataset_no_disponible, proveedor_error, invalid_ruc)."
                    },
                    "retryable": {
                        "type": "boolean",
                        "description": "true si reintentar más tarde puede tener éxito."
                    },
                    "message": {
                        "type": "string"
                    },
                    "time": {
                        "type": "number"
                    }
                },
                "example": {
                    "success": false,
                    "code": "not_found",
                    "retryable": false,
                    "message": "El RUC no existe en SUNAT",
                    "time": 0.31
                }
            },
            "AccessError": {
                "type": "object",
                "required": [
                    "success",
                    "error"
                ],
                "properties": {
                    "success": {
                        "type": "boolean",
                        "const": false
                    },
                    "error": {
                        "type": "object",
                        "required": [
                            "tipo",
                            "mensaje"
                        ],
                        "properties": {
                            "tipo": {
                                "type": "string"
                            },
                            "mensaje": {
                                "type": "string"
                            }
                        }
                    },
                    "consumo": {
                        "type": [
                            "integer",
                            "null"
                        ],
                        "description": "Consumo del ciclo (solo límite de plan)."
                    },
                    "limite": {
                        "type": [
                            "integer",
                            "null"
                        ],
                        "description": "Límite del ciclo (solo límite de plan)."
                    }
                }
            },
            "ValidationError": {
                "type": "object",
                "required": [
                    "message",
                    "errors"
                ],
                "properties": {
                    "message": {
                        "type": "string"
                    },
                    "errors": {
                        "type": "object",
                        "additionalProperties": {
                            "type": "array",
                            "items": {
                                "type": "string"
                            }
                        }
                    }
                },
                "example": {
                    "message": "The ruc field is required.",
                    "errors": {
                        "ruc": [
                            "The ruc field is required."
                        ]
                    }
                }
            }
        },
        "responses": {
            "Unauthorized": {
                "description": "Token ausente (`no_autenticado`), inválido o vencido (`token_invalido`).",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/AccessError"
                        },
                        "example": {
                            "success": false,
                            "error": {
                                "tipo": "no_autenticado",
                                "mensaje": "Token requerido"
                            }
                        }
                    }
                }
            },
            "Forbidden": {
                "description": "Cuenta suspendida (`cuenta_suspendida`), suscripción no activa o vencida (`suscripcion_*`) o IP no permitida (`ip_no_permitida`). No consume cuota.",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/AccessError"
                        },
                        "example": {
                            "success": false,
                            "error": {
                                "tipo": "ip_no_permitida",
                                "mensaje": "La IP de origen no está permitida"
                            }
                        }
                    }
                }
            },
            "DuplicateRequest": {
                "description": "`Idempotency-Key` ya utilizada por el cliente (`solicitud_duplicada`). No consulta ni consume.",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/AccessError"
                        },
                        "example": {
                            "success": false,
                            "error": {
                                "tipo": "solicitud_duplicada",
                                "mensaje": "La clave de idempotencia ya fue utilizada"
                            }
                        }
                    }
                }
            },
            "TooManyRequests": {
                "description": "Límite de consultas del plan agotado (`limite_alcanzado`, incluye `consumo` y `limite`) o límite operativo por minuto superado (`rate_limit_exceeded`, con `Retry-After`).",
                "headers": {
                    "Retry-After": {
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Segundos a esperar."
                    },
                    "X-RateLimit-Limit": {
                        "schema": {
                            "type": "integer"
                        }
                    },
                    "X-RateLimit-Remaining": {
                        "schema": {
                            "type": "integer"
                        }
                    }
                },
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/AccessError"
                        },
                        "example": {
                            "success": false,
                            "error": {
                                "tipo": "limite_alcanzado",
                                "mensaje": "Has alcanzado el límite de consultas de tu plan"
                            },
                            "consumo": 100,
                            "limite": 100
                        }
                    }
                }
            },
            "RateLimitUnavailable": {
                "description": "El contador de límites no está disponible (`rate_limit_unavailable`); responde con `Retry-After: 1` y no consume cuota.",
                "headers": {
                    "Retry-After": {
                        "schema": {
                            "type": "integer"
                        },
                        "description": "Segundos a esperar."
                    },
                    "X-RateLimit-Limit": {
                        "schema": {
                            "type": "integer"
                        }
                    },
                    "X-RateLimit-Remaining": {
                        "schema": {
                            "type": "integer"
                        }
                    }
                },
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/AccessError"
                        },
                        "example": {
                            "success": false,
                            "error": {
                                "tipo": "rate_limit_unavailable",
                                "mensaje": "El control temporal de solicitudes no está disponible"
                            }
                        }
                    }
                }
            }
        }
    }
}
