{
  "openapi": "3.1.0",
  "info": {
    "title": "OpenNexum API",
    "version": "1.0.0",
    "description": "API de OpenNexum para programadores y sus agentes de IA: comprobantes SUNAT (Nexum Comprobantes), datos públicos oficiales y mensajería por WhatsApp, Instagram y Messenger (Nexum Conecta), con una sola clave y saldo prepagado en soles.\n\n## Autenticación\nEnvía tu clave en `Authorization: Bearer onx_live_…` (producción) u `onx_test_…` (sandbox, con SUNAT beta). Cada clave tiene permisos, un tope de gasto y, si quieres, un alcance por RUC. Una clave nunca ve datos de otra cuenta.\n\n## Formatos\n- Montos como texto con dos decimales: `\"1250.50\"` es S/ 1,250.50. Moneda en código ISO (`PEN`, `USD`).\n- Fechas `AAAA-MM-DD` (día en Lima) y fechas con hora en ISO 8601 con la zona de Lima: `2026-11-15T16:30:00-05:00`.\n- RUC de 11 dígitos; validamos el dígito verificador.\n- Los cuerpos rechazan campos desconocidos: un error de tipeo no pasa en silencio.\n\n## Idempotencia\nToda operación que cobra exige la cabecera `Idempotency-Key` (un UUID por operación). Si repites la petición con la misma clave y el mismo cuerpo, recibes la misma respuesta y no se cobra dos veces.\n\n## Saldo y 402\nLo que cobra reserva el precio al empezar y lo cobra solo si el servicio confirma (por ejemplo, SUNAT acepta). Sin saldo o con el tope alcanzado responde **402** con `recarga_url`: pásasela a una persona de tu cuenta.\n\n## Respuestas 202\n- `requiere_confirmacion`: la operación espera que una persona la apruebe en el panel (`confirmacion_url`). Consulta `GET /v1/confirmaciones/{id}`. El «sí» nunca viaja como argumento de la API.\n- `en_cola`: la recibimos y se completa sola (por ejemplo, si SUNAT no responde). No la repitas; consulta `consulta_url`.\n\n## Errores\nTodos los errores tienen la forma `{ \"error\": { \"codigo\", \"mensaje\", \"detalle\", \"request_id\", \"docs\" } }`. El `codigo` es estable; el `mensaje` explica en español cómo arreglarlo. Cada respuesta lleva `X-Request-Id`.\n\n## Listas\nPaginación por cursor: `?limite=20&cursor=…`; la respuesta trae `elementos` y `siguiente_cursor` (`null` al final)."
  },
  "servers": [
    {
      "url": "https://api.opennexum.com",
      "description": "Producción (claves onx_live_)"
    },
    {
      "url": "https://api-sandbox.opennexum.com",
      "description": "Sandbox con SUNAT beta (claves onx_test_)"
    }
  ],
  "security": [
    {
      "claveApi": []
    }
  ],
  "tags": [
    {
      "name": "Cuenta",
      "description": "Saldo, consumo y recargas en soles."
    },
    {
      "name": "Claves",
      "description": "Claves de API por agente, con permisos, tope y alcance por RUC."
    },
    {
      "name": "Confirmaciones",
      "description": "Operaciones que esperan la aprobación de una persona."
    },
    {
      "name": "Datos",
      "description": "RUC, padrones y tipo de cambio desde fuentes oficiales."
    },
    {
      "name": "Emisores",
      "description": "RUC emisores, series y credenciales."
    },
    {
      "name": "Comprobantes",
      "description": "Facturas, boletas y notas: emitir, consultar, descargar y dar de baja."
    },
    {
      "name": "Resúmenes",
      "description": "Resúmenes diarios de boletas y comunicaciones de baja."
    },
    {
      "name": "Guías",
      "description": "Guías de remisión remitente."
    },
    {
      "name": "SIRE",
      "description": "Propuestas de ventas (RVIE) y compras (RCE)."
    },
    {
      "name": "Conexiones",
      "description": "Números de WhatsApp, cuentas de Instagram y páginas de Messenger conectadas."
    },
    {
      "name": "Mensajes",
      "description": "Bandeja, envío de mensajes y de comprobantes."
    },
    {
      "name": "Plantillas",
      "description": "Plantillas de mensaje para escribir fuera de la ventana de atención."
    },
    {
      "name": "Webhooks",
      "description": "Eventos normalizados y firmados hacia tu sistema."
    }
  ],
  "paths": {
    "/v1/yo": {
      "get": {
        "operationId": "yo_ver",
        "summary": "Dice quién eres",
        "description": "Devuelve la cuenta (id público y nombre), el entorno, el tipo de credencial (clave o token OAuth), sus permisos, los RUC a los que llega y su tope. Basta una credencial válida y no cobra. Nunca devuelve la clave ni el token.\n\n**Permiso:** `clave_valida`. **Cobro:** No cobra.",
        "tags": [
          "Cuenta"
        ],
        "security": [
          {
            "claveApi": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/RequestId"
          }
        ],
        "responses": {
          "200": {
            "description": "La cuenta y lo que puede hacer tu credencial.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Yo"
                }
              }
            }
          },
          "401": {
            "description": "`clave_invalida`: Falta la clave de API, está mal escrita, venció o fue revocada. Envíala como `Authorization: Bearer onx_live_…`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "clave_invalida": {
                    "$ref": "#/components/examples/clave_invalida"
                  }
                }
              }
            }
          },
          "403": {
            "description": "`permiso_faltante`: La clave no tiene el permiso que pide esta ruta o no tiene acceso a ese RUC.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "permiso_faltante": {
                    "$ref": "#/components/examples/permiso_faltante"
                  }
                }
              }
            }
          },
          "429": {
            "description": "`limite_uso`: Hiciste demasiadas peticiones seguidas. Espera los segundos que indica `Retry-After` y vuelve a intentar.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "limite_uso": {
                    "$ref": "#/components/examples/limite_uso"
                  }
                }
              }
            }
          },
          "500": {
            "description": "`error_interno`: Algo falló de nuestro lado. Repite la petición con la misma `Idempotency-Key`: no se duplica nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "error_interno": {
                    "$ref": "#/components/examples/error_interno"
                  }
                }
              }
            }
          },
          "501": {
            "description": "`operacion_no_disponible`: Esta operación existe en el contrato, pero todavía no está habilitada. Revisa en la documentación qué rutas ya puedes usar; no se cobró nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "operacion_no_disponible": {
                    "$ref": "#/components/examples/operacion_no_disponible"
                  }
                }
              }
            }
          },
          "503": {
            "description": "`no_disponible`: El dato todavía se está cargando o actualizando de nuestro lado. Vuelve a intentar después de los segundos que indica `Retry-After`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "no_disponible": {
                    "$ref": "#/components/examples/no_disponible"
                  }
                }
              }
            }
          }
        },
        "x-nexum": {
          "permiso": "clave_valida",
          "cobro": "no",
          "puede_pedir_confirmacion": false,
          "confirmacion_obligatoria": false,
          "acepta_credenciales": false,
          "idempotencia": "no_aplica",
          "herramienta_mcp": "yo_ver"
        }
      }
    },
    "/v1/cuenta/saldo": {
      "get": {
        "operationId": "cuenta_saldo",
        "summary": "Consulta tu saldo",
        "description": "Devuelve el saldo disponible y reservado en soles, el tope de la clave que pregunta y el enlace de recarga.\n\n**Permiso:** `cuenta:leer`. **Cobro:** No cobra.",
        "tags": [
          "Cuenta"
        ],
        "security": [
          {
            "claveApi": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/RequestId"
          }
        ],
        "responses": {
          "200": {
            "description": "Saldo de la cuenta.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Saldo"
                }
              }
            }
          },
          "401": {
            "description": "`clave_invalida`: Falta la clave de API, está mal escrita, venció o fue revocada. Envíala como `Authorization: Bearer onx_live_…`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "clave_invalida": {
                    "$ref": "#/components/examples/clave_invalida"
                  }
                }
              }
            }
          },
          "403": {
            "description": "`permiso_faltante`: La clave no tiene el permiso que pide esta ruta o no tiene acceso a ese RUC.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "permiso_faltante": {
                    "$ref": "#/components/examples/permiso_faltante"
                  }
                }
              }
            }
          },
          "429": {
            "description": "`limite_uso`: Hiciste demasiadas peticiones seguidas. Espera los segundos que indica `Retry-After` y vuelve a intentar.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "limite_uso": {
                    "$ref": "#/components/examples/limite_uso"
                  }
                }
              }
            }
          },
          "500": {
            "description": "`error_interno`: Algo falló de nuestro lado. Repite la petición con la misma `Idempotency-Key`: no se duplica nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "error_interno": {
                    "$ref": "#/components/examples/error_interno"
                  }
                }
              }
            }
          },
          "501": {
            "description": "`operacion_no_disponible`: Esta operación existe en el contrato, pero todavía no está habilitada. Revisa en la documentación qué rutas ya puedes usar; no se cobró nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "operacion_no_disponible": {
                    "$ref": "#/components/examples/operacion_no_disponible"
                  }
                }
              }
            }
          },
          "503": {
            "description": "`no_disponible`: El dato todavía se está cargando o actualizando de nuestro lado. Vuelve a intentar después de los segundos que indica `Retry-After`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "no_disponible": {
                    "$ref": "#/components/examples/no_disponible"
                  }
                }
              }
            }
          }
        },
        "x-nexum": {
          "permiso": "cuenta:leer",
          "cobro": "no",
          "puede_pedir_confirmacion": false,
          "confirmacion_obligatoria": false,
          "acepta_credenciales": false,
          "idempotencia": "no_aplica",
          "herramienta_mcp": "cuenta_saldo"
        }
      }
    },
    "/v1/cuenta/consumo": {
      "get": {
        "operationId": "cuenta_consumo",
        "summary": "Lista tu consumo",
        "description": "Movimientos de tu saldo del periodo (por omisión, el mes en curso): reservas, cobros y liberaciones con la operación y la clave que los hizo, y las recargas acreditadas. Trae además el gasto de cada clave o agente en todo el periodo.\n\n**Permiso:** `cuenta:leer`. **Cobro:** No cobra.",
        "tags": [
          "Cuenta"
        ],
        "security": [
          {
            "claveApi": []
          }
        ],
        "parameters": [
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "Cursor opaco que devolvió la página anterior en `siguiente_cursor`.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 512
            }
          },
          {
            "name": "limite",
            "in": "query",
            "required": false,
            "description": "Cuántos elementos traer (1 a 100; por defecto 20).",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100
            }
          },
          {
            "name": "desde",
            "in": "query",
            "required": false,
            "description": "Desde este día (incluido). Si no lo envías, desde el día 1 del mes de `hasta`.",
            "schema": {
              "type": "string",
              "format": "date",
              "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$",
              "examples": [
                "2026-11-15"
              ]
            }
          },
          {
            "name": "hasta",
            "in": "query",
            "required": false,
            "description": "Hasta este día (incluido). Si no lo envías, hoy en Lima.",
            "schema": {
              "type": "string",
              "format": "date",
              "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$",
              "examples": [
                "2026-11-15"
              ]
            }
          },
          {
            "name": "servicio",
            "in": "query",
            "required": false,
            "description": "Solo el consumo de ese servicio (deja fuera las recargas).",
            "schema": {
              "type": "string",
              "enum": [
                "datos",
                "comprobantes",
                "conecta"
              ]
            }
          },
          {
            "name": "clave_id",
            "in": "query",
            "required": false,
            "description": "Solo lo gastado con esta clave (deja fuera las recargas).",
            "schema": {
              "type": "string",
              "pattern": "^clv_[A-Za-z0-9]{8,64}$",
              "examples": [
                "clv_8f2c1a7d9e"
              ]
            }
          },
          {
            "$ref": "#/components/parameters/RequestId"
          }
        ],
        "responses": {
          "200": {
            "description": "Página de movimientos con el gasto por clave.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ListaConsumo"
                }
              }
            }
          },
          "400": {
            "description": "`validacion`: Algún dato no cumple el formato. En `detalle` va cada campo con su problema.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "validacion": {
                    "$ref": "#/components/examples/validacion"
                  }
                }
              }
            }
          },
          "401": {
            "description": "`clave_invalida`: Falta la clave de API, está mal escrita, venció o fue revocada. Envíala como `Authorization: Bearer onx_live_…`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "clave_invalida": {
                    "$ref": "#/components/examples/clave_invalida"
                  }
                }
              }
            }
          },
          "403": {
            "description": "`permiso_faltante`: La clave no tiene el permiso que pide esta ruta o no tiene acceso a ese RUC.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "permiso_faltante": {
                    "$ref": "#/components/examples/permiso_faltante"
                  }
                }
              }
            }
          },
          "429": {
            "description": "`limite_uso`: Hiciste demasiadas peticiones seguidas. Espera los segundos que indica `Retry-After` y vuelve a intentar.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "limite_uso": {
                    "$ref": "#/components/examples/limite_uso"
                  }
                }
              }
            }
          },
          "500": {
            "description": "`error_interno`: Algo falló de nuestro lado. Repite la petición con la misma `Idempotency-Key`: no se duplica nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "error_interno": {
                    "$ref": "#/components/examples/error_interno"
                  }
                }
              }
            }
          },
          "501": {
            "description": "`operacion_no_disponible`: Esta operación existe en el contrato, pero todavía no está habilitada. Revisa en la documentación qué rutas ya puedes usar; no se cobró nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "operacion_no_disponible": {
                    "$ref": "#/components/examples/operacion_no_disponible"
                  }
                }
              }
            }
          },
          "503": {
            "description": "`no_disponible`: El dato todavía se está cargando o actualizando de nuestro lado. Vuelve a intentar después de los segundos que indica `Retry-After`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "no_disponible": {
                    "$ref": "#/components/examples/no_disponible"
                  }
                }
              }
            }
          }
        },
        "x-nexum": {
          "permiso": "cuenta:leer",
          "cobro": "no",
          "puede_pedir_confirmacion": false,
          "confirmacion_obligatoria": false,
          "acepta_credenciales": false,
          "idempotencia": "no_aplica",
          "herramienta_mcp": "cuenta_consumo"
        }
      }
    },
    "/v1/cuenta/recargas": {
      "post": {
        "operationId": "recarga_crear",
        "summary": "Declara una recarga por Yape o Plin",
        "description": "Una persona paga por Yape o Plin y declara el pago: monto, método, número de operación, día del pago y la captura (voucher) en base64. La recarga queda `en_revision` hasta que la revisamos; se acredita una sola vez y luego te enviamos la factura. El mismo número de operación (o el mismo voucher) no se registra dos veces.\n\n**Permiso:** `cuenta:recargar`. **Cobro:** No cobra.\n\n**Idempotency-Key:** obligatoria.",
        "tags": [
          "Cuenta"
        ],
        "security": [
          {
            "claveApi": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "$ref": "#/components/parameters/RequestId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CrearRecarga"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Recarga registrada, en revisión.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Recarga"
                }
              }
            }
          },
          "400": {
            "description": "`validacion`: Algún dato no cumple el formato. En `detalle` va cada campo con su problema.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "validacion": {
                    "$ref": "#/components/examples/validacion"
                  }
                }
              }
            }
          },
          "401": {
            "description": "`clave_invalida`: Falta la clave de API, está mal escrita, venció o fue revocada. Envíala como `Authorization: Bearer onx_live_…`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "clave_invalida": {
                    "$ref": "#/components/examples/clave_invalida"
                  }
                }
              }
            }
          },
          "403": {
            "description": "`permiso_faltante`: La clave no tiene el permiso que pide esta ruta o no tiene acceso a ese RUC.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "permiso_faltante": {
                    "$ref": "#/components/examples/permiso_faltante"
                  }
                }
              }
            }
          },
          "409": {
            "description": "`idempotencia_en_conflicto`: Usaste la misma `Idempotency-Key` con otro cuerpo. Genera una clave nueva para cada operación distinta.\n\n`solicitud_en_curso`: Ya estamos procesando una petición con esa `Idempotency-Key`. Espera unos segundos y vuelve a consultar.\n\n`ya_registrado`: Eso ya está registrado: por ejemplo, el RUC ya está en otra cuenta o la serie ya existe.\n\n`estado_no_permite`: El recurso está en un estado que no permite esta operación, por ejemplo anular un comprobante rechazado.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "idempotencia_en_conflicto": {
                    "$ref": "#/components/examples/idempotencia_en_conflicto"
                  },
                  "solicitud_en_curso": {
                    "$ref": "#/components/examples/solicitud_en_curso"
                  },
                  "ya_registrado": {
                    "$ref": "#/components/examples/ya_registrado"
                  },
                  "estado_no_permite": {
                    "$ref": "#/components/examples/estado_no_permite"
                  }
                }
              }
            }
          },
          "429": {
            "description": "`limite_uso`: Hiciste demasiadas peticiones seguidas. Espera los segundos que indica `Retry-After` y vuelve a intentar.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "limite_uso": {
                    "$ref": "#/components/examples/limite_uso"
                  }
                }
              }
            }
          },
          "500": {
            "description": "`error_interno`: Algo falló de nuestro lado. Repite la petición con la misma `Idempotency-Key`: no se duplica nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "error_interno": {
                    "$ref": "#/components/examples/error_interno"
                  }
                }
              }
            }
          },
          "501": {
            "description": "`operacion_no_disponible`: Esta operación existe en el contrato, pero todavía no está habilitada. Revisa en la documentación qué rutas ya puedes usar; no se cobró nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "operacion_no_disponible": {
                    "$ref": "#/components/examples/operacion_no_disponible"
                  }
                }
              }
            }
          },
          "503": {
            "description": "`no_disponible`: El dato todavía se está cargando o actualizando de nuestro lado. Vuelve a intentar después de los segundos que indica `Retry-After`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "no_disponible": {
                    "$ref": "#/components/examples/no_disponible"
                  }
                }
              }
            }
          }
        },
        "x-nexum": {
          "permiso": "cuenta:recargar",
          "cobro": "no",
          "puede_pedir_confirmacion": false,
          "confirmacion_obligatoria": false,
          "acepta_credenciales": false,
          "idempotencia": "requerida",
          "herramienta_mcp": null
        }
      }
    },
    "/v1/confirmaciones/{id}": {
      "get": {
        "operationId": "confirmacion_ver",
        "summary": "Consulta una aprobación pendiente",
        "description": "Estado de una operación que respondió 202 `requiere_confirmacion`. Basta una clave válida, pero solo la ve la clave que la pidió. Cuando está `ejecutada`, `resultado` dice qué se creó.\n\n**Permiso:** `clave_valida`. **Cobro:** No cobra.",
        "tags": [
          "Confirmaciones"
        ],
        "security": [
          {
            "claveApi": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Identificador que empieza con `op_`.",
            "schema": {
              "type": "string",
              "pattern": "^op_[A-Za-z0-9]{8,64}$",
              "examples": [
                "op_8f2c1a7d9e"
              ]
            }
          },
          {
            "$ref": "#/components/parameters/RequestId"
          }
        ],
        "responses": {
          "200": {
            "description": "Estado de la aprobación.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Confirmacion"
                }
              }
            }
          },
          "400": {
            "description": "`validacion`: Algún dato no cumple el formato. En `detalle` va cada campo con su problema.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "validacion": {
                    "$ref": "#/components/examples/validacion"
                  }
                }
              }
            }
          },
          "401": {
            "description": "`clave_invalida`: Falta la clave de API, está mal escrita, venció o fue revocada. Envíala como `Authorization: Bearer onx_live_…`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "clave_invalida": {
                    "$ref": "#/components/examples/clave_invalida"
                  }
                }
              }
            }
          },
          "403": {
            "description": "`permiso_faltante`: La clave no tiene el permiso que pide esta ruta o no tiene acceso a ese RUC.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "permiso_faltante": {
                    "$ref": "#/components/examples/permiso_faltante"
                  }
                }
              }
            }
          },
          "404": {
            "description": "`no_encontrado`: No existe o no pertenece a tu cuenta.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "no_encontrado": {
                    "$ref": "#/components/examples/no_encontrado"
                  }
                }
              }
            }
          },
          "429": {
            "description": "`limite_uso`: Hiciste demasiadas peticiones seguidas. Espera los segundos que indica `Retry-After` y vuelve a intentar.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "limite_uso": {
                    "$ref": "#/components/examples/limite_uso"
                  }
                }
              }
            }
          },
          "500": {
            "description": "`error_interno`: Algo falló de nuestro lado. Repite la petición con la misma `Idempotency-Key`: no se duplica nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "error_interno": {
                    "$ref": "#/components/examples/error_interno"
                  }
                }
              }
            }
          },
          "501": {
            "description": "`operacion_no_disponible`: Esta operación existe en el contrato, pero todavía no está habilitada. Revisa en la documentación qué rutas ya puedes usar; no se cobró nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "operacion_no_disponible": {
                    "$ref": "#/components/examples/operacion_no_disponible"
                  }
                }
              }
            }
          },
          "503": {
            "description": "`no_disponible`: El dato todavía se está cargando o actualizando de nuestro lado. Vuelve a intentar después de los segundos que indica `Retry-After`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "no_disponible": {
                    "$ref": "#/components/examples/no_disponible"
                  }
                }
              }
            }
          }
        },
        "x-nexum": {
          "permiso": "clave_valida",
          "cobro": "no",
          "puede_pedir_confirmacion": false,
          "confirmacion_obligatoria": false,
          "acepta_credenciales": false,
          "idempotencia": "no_aplica",
          "herramienta_mcp": "confirmacion_ver"
        }
      }
    },
    "/v1/claves": {
      "get": {
        "operationId": "clave_listar",
        "summary": "Lista las claves de tu cuenta",
        "description": "Claves activas y revocadas del entorno de tu clave (`live` o `test`), con sus permisos, alcance por RUC y tope. Nunca devuelve la clave completa. Los agentes conectados por OAuth no salen aquí: se ven y desconectan en el panel.\n\n**Permiso:** `claves:administrar`. **Cobro:** No cobra.",
        "tags": [
          "Claves"
        ],
        "security": [
          {
            "claveApi": []
          }
        ],
        "parameters": [
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "Cursor opaco que devolvió la página anterior en `siguiente_cursor`.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 512
            }
          },
          {
            "name": "limite",
            "in": "query",
            "required": false,
            "description": "Cuántos elementos traer (1 a 100; por defecto 20).",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100
            }
          },
          {
            "$ref": "#/components/parameters/RequestId"
          }
        ],
        "responses": {
          "200": {
            "description": "Página de claves.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ListaClaves"
                }
              }
            }
          },
          "400": {
            "description": "`validacion`: Algún dato no cumple el formato. En `detalle` va cada campo con su problema.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "validacion": {
                    "$ref": "#/components/examples/validacion"
                  }
                }
              }
            }
          },
          "401": {
            "description": "`clave_invalida`: Falta la clave de API, está mal escrita, venció o fue revocada. Envíala como `Authorization: Bearer onx_live_…`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "clave_invalida": {
                    "$ref": "#/components/examples/clave_invalida"
                  }
                }
              }
            }
          },
          "403": {
            "description": "`permiso_faltante`: La clave no tiene el permiso que pide esta ruta o no tiene acceso a ese RUC.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "permiso_faltante": {
                    "$ref": "#/components/examples/permiso_faltante"
                  }
                }
              }
            }
          },
          "429": {
            "description": "`limite_uso`: Hiciste demasiadas peticiones seguidas. Espera los segundos que indica `Retry-After` y vuelve a intentar.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "limite_uso": {
                    "$ref": "#/components/examples/limite_uso"
                  }
                }
              }
            }
          },
          "500": {
            "description": "`error_interno`: Algo falló de nuestro lado. Repite la petición con la misma `Idempotency-Key`: no se duplica nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "error_interno": {
                    "$ref": "#/components/examples/error_interno"
                  }
                }
              }
            }
          },
          "501": {
            "description": "`operacion_no_disponible`: Esta operación existe en el contrato, pero todavía no está habilitada. Revisa en la documentación qué rutas ya puedes usar; no se cobró nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "operacion_no_disponible": {
                    "$ref": "#/components/examples/operacion_no_disponible"
                  }
                }
              }
            }
          },
          "503": {
            "description": "`no_disponible`: El dato todavía se está cargando o actualizando de nuestro lado. Vuelve a intentar después de los segundos que indica `Retry-After`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "no_disponible": {
                    "$ref": "#/components/examples/no_disponible"
                  }
                }
              }
            }
          }
        },
        "x-nexum": {
          "permiso": "claves:administrar",
          "cobro": "no",
          "puede_pedir_confirmacion": false,
          "confirmacion_obligatoria": false,
          "acepta_credenciales": false,
          "idempotencia": "no_aplica",
          "herramienta_mcp": "clave_listar"
        }
      },
      "post": {
        "operationId": "clave_crear",
        "summary": "Crea una clave con tope y permisos",
        "description": "Crea una clave para un agente, nunca con más permisos, RUC, tope o plazo que la clave que la crea. Siempre espera la aprobación de una persona (202). Ya aprobada, repite la petición con la misma `Idempotency-Key`: la primera respuesta 201 trae `secreto`; las siguientes responden `ya_registrado` (el secreto no se guarda). Si la persona la rechaza o la aprobación vence, responde `estado_no_permite`.\n\n**Permiso:** `claves:administrar`. **Cobro:** No cobra.\n\n**Idempotency-Key:** obligatoria.\n\n**Siempre espera la aprobación de una persona** (202 `requiere_confirmacion`).",
        "tags": [
          "Claves"
        ],
        "security": [
          {
            "claveApi": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "$ref": "#/components/parameters/RequestId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CrearClave"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Clave creada; guarda `secreto` ahora.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ClaveCreada"
                }
              }
            }
          },
          "202": {
            "description": "Espera la aprobación de una persona.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RespuestaRequiereConfirmacion"
                }
              }
            }
          },
          "400": {
            "description": "`validacion`: Algún dato no cumple el formato. En `detalle` va cada campo con su problema.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "validacion": {
                    "$ref": "#/components/examples/validacion"
                  }
                }
              }
            }
          },
          "401": {
            "description": "`clave_invalida`: Falta la clave de API, está mal escrita, venció o fue revocada. Envíala como `Authorization: Bearer onx_live_…`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "clave_invalida": {
                    "$ref": "#/components/examples/clave_invalida"
                  }
                }
              }
            }
          },
          "403": {
            "description": "`permiso_faltante`: La clave no tiene el permiso que pide esta ruta o no tiene acceso a ese RUC.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "permiso_faltante": {
                    "$ref": "#/components/examples/permiso_faltante"
                  }
                }
              }
            }
          },
          "409": {
            "description": "`idempotencia_en_conflicto`: Usaste la misma `Idempotency-Key` con otro cuerpo. Genera una clave nueva para cada operación distinta.\n\n`solicitud_en_curso`: Ya estamos procesando una petición con esa `Idempotency-Key`. Espera unos segundos y vuelve a consultar.\n\n`ya_registrado`: Eso ya está registrado: por ejemplo, el RUC ya está en otra cuenta o la serie ya existe.\n\n`estado_no_permite`: El recurso está en un estado que no permite esta operación, por ejemplo anular un comprobante rechazado.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "idempotencia_en_conflicto": {
                    "$ref": "#/components/examples/idempotencia_en_conflicto"
                  },
                  "solicitud_en_curso": {
                    "$ref": "#/components/examples/solicitud_en_curso"
                  },
                  "ya_registrado": {
                    "$ref": "#/components/examples/ya_registrado"
                  },
                  "estado_no_permite": {
                    "$ref": "#/components/examples/estado_no_permite"
                  }
                }
              }
            }
          },
          "429": {
            "description": "`limite_uso`: Hiciste demasiadas peticiones seguidas. Espera los segundos que indica `Retry-After` y vuelve a intentar.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "limite_uso": {
                    "$ref": "#/components/examples/limite_uso"
                  }
                }
              }
            }
          },
          "500": {
            "description": "`error_interno`: Algo falló de nuestro lado. Repite la petición con la misma `Idempotency-Key`: no se duplica nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "error_interno": {
                    "$ref": "#/components/examples/error_interno"
                  }
                }
              }
            }
          },
          "501": {
            "description": "`operacion_no_disponible`: Esta operación existe en el contrato, pero todavía no está habilitada. Revisa en la documentación qué rutas ya puedes usar; no se cobró nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "operacion_no_disponible": {
                    "$ref": "#/components/examples/operacion_no_disponible"
                  }
                }
              }
            }
          },
          "503": {
            "description": "`no_disponible`: El dato todavía se está cargando o actualizando de nuestro lado. Vuelve a intentar después de los segundos que indica `Retry-After`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "no_disponible": {
                    "$ref": "#/components/examples/no_disponible"
                  }
                }
              }
            }
          }
        },
        "x-nexum": {
          "permiso": "claves:administrar",
          "cobro": "no",
          "puede_pedir_confirmacion": true,
          "confirmacion_obligatoria": true,
          "acepta_credenciales": false,
          "idempotencia": "requerida",
          "herramienta_mcp": null
        }
      }
    },
    "/v1/claves/{id}": {
      "delete": {
        "operationId": "clave_revocar",
        "summary": "Revoca una clave",
        "description": "La clave deja de funcionar al instante. No se puede deshacer; crea otra si la necesitas. Puedes revocar tu propia clave o una que creó ella (o sus descendientes); una clave nunca revoca a la que la creó. Las demás se revocan desde el panel.\n\n**Permiso:** `claves:administrar`. **Cobro:** No cobra.",
        "tags": [
          "Claves"
        ],
        "security": [
          {
            "claveApi": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Identificador que empieza con `clv_`.",
            "schema": {
              "type": "string",
              "pattern": "^clv_[A-Za-z0-9]{8,64}$",
              "examples": [
                "clv_8f2c1a7d9e"
              ]
            }
          },
          {
            "$ref": "#/components/parameters/RequestId"
          }
        ],
        "responses": {
          "200": {
            "description": "Clave revocada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Clave"
                }
              }
            }
          },
          "400": {
            "description": "`validacion`: Algún dato no cumple el formato. En `detalle` va cada campo con su problema.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "validacion": {
                    "$ref": "#/components/examples/validacion"
                  }
                }
              }
            }
          },
          "401": {
            "description": "`clave_invalida`: Falta la clave de API, está mal escrita, venció o fue revocada. Envíala como `Authorization: Bearer onx_live_…`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "clave_invalida": {
                    "$ref": "#/components/examples/clave_invalida"
                  }
                }
              }
            }
          },
          "403": {
            "description": "`permiso_faltante`: La clave no tiene el permiso que pide esta ruta o no tiene acceso a ese RUC.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "permiso_faltante": {
                    "$ref": "#/components/examples/permiso_faltante"
                  }
                }
              }
            }
          },
          "404": {
            "description": "`no_encontrado`: No existe o no pertenece a tu cuenta.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "no_encontrado": {
                    "$ref": "#/components/examples/no_encontrado"
                  }
                }
              }
            }
          },
          "429": {
            "description": "`limite_uso`: Hiciste demasiadas peticiones seguidas. Espera los segundos que indica `Retry-After` y vuelve a intentar.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "limite_uso": {
                    "$ref": "#/components/examples/limite_uso"
                  }
                }
              }
            }
          },
          "500": {
            "description": "`error_interno`: Algo falló de nuestro lado. Repite la petición con la misma `Idempotency-Key`: no se duplica nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "error_interno": {
                    "$ref": "#/components/examples/error_interno"
                  }
                }
              }
            }
          },
          "501": {
            "description": "`operacion_no_disponible`: Esta operación existe en el contrato, pero todavía no está habilitada. Revisa en la documentación qué rutas ya puedes usar; no se cobró nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "operacion_no_disponible": {
                    "$ref": "#/components/examples/operacion_no_disponible"
                  }
                }
              }
            }
          },
          "503": {
            "description": "`no_disponible`: El dato todavía se está cargando o actualizando de nuestro lado. Vuelve a intentar después de los segundos que indica `Retry-After`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "no_disponible": {
                    "$ref": "#/components/examples/no_disponible"
                  }
                }
              }
            }
          }
        },
        "x-nexum": {
          "permiso": "claves:administrar",
          "cobro": "no",
          "puede_pedir_confirmacion": false,
          "confirmacion_obligatoria": false,
          "acepta_credenciales": false,
          "idempotencia": "no_aplica",
          "herramienta_mcp": "clave_revocar"
        }
      }
    },
    "/v1/soporte/tickets": {
      "post": {
        "operationId": "ticket_crear",
        "summary": "Abre un ticket de soporte",
        "description": "Reporta un problema o propone una mejora. Basta una clave válida, así que un agente puede reportar lo que le falla; incluye el `request_id`. Te respondemos en el ticket. Nunca pegues claves, contraseñas ni certificados.\n\n**Permiso:** `clave_valida`. **Cobro:** No cobra.",
        "tags": [
          "Cuenta"
        ],
        "security": [
          {
            "claveApi": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKeyOpcional"
          },
          {
            "$ref": "#/components/parameters/RequestId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CrearTicket"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Ticket abierto.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TicketDetalle"
                }
              }
            }
          },
          "400": {
            "description": "`validacion`: Algún dato no cumple el formato. En `detalle` va cada campo con su problema.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "validacion": {
                    "$ref": "#/components/examples/validacion"
                  }
                }
              }
            }
          },
          "401": {
            "description": "`clave_invalida`: Falta la clave de API, está mal escrita, venció o fue revocada. Envíala como `Authorization: Bearer onx_live_…`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "clave_invalida": {
                    "$ref": "#/components/examples/clave_invalida"
                  }
                }
              }
            }
          },
          "403": {
            "description": "`permiso_faltante`: La clave no tiene el permiso que pide esta ruta o no tiene acceso a ese RUC.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "permiso_faltante": {
                    "$ref": "#/components/examples/permiso_faltante"
                  }
                }
              }
            }
          },
          "409": {
            "description": "`idempotencia_en_conflicto`: Usaste la misma `Idempotency-Key` con otro cuerpo. Genera una clave nueva para cada operación distinta.\n\n`solicitud_en_curso`: Ya estamos procesando una petición con esa `Idempotency-Key`. Espera unos segundos y vuelve a consultar.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "idempotencia_en_conflicto": {
                    "$ref": "#/components/examples/idempotencia_en_conflicto"
                  },
                  "solicitud_en_curso": {
                    "$ref": "#/components/examples/solicitud_en_curso"
                  }
                }
              }
            }
          },
          "429": {
            "description": "`limite_uso`: Hiciste demasiadas peticiones seguidas. Espera los segundos que indica `Retry-After` y vuelve a intentar.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "limite_uso": {
                    "$ref": "#/components/examples/limite_uso"
                  }
                }
              }
            }
          },
          "500": {
            "description": "`error_interno`: Algo falló de nuestro lado. Repite la petición con la misma `Idempotency-Key`: no se duplica nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "error_interno": {
                    "$ref": "#/components/examples/error_interno"
                  }
                }
              }
            }
          },
          "501": {
            "description": "`operacion_no_disponible`: Esta operación existe en el contrato, pero todavía no está habilitada. Revisa en la documentación qué rutas ya puedes usar; no se cobró nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "operacion_no_disponible": {
                    "$ref": "#/components/examples/operacion_no_disponible"
                  }
                }
              }
            }
          },
          "503": {
            "description": "`no_disponible`: El dato todavía se está cargando o actualizando de nuestro lado. Vuelve a intentar después de los segundos que indica `Retry-After`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "no_disponible": {
                    "$ref": "#/components/examples/no_disponible"
                  }
                }
              }
            }
          }
        },
        "x-nexum": {
          "permiso": "clave_valida",
          "cobro": "no",
          "puede_pedir_confirmacion": false,
          "confirmacion_obligatoria": false,
          "acepta_credenciales": false,
          "idempotencia": "opcional",
          "herramienta_mcp": "ticket_crear"
        }
      },
      "get": {
        "operationId": "ticket_listar",
        "summary": "Lista tus tickets de soporte",
        "description": "Tickets que abrió esta clave, del más reciente al más antiguo, sin sus mensajes.\n\n**Permiso:** `clave_valida`. **Cobro:** No cobra.",
        "tags": [
          "Cuenta"
        ],
        "security": [
          {
            "claveApi": []
          }
        ],
        "parameters": [
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "Cursor opaco que devolvió la página anterior en `siguiente_cursor`.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 512
            }
          },
          {
            "name": "limite",
            "in": "query",
            "required": false,
            "description": "Cuántos elementos traer (1 a 100; por defecto 20).",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100
            }
          },
          {
            "name": "estado",
            "in": "query",
            "required": false,
            "description": "Solo los tickets en ese estado.",
            "schema": {
              "type": "string",
              "enum": [
                "abierto",
                "en_revision",
                "respondido",
                "escalado",
                "cerrado"
              ]
            }
          },
          {
            "$ref": "#/components/parameters/RequestId"
          }
        ],
        "responses": {
          "200": {
            "description": "Página de tickets.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ListaTickets"
                }
              }
            }
          },
          "400": {
            "description": "`validacion`: Algún dato no cumple el formato. En `detalle` va cada campo con su problema.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "validacion": {
                    "$ref": "#/components/examples/validacion"
                  }
                }
              }
            }
          },
          "401": {
            "description": "`clave_invalida`: Falta la clave de API, está mal escrita, venció o fue revocada. Envíala como `Authorization: Bearer onx_live_…`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "clave_invalida": {
                    "$ref": "#/components/examples/clave_invalida"
                  }
                }
              }
            }
          },
          "403": {
            "description": "`permiso_faltante`: La clave no tiene el permiso que pide esta ruta o no tiene acceso a ese RUC.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "permiso_faltante": {
                    "$ref": "#/components/examples/permiso_faltante"
                  }
                }
              }
            }
          },
          "429": {
            "description": "`limite_uso`: Hiciste demasiadas peticiones seguidas. Espera los segundos que indica `Retry-After` y vuelve a intentar.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "limite_uso": {
                    "$ref": "#/components/examples/limite_uso"
                  }
                }
              }
            }
          },
          "500": {
            "description": "`error_interno`: Algo falló de nuestro lado. Repite la petición con la misma `Idempotency-Key`: no se duplica nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "error_interno": {
                    "$ref": "#/components/examples/error_interno"
                  }
                }
              }
            }
          },
          "501": {
            "description": "`operacion_no_disponible`: Esta operación existe en el contrato, pero todavía no está habilitada. Revisa en la documentación qué rutas ya puedes usar; no se cobró nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "operacion_no_disponible": {
                    "$ref": "#/components/examples/operacion_no_disponible"
                  }
                }
              }
            }
          },
          "503": {
            "description": "`no_disponible`: El dato todavía se está cargando o actualizando de nuestro lado. Vuelve a intentar después de los segundos que indica `Retry-After`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "no_disponible": {
                    "$ref": "#/components/examples/no_disponible"
                  }
                }
              }
            }
          }
        },
        "x-nexum": {
          "permiso": "clave_valida",
          "cobro": "no",
          "puede_pedir_confirmacion": false,
          "confirmacion_obligatoria": false,
          "acepta_credenciales": false,
          "idempotencia": "no_aplica",
          "herramienta_mcp": null
        }
      }
    },
    "/v1/soporte/tickets/{id}": {
      "get": {
        "operationId": "ticket_ver",
        "summary": "Consulta un ticket de soporte",
        "description": "Un ticket que abrió esta clave, con todos sus mensajes y su estado. Úsalo para ver si ya te respondimos.\n\n**Permiso:** `clave_valida`. **Cobro:** No cobra.",
        "tags": [
          "Cuenta"
        ],
        "security": [
          {
            "claveApi": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Identificador que empieza con `tkt_`.",
            "schema": {
              "type": "string",
              "pattern": "^tkt_[A-Za-z0-9]{8,64}$",
              "examples": [
                "tkt_8f2c1a7d9e"
              ]
            }
          },
          {
            "$ref": "#/components/parameters/RequestId"
          }
        ],
        "responses": {
          "200": {
            "description": "Ticket con sus mensajes.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TicketDetalle"
                }
              }
            }
          },
          "400": {
            "description": "`validacion`: Algún dato no cumple el formato. En `detalle` va cada campo con su problema.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "validacion": {
                    "$ref": "#/components/examples/validacion"
                  }
                }
              }
            }
          },
          "401": {
            "description": "`clave_invalida`: Falta la clave de API, está mal escrita, venció o fue revocada. Envíala como `Authorization: Bearer onx_live_…`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "clave_invalida": {
                    "$ref": "#/components/examples/clave_invalida"
                  }
                }
              }
            }
          },
          "403": {
            "description": "`permiso_faltante`: La clave no tiene el permiso que pide esta ruta o no tiene acceso a ese RUC.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "permiso_faltante": {
                    "$ref": "#/components/examples/permiso_faltante"
                  }
                }
              }
            }
          },
          "404": {
            "description": "`no_encontrado`: No existe o no pertenece a tu cuenta.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "no_encontrado": {
                    "$ref": "#/components/examples/no_encontrado"
                  }
                }
              }
            }
          },
          "429": {
            "description": "`limite_uso`: Hiciste demasiadas peticiones seguidas. Espera los segundos que indica `Retry-After` y vuelve a intentar.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "limite_uso": {
                    "$ref": "#/components/examples/limite_uso"
                  }
                }
              }
            }
          },
          "500": {
            "description": "`error_interno`: Algo falló de nuestro lado. Repite la petición con la misma `Idempotency-Key`: no se duplica nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "error_interno": {
                    "$ref": "#/components/examples/error_interno"
                  }
                }
              }
            }
          },
          "501": {
            "description": "`operacion_no_disponible`: Esta operación existe en el contrato, pero todavía no está habilitada. Revisa en la documentación qué rutas ya puedes usar; no se cobró nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "operacion_no_disponible": {
                    "$ref": "#/components/examples/operacion_no_disponible"
                  }
                }
              }
            }
          },
          "503": {
            "description": "`no_disponible`: El dato todavía se está cargando o actualizando de nuestro lado. Vuelve a intentar después de los segundos que indica `Retry-After`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "no_disponible": {
                    "$ref": "#/components/examples/no_disponible"
                  }
                }
              }
            }
          }
        },
        "x-nexum": {
          "permiso": "clave_valida",
          "cobro": "no",
          "puede_pedir_confirmacion": false,
          "confirmacion_obligatoria": false,
          "acepta_credenciales": false,
          "idempotencia": "no_aplica",
          "herramienta_mcp": "ticket_ver"
        }
      }
    },
    "/v1/soporte/tickets/{id}/mensajes": {
      "post": {
        "operationId": "ticket_responder",
        "summary": "Responde en un ticket de soporte",
        "description": "Agrega tu mensaje a un ticket que abrió esta clave. Un ticket cerrado no recibe mensajes: abre otro.\n\n**Permiso:** `clave_valida`. **Cobro:** No cobra.",
        "tags": [
          "Cuenta"
        ],
        "security": [
          {
            "claveApi": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Identificador que empieza con `tkt_`.",
            "schema": {
              "type": "string",
              "pattern": "^tkt_[A-Za-z0-9]{8,64}$",
              "examples": [
                "tkt_8f2c1a7d9e"
              ]
            }
          },
          {
            "$ref": "#/components/parameters/IdempotencyKeyOpcional"
          },
          {
            "$ref": "#/components/parameters/RequestId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ResponderTicket"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Mensaje agregado; el ticket vuelve a esperar nuestra respuesta.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TicketDetalle"
                }
              }
            }
          },
          "400": {
            "description": "`validacion`: Algún dato no cumple el formato. En `detalle` va cada campo con su problema.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "validacion": {
                    "$ref": "#/components/examples/validacion"
                  }
                }
              }
            }
          },
          "401": {
            "description": "`clave_invalida`: Falta la clave de API, está mal escrita, venció o fue revocada. Envíala como `Authorization: Bearer onx_live_…`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "clave_invalida": {
                    "$ref": "#/components/examples/clave_invalida"
                  }
                }
              }
            }
          },
          "403": {
            "description": "`permiso_faltante`: La clave no tiene el permiso que pide esta ruta o no tiene acceso a ese RUC.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "permiso_faltante": {
                    "$ref": "#/components/examples/permiso_faltante"
                  }
                }
              }
            }
          },
          "404": {
            "description": "`no_encontrado`: No existe o no pertenece a tu cuenta.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "no_encontrado": {
                    "$ref": "#/components/examples/no_encontrado"
                  }
                }
              }
            }
          },
          "409": {
            "description": "`idempotencia_en_conflicto`: Usaste la misma `Idempotency-Key` con otro cuerpo. Genera una clave nueva para cada operación distinta.\n\n`solicitud_en_curso`: Ya estamos procesando una petición con esa `Idempotency-Key`. Espera unos segundos y vuelve a consultar.\n\n`estado_no_permite`: El recurso está en un estado que no permite esta operación, por ejemplo anular un comprobante rechazado.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "idempotencia_en_conflicto": {
                    "$ref": "#/components/examples/idempotencia_en_conflicto"
                  },
                  "solicitud_en_curso": {
                    "$ref": "#/components/examples/solicitud_en_curso"
                  },
                  "estado_no_permite": {
                    "$ref": "#/components/examples/estado_no_permite"
                  }
                }
              }
            }
          },
          "429": {
            "description": "`limite_uso`: Hiciste demasiadas peticiones seguidas. Espera los segundos que indica `Retry-After` y vuelve a intentar.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "limite_uso": {
                    "$ref": "#/components/examples/limite_uso"
                  }
                }
              }
            }
          },
          "500": {
            "description": "`error_interno`: Algo falló de nuestro lado. Repite la petición con la misma `Idempotency-Key`: no se duplica nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "error_interno": {
                    "$ref": "#/components/examples/error_interno"
                  }
                }
              }
            }
          },
          "501": {
            "description": "`operacion_no_disponible`: Esta operación existe en el contrato, pero todavía no está habilitada. Revisa en la documentación qué rutas ya puedes usar; no se cobró nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "operacion_no_disponible": {
                    "$ref": "#/components/examples/operacion_no_disponible"
                  }
                }
              }
            }
          },
          "503": {
            "description": "`no_disponible`: El dato todavía se está cargando o actualizando de nuestro lado. Vuelve a intentar después de los segundos que indica `Retry-After`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "no_disponible": {
                    "$ref": "#/components/examples/no_disponible"
                  }
                }
              }
            }
          }
        },
        "x-nexum": {
          "permiso": "clave_valida",
          "cobro": "no",
          "puede_pedir_confirmacion": false,
          "confirmacion_obligatoria": false,
          "acepta_credenciales": false,
          "idempotencia": "opcional",
          "herramienta_mcp": null
        }
      }
    },
    "/v1/soporte/tickets/{id}/cerrar": {
      "post": {
        "operationId": "ticket_cerrar",
        "summary": "Cierra un ticket de soporte",
        "description": "Cierra un ticket que abrió esta clave cuando ya no necesitas ayuda. Cerrar uno ya cerrado no cambia nada.\n\n**Permiso:** `clave_valida`. **Cobro:** No cobra.",
        "tags": [
          "Cuenta"
        ],
        "security": [
          {
            "claveApi": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Identificador que empieza con `tkt_`.",
            "schema": {
              "type": "string",
              "pattern": "^tkt_[A-Za-z0-9]{8,64}$",
              "examples": [
                "tkt_8f2c1a7d9e"
              ]
            }
          },
          {
            "$ref": "#/components/parameters/IdempotencyKeyOpcional"
          },
          {
            "$ref": "#/components/parameters/RequestId"
          }
        ],
        "responses": {
          "200": {
            "description": "Ticket cerrado.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Ticket"
                }
              }
            }
          },
          "400": {
            "description": "`validacion`: Algún dato no cumple el formato. En `detalle` va cada campo con su problema.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "validacion": {
                    "$ref": "#/components/examples/validacion"
                  }
                }
              }
            }
          },
          "401": {
            "description": "`clave_invalida`: Falta la clave de API, está mal escrita, venció o fue revocada. Envíala como `Authorization: Bearer onx_live_…`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "clave_invalida": {
                    "$ref": "#/components/examples/clave_invalida"
                  }
                }
              }
            }
          },
          "403": {
            "description": "`permiso_faltante`: La clave no tiene el permiso que pide esta ruta o no tiene acceso a ese RUC.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "permiso_faltante": {
                    "$ref": "#/components/examples/permiso_faltante"
                  }
                }
              }
            }
          },
          "404": {
            "description": "`no_encontrado`: No existe o no pertenece a tu cuenta.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "no_encontrado": {
                    "$ref": "#/components/examples/no_encontrado"
                  }
                }
              }
            }
          },
          "409": {
            "description": "`idempotencia_en_conflicto`: Usaste la misma `Idempotency-Key` con otro cuerpo. Genera una clave nueva para cada operación distinta.\n\n`solicitud_en_curso`: Ya estamos procesando una petición con esa `Idempotency-Key`. Espera unos segundos y vuelve a consultar.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "idempotencia_en_conflicto": {
                    "$ref": "#/components/examples/idempotencia_en_conflicto"
                  },
                  "solicitud_en_curso": {
                    "$ref": "#/components/examples/solicitud_en_curso"
                  }
                }
              }
            }
          },
          "429": {
            "description": "`limite_uso`: Hiciste demasiadas peticiones seguidas. Espera los segundos que indica `Retry-After` y vuelve a intentar.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "limite_uso": {
                    "$ref": "#/components/examples/limite_uso"
                  }
                }
              }
            }
          },
          "500": {
            "description": "`error_interno`: Algo falló de nuestro lado. Repite la petición con la misma `Idempotency-Key`: no se duplica nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "error_interno": {
                    "$ref": "#/components/examples/error_interno"
                  }
                }
              }
            }
          },
          "501": {
            "description": "`operacion_no_disponible`: Esta operación existe en el contrato, pero todavía no está habilitada. Revisa en la documentación qué rutas ya puedes usar; no se cobró nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "operacion_no_disponible": {
                    "$ref": "#/components/examples/operacion_no_disponible"
                  }
                }
              }
            }
          },
          "503": {
            "description": "`no_disponible`: El dato todavía se está cargando o actualizando de nuestro lado. Vuelve a intentar después de los segundos que indica `Retry-After`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "no_disponible": {
                    "$ref": "#/components/examples/no_disponible"
                  }
                }
              }
            }
          }
        },
        "x-nexum": {
          "permiso": "clave_valida",
          "cobro": "no",
          "puede_pedir_confirmacion": false,
          "confirmacion_obligatoria": false,
          "acepta_credenciales": false,
          "idempotencia": "opcional",
          "herramienta_mcp": null
        }
      }
    },
    "/v1/ruc/{ruc}": {
      "get": {
        "operationId": "ruc_consultar",
        "summary": "Consulta un RUC",
        "description": "Razón social, estado, condición y dirección desde el padrón reducido de SUNAT. Gratis hasta el cupo mensual de tu plan; luego se descuenta del saldo.\n\n**Permiso:** `datos:leer`. **Cobro:** Consume el cupo gratis de tu plan y, luego, saldo.",
        "tags": [
          "Datos"
        ],
        "security": [
          {
            "claveApi": []
          }
        ],
        "parameters": [
          {
            "name": "ruc",
            "in": "path",
            "required": true,
            "description": "RUC del emisor o contribuyente.",
            "schema": {
              "type": "string",
              "pattern": "^(10|15|16|17|20)\\d{9}$",
              "examples": [
                "20000000001"
              ]
            }
          },
          {
            "$ref": "#/components/parameters/RequestId"
          }
        ],
        "responses": {
          "200": {
            "description": "Datos del contribuyente.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Contribuyente"
                }
              }
            }
          },
          "400": {
            "description": "`validacion`: Algún dato no cumple el formato. En `detalle` va cada campo con su problema.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "validacion": {
                    "$ref": "#/components/examples/validacion"
                  }
                }
              }
            }
          },
          "401": {
            "description": "`clave_invalida`: Falta la clave de API, está mal escrita, venció o fue revocada. Envíala como `Authorization: Bearer onx_live_…`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "clave_invalida": {
                    "$ref": "#/components/examples/clave_invalida"
                  }
                }
              }
            }
          },
          "402": {
            "description": "`saldo_insuficiente`: No te alcanza el saldo para esta operación. Pásale `recarga_url` a una persona de tu cuenta para que recargue.\n\n`tope_alcanzado`: La clave llegó a su tope de gasto del periodo. Una persona de tu cuenta puede subirlo desde el panel.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error402"
                },
                "examples": {
                  "saldo_insuficiente": {
                    "$ref": "#/components/examples/saldo_insuficiente"
                  },
                  "tope_alcanzado": {
                    "$ref": "#/components/examples/tope_alcanzado"
                  }
                }
              }
            }
          },
          "403": {
            "description": "`permiso_faltante`: La clave no tiene el permiso que pide esta ruta o no tiene acceso a ese RUC.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "permiso_faltante": {
                    "$ref": "#/components/examples/permiso_faltante"
                  }
                }
              }
            }
          },
          "404": {
            "description": "`no_encontrado`: No existe o no pertenece a tu cuenta.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "no_encontrado": {
                    "$ref": "#/components/examples/no_encontrado"
                  }
                }
              }
            }
          },
          "429": {
            "description": "`limite_uso`: Hiciste demasiadas peticiones seguidas. Espera los segundos que indica `Retry-After` y vuelve a intentar.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "limite_uso": {
                    "$ref": "#/components/examples/limite_uso"
                  }
                }
              }
            }
          },
          "500": {
            "description": "`error_interno`: Algo falló de nuestro lado. Repite la petición con la misma `Idempotency-Key`: no se duplica nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "error_interno": {
                    "$ref": "#/components/examples/error_interno"
                  }
                }
              }
            }
          },
          "501": {
            "description": "`operacion_no_disponible`: Esta operación existe en el contrato, pero todavía no está habilitada. Revisa en la documentación qué rutas ya puedes usar; no se cobró nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "operacion_no_disponible": {
                    "$ref": "#/components/examples/operacion_no_disponible"
                  }
                }
              }
            }
          },
          "503": {
            "description": "`no_disponible`: El dato todavía se está cargando o actualizando de nuestro lado. Vuelve a intentar después de los segundos que indica `Retry-After`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "no_disponible": {
                    "$ref": "#/components/examples/no_disponible"
                  }
                }
              }
            }
          }
        },
        "x-nexum": {
          "permiso": "datos:leer",
          "cobro": "consumo",
          "puede_pedir_confirmacion": false,
          "confirmacion_obligatoria": false,
          "acepta_credenciales": false,
          "idempotencia": "no_aplica",
          "herramienta_mcp": "ruc_consultar"
        }
      }
    },
    "/v1/ruc/{ruc}/padrones": {
      "get": {
        "operationId": "ruc_padrones",
        "summary": "Consulta los padrones de un RUC",
        "description": "Indica si el RUC es agente de retención, agente de percepción o buen contribuyente, según SUNAT.\n\n**Permiso:** `datos:leer`. **Cobro:** Consume el cupo gratis de tu plan y, luego, saldo.",
        "tags": [
          "Datos"
        ],
        "security": [
          {
            "claveApi": []
          }
        ],
        "parameters": [
          {
            "name": "ruc",
            "in": "path",
            "required": true,
            "description": "RUC del emisor o contribuyente.",
            "schema": {
              "type": "string",
              "pattern": "^(10|15|16|17|20)\\d{9}$",
              "examples": [
                "20000000001"
              ]
            }
          },
          {
            "$ref": "#/components/parameters/RequestId"
          }
        ],
        "responses": {
          "200": {
            "description": "Padrones del RUC.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Padrones"
                }
              }
            }
          },
          "400": {
            "description": "`validacion`: Algún dato no cumple el formato. En `detalle` va cada campo con su problema.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "validacion": {
                    "$ref": "#/components/examples/validacion"
                  }
                }
              }
            }
          },
          "401": {
            "description": "`clave_invalida`: Falta la clave de API, está mal escrita, venció o fue revocada. Envíala como `Authorization: Bearer onx_live_…`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "clave_invalida": {
                    "$ref": "#/components/examples/clave_invalida"
                  }
                }
              }
            }
          },
          "402": {
            "description": "`saldo_insuficiente`: No te alcanza el saldo para esta operación. Pásale `recarga_url` a una persona de tu cuenta para que recargue.\n\n`tope_alcanzado`: La clave llegó a su tope de gasto del periodo. Una persona de tu cuenta puede subirlo desde el panel.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error402"
                },
                "examples": {
                  "saldo_insuficiente": {
                    "$ref": "#/components/examples/saldo_insuficiente"
                  },
                  "tope_alcanzado": {
                    "$ref": "#/components/examples/tope_alcanzado"
                  }
                }
              }
            }
          },
          "403": {
            "description": "`permiso_faltante`: La clave no tiene el permiso que pide esta ruta o no tiene acceso a ese RUC.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "permiso_faltante": {
                    "$ref": "#/components/examples/permiso_faltante"
                  }
                }
              }
            }
          },
          "404": {
            "description": "`no_encontrado`: No existe o no pertenece a tu cuenta.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "no_encontrado": {
                    "$ref": "#/components/examples/no_encontrado"
                  }
                }
              }
            }
          },
          "429": {
            "description": "`limite_uso`: Hiciste demasiadas peticiones seguidas. Espera los segundos que indica `Retry-After` y vuelve a intentar.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "limite_uso": {
                    "$ref": "#/components/examples/limite_uso"
                  }
                }
              }
            }
          },
          "500": {
            "description": "`error_interno`: Algo falló de nuestro lado. Repite la petición con la misma `Idempotency-Key`: no se duplica nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "error_interno": {
                    "$ref": "#/components/examples/error_interno"
                  }
                }
              }
            }
          },
          "501": {
            "description": "`operacion_no_disponible`: Esta operación existe en el contrato, pero todavía no está habilitada. Revisa en la documentación qué rutas ya puedes usar; no se cobró nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "operacion_no_disponible": {
                    "$ref": "#/components/examples/operacion_no_disponible"
                  }
                }
              }
            }
          },
          "503": {
            "description": "`no_disponible`: El dato todavía se está cargando o actualizando de nuestro lado. Vuelve a intentar después de los segundos que indica `Retry-After`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "no_disponible": {
                    "$ref": "#/components/examples/no_disponible"
                  }
                }
              }
            }
          }
        },
        "x-nexum": {
          "permiso": "datos:leer",
          "cobro": "consumo",
          "puede_pedir_confirmacion": false,
          "confirmacion_obligatoria": false,
          "acepta_credenciales": false,
          "idempotencia": "no_aplica",
          "herramienta_mcp": "ruc_padrones"
        }
      }
    },
    "/v1/tipo-cambio": {
      "get": {
        "operationId": "tipo_cambio_consultar",
        "summary": "Consulta el tipo de cambio",
        "description": "Compra y venta oficiales del dólar para una fecha, según el BCRP. Sin fecha, el de hoy en Lima.\n\n**Permiso:** `datos:leer`. **Cobro:** Consume el cupo gratis de tu plan y, luego, saldo.",
        "tags": [
          "Datos"
        ],
        "security": [
          {
            "claveApi": []
          }
        ],
        "parameters": [
          {
            "name": "fecha",
            "in": "query",
            "required": false,
            "description": "Día que quieres; si no lo envías, hoy en Lima.",
            "schema": {
              "type": "string",
              "format": "date",
              "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$",
              "examples": [
                "2026-11-15"
              ]
            }
          },
          {
            "$ref": "#/components/parameters/RequestId"
          }
        ],
        "responses": {
          "200": {
            "description": "Tipo de cambio.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TipoCambio"
                }
              }
            }
          },
          "400": {
            "description": "`validacion`: Algún dato no cumple el formato. En `detalle` va cada campo con su problema.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "validacion": {
                    "$ref": "#/components/examples/validacion"
                  }
                }
              }
            }
          },
          "401": {
            "description": "`clave_invalida`: Falta la clave de API, está mal escrita, venció o fue revocada. Envíala como `Authorization: Bearer onx_live_…`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "clave_invalida": {
                    "$ref": "#/components/examples/clave_invalida"
                  }
                }
              }
            }
          },
          "402": {
            "description": "`saldo_insuficiente`: No te alcanza el saldo para esta operación. Pásale `recarga_url` a una persona de tu cuenta para que recargue.\n\n`tope_alcanzado`: La clave llegó a su tope de gasto del periodo. Una persona de tu cuenta puede subirlo desde el panel.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error402"
                },
                "examples": {
                  "saldo_insuficiente": {
                    "$ref": "#/components/examples/saldo_insuficiente"
                  },
                  "tope_alcanzado": {
                    "$ref": "#/components/examples/tope_alcanzado"
                  }
                }
              }
            }
          },
          "403": {
            "description": "`permiso_faltante`: La clave no tiene el permiso que pide esta ruta o no tiene acceso a ese RUC.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "permiso_faltante": {
                    "$ref": "#/components/examples/permiso_faltante"
                  }
                }
              }
            }
          },
          "404": {
            "description": "`no_encontrado`: No existe o no pertenece a tu cuenta.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "no_encontrado": {
                    "$ref": "#/components/examples/no_encontrado"
                  }
                }
              }
            }
          },
          "429": {
            "description": "`limite_uso`: Hiciste demasiadas peticiones seguidas. Espera los segundos que indica `Retry-After` y vuelve a intentar.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "limite_uso": {
                    "$ref": "#/components/examples/limite_uso"
                  }
                }
              }
            }
          },
          "500": {
            "description": "`error_interno`: Algo falló de nuestro lado. Repite la petición con la misma `Idempotency-Key`: no se duplica nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "error_interno": {
                    "$ref": "#/components/examples/error_interno"
                  }
                }
              }
            }
          },
          "501": {
            "description": "`operacion_no_disponible`: Esta operación existe en el contrato, pero todavía no está habilitada. Revisa en la documentación qué rutas ya puedes usar; no se cobró nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "operacion_no_disponible": {
                    "$ref": "#/components/examples/operacion_no_disponible"
                  }
                }
              }
            }
          },
          "503": {
            "description": "`no_disponible`: El dato todavía se está cargando o actualizando de nuestro lado. Vuelve a intentar después de los segundos que indica `Retry-After`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "no_disponible": {
                    "$ref": "#/components/examples/no_disponible"
                  }
                }
              }
            }
          }
        },
        "x-nexum": {
          "permiso": "datos:leer",
          "cobro": "consumo",
          "puede_pedir_confirmacion": false,
          "confirmacion_obligatoria": false,
          "acepta_credenciales": false,
          "idempotencia": "no_aplica",
          "herramienta_mcp": "tipo_cambio_consultar"
        }
      }
    },
    "/v1/emisores": {
      "post": {
        "operationId": "emisor_crear",
        "summary": "Registra un RUC emisor",
        "description": "Agrega un RUC a tu cuenta para emitir. Revisamos el padrón: si el RUC está obligado a OSE, no se acepta en la v1; si ya está en otra cuenta, responde `ya_registrado` (se transfiere por soporte).\n\n**Permiso:** `emisores:administrar`. **Cobro:** No cobra.",
        "tags": [
          "Emisores"
        ],
        "security": [
          {
            "claveApi": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKeyOpcional"
          },
          {
            "$ref": "#/components/parameters/RequestId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CrearEmisor"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Emisor registrado.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Emisor"
                }
              }
            }
          },
          "400": {
            "description": "`validacion`: Algún dato no cumple el formato. En `detalle` va cada campo con su problema.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "validacion": {
                    "$ref": "#/components/examples/validacion"
                  }
                }
              }
            }
          },
          "401": {
            "description": "`clave_invalida`: Falta la clave de API, está mal escrita, venció o fue revocada. Envíala como `Authorization: Bearer onx_live_…`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "clave_invalida": {
                    "$ref": "#/components/examples/clave_invalida"
                  }
                }
              }
            }
          },
          "403": {
            "description": "`permiso_faltante`: La clave no tiene el permiso que pide esta ruta o no tiene acceso a ese RUC.\n\n`emisor_obligado_ose`: Ese RUC figura en el padrón de obligados a emitir mediante un OSE; por ahora no podemos emitir por él.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "permiso_faltante": {
                    "$ref": "#/components/examples/permiso_faltante"
                  },
                  "emisor_obligado_ose": {
                    "$ref": "#/components/examples/emisor_obligado_ose"
                  }
                }
              }
            }
          },
          "409": {
            "description": "`idempotencia_en_conflicto`: Usaste la misma `Idempotency-Key` con otro cuerpo. Genera una clave nueva para cada operación distinta.\n\n`solicitud_en_curso`: Ya estamos procesando una petición con esa `Idempotency-Key`. Espera unos segundos y vuelve a consultar.\n\n`ya_registrado`: Eso ya está registrado: por ejemplo, el RUC ya está en otra cuenta o la serie ya existe.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "idempotencia_en_conflicto": {
                    "$ref": "#/components/examples/idempotencia_en_conflicto"
                  },
                  "solicitud_en_curso": {
                    "$ref": "#/components/examples/solicitud_en_curso"
                  },
                  "ya_registrado": {
                    "$ref": "#/components/examples/ya_registrado"
                  }
                }
              }
            }
          },
          "429": {
            "description": "`limite_uso`: Hiciste demasiadas peticiones seguidas. Espera los segundos que indica `Retry-After` y vuelve a intentar.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "limite_uso": {
                    "$ref": "#/components/examples/limite_uso"
                  }
                }
              }
            }
          },
          "500": {
            "description": "`error_interno`: Algo falló de nuestro lado. Repite la petición con la misma `Idempotency-Key`: no se duplica nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "error_interno": {
                    "$ref": "#/components/examples/error_interno"
                  }
                }
              }
            }
          },
          "501": {
            "description": "`operacion_no_disponible`: Esta operación existe en el contrato, pero todavía no está habilitada. Revisa en la documentación qué rutas ya puedes usar; no se cobró nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "operacion_no_disponible": {
                    "$ref": "#/components/examples/operacion_no_disponible"
                  }
                }
              }
            }
          },
          "503": {
            "description": "`no_disponible`: El dato todavía se está cargando o actualizando de nuestro lado. Vuelve a intentar después de los segundos que indica `Retry-After`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "no_disponible": {
                    "$ref": "#/components/examples/no_disponible"
                  }
                }
              }
            }
          }
        },
        "x-nexum": {
          "permiso": "emisores:administrar",
          "cobro": "no",
          "puede_pedir_confirmacion": false,
          "confirmacion_obligatoria": false,
          "acepta_credenciales": false,
          "idempotencia": "opcional",
          "herramienta_mcp": "emisor_crear"
        }
      },
      "get": {
        "operationId": "emisor_listar",
        "summary": "Lista tus RUC emisores",
        "description": "RUC emisores de tu cuenta a los que tiene acceso la clave.\n\n**Permiso:** `comprobantes:leer`. **Cobro:** No cobra.",
        "tags": [
          "Emisores"
        ],
        "security": [
          {
            "claveApi": []
          }
        ],
        "parameters": [
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "Cursor opaco que devolvió la página anterior en `siguiente_cursor`.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 512
            }
          },
          {
            "name": "limite",
            "in": "query",
            "required": false,
            "description": "Cuántos elementos traer (1 a 100; por defecto 20).",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100
            }
          },
          {
            "$ref": "#/components/parameters/RequestId"
          }
        ],
        "responses": {
          "200": {
            "description": "Página de emisores.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ListaEmisores"
                }
              }
            }
          },
          "400": {
            "description": "`validacion`: Algún dato no cumple el formato. En `detalle` va cada campo con su problema.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "validacion": {
                    "$ref": "#/components/examples/validacion"
                  }
                }
              }
            }
          },
          "401": {
            "description": "`clave_invalida`: Falta la clave de API, está mal escrita, venció o fue revocada. Envíala como `Authorization: Bearer onx_live_…`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "clave_invalida": {
                    "$ref": "#/components/examples/clave_invalida"
                  }
                }
              }
            }
          },
          "403": {
            "description": "`permiso_faltante`: La clave no tiene el permiso que pide esta ruta o no tiene acceso a ese RUC.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "permiso_faltante": {
                    "$ref": "#/components/examples/permiso_faltante"
                  }
                }
              }
            }
          },
          "429": {
            "description": "`limite_uso`: Hiciste demasiadas peticiones seguidas. Espera los segundos que indica `Retry-After` y vuelve a intentar.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "limite_uso": {
                    "$ref": "#/components/examples/limite_uso"
                  }
                }
              }
            }
          },
          "500": {
            "description": "`error_interno`: Algo falló de nuestro lado. Repite la petición con la misma `Idempotency-Key`: no se duplica nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "error_interno": {
                    "$ref": "#/components/examples/error_interno"
                  }
                }
              }
            }
          },
          "501": {
            "description": "`operacion_no_disponible`: Esta operación existe en el contrato, pero todavía no está habilitada. Revisa en la documentación qué rutas ya puedes usar; no se cobró nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "operacion_no_disponible": {
                    "$ref": "#/components/examples/operacion_no_disponible"
                  }
                }
              }
            }
          },
          "503": {
            "description": "`no_disponible`: El dato todavía se está cargando o actualizando de nuestro lado. Vuelve a intentar después de los segundos que indica `Retry-After`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "no_disponible": {
                    "$ref": "#/components/examples/no_disponible"
                  }
                }
              }
            }
          }
        },
        "x-nexum": {
          "permiso": "comprobantes:leer",
          "cobro": "no",
          "puede_pedir_confirmacion": false,
          "confirmacion_obligatoria": false,
          "acepta_credenciales": false,
          "idempotencia": "no_aplica",
          "herramienta_mcp": "emisor_listar"
        }
      }
    },
    "/v1/emisores/{ruc}": {
      "get": {
        "operationId": "emisor_ver",
        "summary": "Consulta un RUC emisor",
        "description": "Datos del emisor, entorno y modo de credenciales.\n\n**Permiso:** `comprobantes:leer`. **Cobro:** No cobra.",
        "tags": [
          "Emisores"
        ],
        "security": [
          {
            "claveApi": []
          }
        ],
        "parameters": [
          {
            "name": "ruc",
            "in": "path",
            "required": true,
            "description": "RUC del emisor o contribuyente.",
            "schema": {
              "type": "string",
              "pattern": "^(10|15|16|17|20)\\d{9}$",
              "examples": [
                "20000000001"
              ]
            }
          },
          {
            "$ref": "#/components/parameters/RequestId"
          }
        ],
        "responses": {
          "200": {
            "description": "Emisor.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Emisor"
                }
              }
            }
          },
          "400": {
            "description": "`validacion`: Algún dato no cumple el formato. En `detalle` va cada campo con su problema.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "validacion": {
                    "$ref": "#/components/examples/validacion"
                  }
                }
              }
            }
          },
          "401": {
            "description": "`clave_invalida`: Falta la clave de API, está mal escrita, venció o fue revocada. Envíala como `Authorization: Bearer onx_live_…`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "clave_invalida": {
                    "$ref": "#/components/examples/clave_invalida"
                  }
                }
              }
            }
          },
          "403": {
            "description": "`permiso_faltante`: La clave no tiene el permiso que pide esta ruta o no tiene acceso a ese RUC.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "permiso_faltante": {
                    "$ref": "#/components/examples/permiso_faltante"
                  }
                }
              }
            }
          },
          "404": {
            "description": "`no_encontrado`: No existe o no pertenece a tu cuenta.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "no_encontrado": {
                    "$ref": "#/components/examples/no_encontrado"
                  }
                }
              }
            }
          },
          "429": {
            "description": "`limite_uso`: Hiciste demasiadas peticiones seguidas. Espera los segundos que indica `Retry-After` y vuelve a intentar.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "limite_uso": {
                    "$ref": "#/components/examples/limite_uso"
                  }
                }
              }
            }
          },
          "500": {
            "description": "`error_interno`: Algo falló de nuestro lado. Repite la petición con la misma `Idempotency-Key`: no se duplica nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "error_interno": {
                    "$ref": "#/components/examples/error_interno"
                  }
                }
              }
            }
          },
          "501": {
            "description": "`operacion_no_disponible`: Esta operación existe en el contrato, pero todavía no está habilitada. Revisa en la documentación qué rutas ya puedes usar; no se cobró nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "operacion_no_disponible": {
                    "$ref": "#/components/examples/operacion_no_disponible"
                  }
                }
              }
            }
          },
          "503": {
            "description": "`no_disponible`: El dato todavía se está cargando o actualizando de nuestro lado. Vuelve a intentar después de los segundos que indica `Retry-After`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "no_disponible": {
                    "$ref": "#/components/examples/no_disponible"
                  }
                }
              }
            }
          }
        },
        "x-nexum": {
          "permiso": "comprobantes:leer",
          "cobro": "no",
          "puede_pedir_confirmacion": false,
          "confirmacion_obligatoria": false,
          "acepta_credenciales": false,
          "idempotencia": "no_aplica",
          "herramienta_mcp": "emisor_ver"
        }
      }
    },
    "/v1/emisores/{ruc}/credenciales": {
      "put": {
        "operationId": "credenciales_guardar",
        "summary": "Guarda credenciales en la bóveda",
        "description": "Guarda el certificado y el usuario SOL secundario cifrados. Solo funciona con la bóveda activa; mientras tanto responde `boveda_inactiva` y debes enviar `credenciales` en cada llamada. No se expone a agentes por MCP: un certificado no debe pasar por el chat.\n\n**Permiso:** `emisores:administrar`. **Cobro:** No cobra.",
        "tags": [
          "Emisores"
        ],
        "security": [
          {
            "claveApi": []
          }
        ],
        "parameters": [
          {
            "name": "ruc",
            "in": "path",
            "required": true,
            "description": "RUC del emisor o contribuyente.",
            "schema": {
              "type": "string",
              "pattern": "^(10|15|16|17|20)\\d{9}$",
              "examples": [
                "20000000001"
              ]
            }
          },
          {
            "$ref": "#/components/parameters/RequestId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/GuardarCredenciales"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Credenciales guardadas (sin datos secretos).",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EstadoCredenciales"
                }
              }
            }
          },
          "400": {
            "description": "`validacion`: Algún dato no cumple el formato. En `detalle` va cada campo con su problema.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "validacion": {
                    "$ref": "#/components/examples/validacion"
                  }
                }
              }
            }
          },
          "401": {
            "description": "`clave_invalida`: Falta la clave de API, está mal escrita, venció o fue revocada. Envíala como `Authorization: Bearer onx_live_…`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "clave_invalida": {
                    "$ref": "#/components/examples/clave_invalida"
                  }
                }
              }
            }
          },
          "403": {
            "description": "`permiso_faltante`: La clave no tiene el permiso que pide esta ruta o no tiene acceso a ese RUC.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "permiso_faltante": {
                    "$ref": "#/components/examples/permiso_faltante"
                  }
                }
              }
            }
          },
          "404": {
            "description": "`no_encontrado`: No existe o no pertenece a tu cuenta.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "no_encontrado": {
                    "$ref": "#/components/examples/no_encontrado"
                  }
                }
              }
            }
          },
          "409": {
            "description": "`boveda_inactiva`: La bóveda de credenciales todavía no está activa. Envía `credenciales` en cada llamada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "boveda_inactiva": {
                    "$ref": "#/components/examples/boveda_inactiva"
                  }
                }
              }
            }
          },
          "422": {
            "description": "`credenciales_sunat`: SUNAT no aceptó el certificado o el usuario SOL, o el certificado es de otro RUC.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "credenciales_sunat": {
                    "$ref": "#/components/examples/credenciales_sunat"
                  }
                }
              }
            }
          },
          "429": {
            "description": "`limite_uso`: Hiciste demasiadas peticiones seguidas. Espera los segundos que indica `Retry-After` y vuelve a intentar.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "limite_uso": {
                    "$ref": "#/components/examples/limite_uso"
                  }
                }
              }
            }
          },
          "500": {
            "description": "`error_interno`: Algo falló de nuestro lado. Repite la petición con la misma `Idempotency-Key`: no se duplica nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "error_interno": {
                    "$ref": "#/components/examples/error_interno"
                  }
                }
              }
            }
          },
          "501": {
            "description": "`operacion_no_disponible`: Esta operación existe en el contrato, pero todavía no está habilitada. Revisa en la documentación qué rutas ya puedes usar; no se cobró nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "operacion_no_disponible": {
                    "$ref": "#/components/examples/operacion_no_disponible"
                  }
                }
              }
            }
          },
          "503": {
            "description": "`no_disponible`: El dato todavía se está cargando o actualizando de nuestro lado. Vuelve a intentar después de los segundos que indica `Retry-After`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "no_disponible": {
                    "$ref": "#/components/examples/no_disponible"
                  }
                }
              }
            }
          }
        },
        "x-nexum": {
          "permiso": "emisores:administrar",
          "cobro": "no",
          "puede_pedir_confirmacion": false,
          "confirmacion_obligatoria": false,
          "acepta_credenciales": false,
          "idempotencia": "no_aplica",
          "herramienta_mcp": null
        }
      }
    },
    "/v1/emisores/{ruc}/series": {
      "get": {
        "operationId": "serie_listar",
        "summary": "Lista las series de un emisor",
        "description": "Series registradas y el último número asignado en cada una.\n\n**Permiso:** `comprobantes:leer`. **Cobro:** No cobra.",
        "tags": [
          "Emisores"
        ],
        "security": [
          {
            "claveApi": []
          }
        ],
        "parameters": [
          {
            "name": "ruc",
            "in": "path",
            "required": true,
            "description": "RUC del emisor o contribuyente.",
            "schema": {
              "type": "string",
              "pattern": "^(10|15|16|17|20)\\d{9}$",
              "examples": [
                "20000000001"
              ]
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "Cursor opaco que devolvió la página anterior en `siguiente_cursor`.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 512
            }
          },
          {
            "name": "limite",
            "in": "query",
            "required": false,
            "description": "Cuántos elementos traer (1 a 100; por defecto 20).",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100
            }
          },
          {
            "$ref": "#/components/parameters/RequestId"
          }
        ],
        "responses": {
          "200": {
            "description": "Página de series.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ListaSeries"
                }
              }
            }
          },
          "400": {
            "description": "`validacion`: Algún dato no cumple el formato. En `detalle` va cada campo con su problema.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "validacion": {
                    "$ref": "#/components/examples/validacion"
                  }
                }
              }
            }
          },
          "401": {
            "description": "`clave_invalida`: Falta la clave de API, está mal escrita, venció o fue revocada. Envíala como `Authorization: Bearer onx_live_…`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "clave_invalida": {
                    "$ref": "#/components/examples/clave_invalida"
                  }
                }
              }
            }
          },
          "403": {
            "description": "`permiso_faltante`: La clave no tiene el permiso que pide esta ruta o no tiene acceso a ese RUC.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "permiso_faltante": {
                    "$ref": "#/components/examples/permiso_faltante"
                  }
                }
              }
            }
          },
          "404": {
            "description": "`no_encontrado`: No existe o no pertenece a tu cuenta.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "no_encontrado": {
                    "$ref": "#/components/examples/no_encontrado"
                  }
                }
              }
            }
          },
          "429": {
            "description": "`limite_uso`: Hiciste demasiadas peticiones seguidas. Espera los segundos que indica `Retry-After` y vuelve a intentar.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "limite_uso": {
                    "$ref": "#/components/examples/limite_uso"
                  }
                }
              }
            }
          },
          "500": {
            "description": "`error_interno`: Algo falló de nuestro lado. Repite la petición con la misma `Idempotency-Key`: no se duplica nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "error_interno": {
                    "$ref": "#/components/examples/error_interno"
                  }
                }
              }
            }
          },
          "501": {
            "description": "`operacion_no_disponible`: Esta operación existe en el contrato, pero todavía no está habilitada. Revisa en la documentación qué rutas ya puedes usar; no se cobró nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "operacion_no_disponible": {
                    "$ref": "#/components/examples/operacion_no_disponible"
                  }
                }
              }
            }
          },
          "503": {
            "description": "`no_disponible`: El dato todavía se está cargando o actualizando de nuestro lado. Vuelve a intentar después de los segundos que indica `Retry-After`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "no_disponible": {
                    "$ref": "#/components/examples/no_disponible"
                  }
                }
              }
            }
          }
        },
        "x-nexum": {
          "permiso": "comprobantes:leer",
          "cobro": "no",
          "puede_pedir_confirmacion": false,
          "confirmacion_obligatoria": false,
          "acepta_credenciales": false,
          "idempotencia": "no_aplica",
          "herramienta_mcp": "serie_listar"
        }
      },
      "post": {
        "operationId": "serie_crear",
        "summary": "Crea una serie",
        "description": "Registra una serie (F001, B001, T001…). Si vienes de otro sistema, indica el último número usado.\n\n**Permiso:** `emisores:administrar`. **Cobro:** No cobra.",
        "tags": [
          "Emisores"
        ],
        "security": [
          {
            "claveApi": []
          }
        ],
        "parameters": [
          {
            "name": "ruc",
            "in": "path",
            "required": true,
            "description": "RUC del emisor o contribuyente.",
            "schema": {
              "type": "string",
              "pattern": "^(10|15|16|17|20)\\d{9}$",
              "examples": [
                "20000000001"
              ]
            }
          },
          {
            "$ref": "#/components/parameters/IdempotencyKeyOpcional"
          },
          {
            "$ref": "#/components/parameters/RequestId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CrearSerie"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Serie creada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Serie"
                }
              }
            }
          },
          "400": {
            "description": "`validacion`: Algún dato no cumple el formato. En `detalle` va cada campo con su problema.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "validacion": {
                    "$ref": "#/components/examples/validacion"
                  }
                }
              }
            }
          },
          "401": {
            "description": "`clave_invalida`: Falta la clave de API, está mal escrita, venció o fue revocada. Envíala como `Authorization: Bearer onx_live_…`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "clave_invalida": {
                    "$ref": "#/components/examples/clave_invalida"
                  }
                }
              }
            }
          },
          "403": {
            "description": "`permiso_faltante`: La clave no tiene el permiso que pide esta ruta o no tiene acceso a ese RUC.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "permiso_faltante": {
                    "$ref": "#/components/examples/permiso_faltante"
                  }
                }
              }
            }
          },
          "404": {
            "description": "`no_encontrado`: No existe o no pertenece a tu cuenta.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "no_encontrado": {
                    "$ref": "#/components/examples/no_encontrado"
                  }
                }
              }
            }
          },
          "409": {
            "description": "`idempotencia_en_conflicto`: Usaste la misma `Idempotency-Key` con otro cuerpo. Genera una clave nueva para cada operación distinta.\n\n`solicitud_en_curso`: Ya estamos procesando una petición con esa `Idempotency-Key`. Espera unos segundos y vuelve a consultar.\n\n`ya_registrado`: Eso ya está registrado: por ejemplo, el RUC ya está en otra cuenta o la serie ya existe.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "idempotencia_en_conflicto": {
                    "$ref": "#/components/examples/idempotencia_en_conflicto"
                  },
                  "solicitud_en_curso": {
                    "$ref": "#/components/examples/solicitud_en_curso"
                  },
                  "ya_registrado": {
                    "$ref": "#/components/examples/ya_registrado"
                  }
                }
              }
            }
          },
          "429": {
            "description": "`limite_uso`: Hiciste demasiadas peticiones seguidas. Espera los segundos que indica `Retry-After` y vuelve a intentar.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "limite_uso": {
                    "$ref": "#/components/examples/limite_uso"
                  }
                }
              }
            }
          },
          "500": {
            "description": "`error_interno`: Algo falló de nuestro lado. Repite la petición con la misma `Idempotency-Key`: no se duplica nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "error_interno": {
                    "$ref": "#/components/examples/error_interno"
                  }
                }
              }
            }
          },
          "501": {
            "description": "`operacion_no_disponible`: Esta operación existe en el contrato, pero todavía no está habilitada. Revisa en la documentación qué rutas ya puedes usar; no se cobró nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "operacion_no_disponible": {
                    "$ref": "#/components/examples/operacion_no_disponible"
                  }
                }
              }
            }
          },
          "503": {
            "description": "`no_disponible`: El dato todavía se está cargando o actualizando de nuestro lado. Vuelve a intentar después de los segundos que indica `Retry-After`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "no_disponible": {
                    "$ref": "#/components/examples/no_disponible"
                  }
                }
              }
            }
          }
        },
        "x-nexum": {
          "permiso": "emisores:administrar",
          "cobro": "no",
          "puede_pedir_confirmacion": false,
          "confirmacion_obligatoria": false,
          "acepta_credenciales": false,
          "idempotencia": "opcional",
          "herramienta_mcp": "serie_crear"
        }
      }
    },
    "/v1/emisores/{ruc}/resumenes": {
      "post": {
        "operationId": "resumen_crear",
        "summary": "Envía el resumen diario de boletas",
        "description": "Arma el resumen diario con las boletas del día que faltan informar y lo envía a SUNAT. Es asíncrono: consulta el resumen con su `id`.\n\n**Permiso:** `comprobantes:emitir`. **Cobro:** No cobra.\n\n**Idempotency-Key:** obligatoria.\n\nSi envías `credenciales`, la clave necesita además `credenciales:por_llamada`.",
        "tags": [
          "Resúmenes"
        ],
        "security": [
          {
            "claveApi": []
          }
        ],
        "parameters": [
          {
            "name": "ruc",
            "in": "path",
            "required": true,
            "description": "RUC del emisor o contribuyente.",
            "schema": {
              "type": "string",
              "pattern": "^(10|15|16|17|20)\\d{9}$",
              "examples": [
                "20000000001"
              ]
            }
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "$ref": "#/components/parameters/RequestId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CrearResumen"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Resumen en cola.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RespuestaEnCola"
                }
              }
            }
          },
          "400": {
            "description": "`validacion`: Algún dato no cumple el formato. En `detalle` va cada campo con su problema.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "validacion": {
                    "$ref": "#/components/examples/validacion"
                  }
                }
              }
            }
          },
          "401": {
            "description": "`clave_invalida`: Falta la clave de API, está mal escrita, venció o fue revocada. Envíala como `Authorization: Bearer onx_live_…`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "clave_invalida": {
                    "$ref": "#/components/examples/clave_invalida"
                  }
                }
              }
            }
          },
          "403": {
            "description": "`permiso_faltante`: La clave no tiene el permiso que pide esta ruta o no tiene acceso a ese RUC.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "permiso_faltante": {
                    "$ref": "#/components/examples/permiso_faltante"
                  }
                }
              }
            }
          },
          "404": {
            "description": "`no_encontrado`: No existe o no pertenece a tu cuenta.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "no_encontrado": {
                    "$ref": "#/components/examples/no_encontrado"
                  }
                }
              }
            }
          },
          "409": {
            "description": "`idempotencia_en_conflicto`: Usaste la misma `Idempotency-Key` con otro cuerpo. Genera una clave nueva para cada operación distinta.\n\n`solicitud_en_curso`: Ya estamos procesando una petición con esa `Idempotency-Key`. Espera unos segundos y vuelve a consultar.\n\n`boveda_inactiva`: La bóveda de credenciales todavía no está activa. Envía `credenciales` en cada llamada.\n\n`plazo_vencido`: Pasó el plazo que da SUNAT para esta operación. Para anular una factura fuera de plazo, emite una nota de crédito.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "idempotencia_en_conflicto": {
                    "$ref": "#/components/examples/idempotencia_en_conflicto"
                  },
                  "solicitud_en_curso": {
                    "$ref": "#/components/examples/solicitud_en_curso"
                  },
                  "boveda_inactiva": {
                    "$ref": "#/components/examples/boveda_inactiva"
                  },
                  "plazo_vencido": {
                    "$ref": "#/components/examples/plazo_vencido"
                  }
                }
              }
            }
          },
          "422": {
            "description": "`credenciales_sunat`: SUNAT no aceptó el certificado o el usuario SOL, o el certificado es de otro RUC.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "credenciales_sunat": {
                    "$ref": "#/components/examples/credenciales_sunat"
                  }
                }
              }
            }
          },
          "429": {
            "description": "`limite_uso`: Hiciste demasiadas peticiones seguidas. Espera los segundos que indica `Retry-After` y vuelve a intentar.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "limite_uso": {
                    "$ref": "#/components/examples/limite_uso"
                  }
                }
              }
            }
          },
          "500": {
            "description": "`error_interno`: Algo falló de nuestro lado. Repite la petición con la misma `Idempotency-Key`: no se duplica nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "error_interno": {
                    "$ref": "#/components/examples/error_interno"
                  }
                }
              }
            }
          },
          "501": {
            "description": "`operacion_no_disponible`: Esta operación existe en el contrato, pero todavía no está habilitada. Revisa en la documentación qué rutas ya puedes usar; no se cobró nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "operacion_no_disponible": {
                    "$ref": "#/components/examples/operacion_no_disponible"
                  }
                }
              }
            }
          },
          "503": {
            "description": "`no_disponible`: El dato todavía se está cargando o actualizando de nuestro lado. Vuelve a intentar después de los segundos que indica `Retry-After`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "no_disponible": {
                    "$ref": "#/components/examples/no_disponible"
                  }
                }
              }
            }
          }
        },
        "x-nexum": {
          "permiso": "comprobantes:emitir",
          "cobro": "no",
          "puede_pedir_confirmacion": false,
          "confirmacion_obligatoria": false,
          "acepta_credenciales": true,
          "idempotencia": "requerida",
          "herramienta_mcp": "resumen_crear"
        }
      },
      "get": {
        "operationId": "resumen_listar",
        "summary": "Lista resúmenes y comunicaciones de baja",
        "description": "Resúmenes diarios (RC) y comunicaciones de baja (RA) del emisor, con su estado en SUNAT.\n\n**Permiso:** `comprobantes:leer`. **Cobro:** No cobra.",
        "tags": [
          "Resúmenes"
        ],
        "security": [
          {
            "claveApi": []
          }
        ],
        "parameters": [
          {
            "name": "ruc",
            "in": "path",
            "required": true,
            "description": "RUC del emisor o contribuyente.",
            "schema": {
              "type": "string",
              "pattern": "^(10|15|16|17|20)\\d{9}$",
              "examples": [
                "20000000001"
              ]
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "Cursor opaco que devolvió la página anterior en `siguiente_cursor`.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 512
            }
          },
          {
            "name": "limite",
            "in": "query",
            "required": false,
            "description": "Cuántos elementos traer (1 a 100; por defecto 20).",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100
            }
          },
          {
            "name": "desde",
            "in": "query",
            "required": false,
            "description": "Fecha AAAA-MM-DD (día en Lima).",
            "schema": {
              "type": "string",
              "format": "date",
              "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$",
              "examples": [
                "2026-11-15"
              ]
            }
          },
          {
            "name": "hasta",
            "in": "query",
            "required": false,
            "description": "Fecha AAAA-MM-DD (día en Lima).",
            "schema": {
              "type": "string",
              "format": "date",
              "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$",
              "examples": [
                "2026-11-15"
              ]
            }
          },
          {
            "$ref": "#/components/parameters/RequestId"
          }
        ],
        "responses": {
          "200": {
            "description": "Página de resúmenes.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ListaResumenes"
                }
              }
            }
          },
          "400": {
            "description": "`validacion`: Algún dato no cumple el formato. En `detalle` va cada campo con su problema.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "validacion": {
                    "$ref": "#/components/examples/validacion"
                  }
                }
              }
            }
          },
          "401": {
            "description": "`clave_invalida`: Falta la clave de API, está mal escrita, venció o fue revocada. Envíala como `Authorization: Bearer onx_live_…`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "clave_invalida": {
                    "$ref": "#/components/examples/clave_invalida"
                  }
                }
              }
            }
          },
          "403": {
            "description": "`permiso_faltante`: La clave no tiene el permiso que pide esta ruta o no tiene acceso a ese RUC.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "permiso_faltante": {
                    "$ref": "#/components/examples/permiso_faltante"
                  }
                }
              }
            }
          },
          "404": {
            "description": "`no_encontrado`: No existe o no pertenece a tu cuenta.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "no_encontrado": {
                    "$ref": "#/components/examples/no_encontrado"
                  }
                }
              }
            }
          },
          "429": {
            "description": "`limite_uso`: Hiciste demasiadas peticiones seguidas. Espera los segundos que indica `Retry-After` y vuelve a intentar.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "limite_uso": {
                    "$ref": "#/components/examples/limite_uso"
                  }
                }
              }
            }
          },
          "500": {
            "description": "`error_interno`: Algo falló de nuestro lado. Repite la petición con la misma `Idempotency-Key`: no se duplica nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "error_interno": {
                    "$ref": "#/components/examples/error_interno"
                  }
                }
              }
            }
          },
          "501": {
            "description": "`operacion_no_disponible`: Esta operación existe en el contrato, pero todavía no está habilitada. Revisa en la documentación qué rutas ya puedes usar; no se cobró nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "operacion_no_disponible": {
                    "$ref": "#/components/examples/operacion_no_disponible"
                  }
                }
              }
            }
          },
          "503": {
            "description": "`no_disponible`: El dato todavía se está cargando o actualizando de nuestro lado. Vuelve a intentar después de los segundos que indica `Retry-After`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "no_disponible": {
                    "$ref": "#/components/examples/no_disponible"
                  }
                }
              }
            }
          }
        },
        "x-nexum": {
          "permiso": "comprobantes:leer",
          "cobro": "no",
          "puede_pedir_confirmacion": false,
          "confirmacion_obligatoria": false,
          "acepta_credenciales": false,
          "idempotencia": "no_aplica",
          "herramienta_mcp": "resumen_listar"
        }
      }
    },
    "/v1/emisores/{ruc}/resumenes/{id}": {
      "get": {
        "operationId": "resumen_ver",
        "summary": "Consulta un resumen",
        "description": "Estado de un resumen diario o de una comunicación de baja, con el ticket y la respuesta de SUNAT.\n\n**Permiso:** `comprobantes:leer`. **Cobro:** No cobra.",
        "tags": [
          "Resúmenes"
        ],
        "security": [
          {
            "claveApi": []
          }
        ],
        "parameters": [
          {
            "name": "ruc",
            "in": "path",
            "required": true,
            "description": "RUC del emisor.",
            "schema": {
              "type": "string",
              "pattern": "^(10|15|16|17|20)\\d{9}$",
              "examples": [
                "20000000001"
              ]
            }
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Identificador que empieza con `res_`.",
            "schema": {
              "type": "string",
              "pattern": "^res_[A-Za-z0-9]{8,64}$",
              "examples": [
                "res_8f2c1a7d9e"
              ]
            }
          },
          {
            "$ref": "#/components/parameters/RequestId"
          }
        ],
        "responses": {
          "200": {
            "description": "Resumen.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Resumen"
                }
              }
            }
          },
          "400": {
            "description": "`validacion`: Algún dato no cumple el formato. En `detalle` va cada campo con su problema.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "validacion": {
                    "$ref": "#/components/examples/validacion"
                  }
                }
              }
            }
          },
          "401": {
            "description": "`clave_invalida`: Falta la clave de API, está mal escrita, venció o fue revocada. Envíala como `Authorization: Bearer onx_live_…`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "clave_invalida": {
                    "$ref": "#/components/examples/clave_invalida"
                  }
                }
              }
            }
          },
          "403": {
            "description": "`permiso_faltante`: La clave no tiene el permiso que pide esta ruta o no tiene acceso a ese RUC.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "permiso_faltante": {
                    "$ref": "#/components/examples/permiso_faltante"
                  }
                }
              }
            }
          },
          "404": {
            "description": "`no_encontrado`: No existe o no pertenece a tu cuenta.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "no_encontrado": {
                    "$ref": "#/components/examples/no_encontrado"
                  }
                }
              }
            }
          },
          "429": {
            "description": "`limite_uso`: Hiciste demasiadas peticiones seguidas. Espera los segundos que indica `Retry-After` y vuelve a intentar.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "limite_uso": {
                    "$ref": "#/components/examples/limite_uso"
                  }
                }
              }
            }
          },
          "500": {
            "description": "`error_interno`: Algo falló de nuestro lado. Repite la petición con la misma `Idempotency-Key`: no se duplica nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "error_interno": {
                    "$ref": "#/components/examples/error_interno"
                  }
                }
              }
            }
          },
          "501": {
            "description": "`operacion_no_disponible`: Esta operación existe en el contrato, pero todavía no está habilitada. Revisa en la documentación qué rutas ya puedes usar; no se cobró nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "operacion_no_disponible": {
                    "$ref": "#/components/examples/operacion_no_disponible"
                  }
                }
              }
            }
          },
          "503": {
            "description": "`no_disponible`: El dato todavía se está cargando o actualizando de nuestro lado. Vuelve a intentar después de los segundos que indica `Retry-After`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "no_disponible": {
                    "$ref": "#/components/examples/no_disponible"
                  }
                }
              }
            }
          }
        },
        "x-nexum": {
          "permiso": "comprobantes:leer",
          "cobro": "no",
          "puede_pedir_confirmacion": false,
          "confirmacion_obligatoria": false,
          "acepta_credenciales": false,
          "idempotencia": "no_aplica",
          "herramienta_mcp": "resumen_ver"
        }
      }
    },
    "/v1/emisores/{ruc}/guias": {
      "post": {
        "operationId": "guia_emitir",
        "summary": "Emite una guía de remisión remitente",
        "description": "Emite la guía (09) por la API de SUNAT. El número lo asigna el servidor. Reserva el precio y lo cobra solo si SUNAT la acepta; si SUNAT no responde, queda `en_cola`.\n\n**Permiso:** `guias:emitir`. **Cobro:** Reserva el precio del saldo y lo cobra solo si el servicio confirma.\n\n**Idempotency-Key:** obligatoria.\n\nSi envías `credenciales`, la clave necesita además `credenciales:por_llamada`.",
        "tags": [
          "Guías"
        ],
        "security": [
          {
            "claveApi": []
          }
        ],
        "parameters": [
          {
            "name": "ruc",
            "in": "path",
            "required": true,
            "description": "RUC del emisor o contribuyente.",
            "schema": {
              "type": "string",
              "pattern": "^(10|15|16|17|20)\\d{9}$",
              "examples": [
                "20000000001"
              ]
            }
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "$ref": "#/components/parameters/RequestId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EmitirGuia"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Guía aceptada por SUNAT.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Guia"
                }
              }
            }
          },
          "202": {
            "description": "Guía en cola.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RespuestaEnCola"
                }
              }
            }
          },
          "400": {
            "description": "`validacion`: Algún dato no cumple el formato. En `detalle` va cada campo con su problema.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "validacion": {
                    "$ref": "#/components/examples/validacion"
                  }
                }
              }
            }
          },
          "401": {
            "description": "`clave_invalida`: Falta la clave de API, está mal escrita, venció o fue revocada. Envíala como `Authorization: Bearer onx_live_…`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "clave_invalida": {
                    "$ref": "#/components/examples/clave_invalida"
                  }
                }
              }
            }
          },
          "402": {
            "description": "`saldo_insuficiente`: No te alcanza el saldo para esta operación. Pásale `recarga_url` a una persona de tu cuenta para que recargue.\n\n`tope_alcanzado`: La clave llegó a su tope de gasto del periodo. Una persona de tu cuenta puede subirlo desde el panel.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error402"
                },
                "examples": {
                  "saldo_insuficiente": {
                    "$ref": "#/components/examples/saldo_insuficiente"
                  },
                  "tope_alcanzado": {
                    "$ref": "#/components/examples/tope_alcanzado"
                  }
                }
              }
            }
          },
          "403": {
            "description": "`permiso_faltante`: La clave no tiene el permiso que pide esta ruta o no tiene acceso a ese RUC.\n\n`emisor_obligado_ose`: Ese RUC figura en el padrón de obligados a emitir mediante un OSE; por ahora no podemos emitir por él.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "permiso_faltante": {
                    "$ref": "#/components/examples/permiso_faltante"
                  },
                  "emisor_obligado_ose": {
                    "$ref": "#/components/examples/emisor_obligado_ose"
                  }
                }
              }
            }
          },
          "404": {
            "description": "`no_encontrado`: No existe o no pertenece a tu cuenta.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "no_encontrado": {
                    "$ref": "#/components/examples/no_encontrado"
                  }
                }
              }
            }
          },
          "409": {
            "description": "`idempotencia_en_conflicto`: Usaste la misma `Idempotency-Key` con otro cuerpo. Genera una clave nueva para cada operación distinta.\n\n`solicitud_en_curso`: Ya estamos procesando una petición con esa `Idempotency-Key`. Espera unos segundos y vuelve a consultar.\n\n`boveda_inactiva`: La bóveda de credenciales todavía no está activa. Envía `credenciales` en cada llamada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "idempotencia_en_conflicto": {
                    "$ref": "#/components/examples/idempotencia_en_conflicto"
                  },
                  "solicitud_en_curso": {
                    "$ref": "#/components/examples/solicitud_en_curso"
                  },
                  "boveda_inactiva": {
                    "$ref": "#/components/examples/boveda_inactiva"
                  }
                }
              }
            }
          },
          "422": {
            "description": "`sunat_rechazo`: SUNAT rechazó el comprobante. En `detalle` van el código y la descripción que dio SUNAT.\n\n`credenciales_sunat`: SUNAT no aceptó el certificado o el usuario SOL, o el certificado es de otro RUC.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "sunat_rechazo": {
                    "$ref": "#/components/examples/sunat_rechazo"
                  },
                  "credenciales_sunat": {
                    "$ref": "#/components/examples/credenciales_sunat"
                  }
                }
              }
            }
          },
          "429": {
            "description": "`limite_uso`: Hiciste demasiadas peticiones seguidas. Espera los segundos que indica `Retry-After` y vuelve a intentar.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "limite_uso": {
                    "$ref": "#/components/examples/limite_uso"
                  }
                }
              }
            }
          },
          "500": {
            "description": "`error_interno`: Algo falló de nuestro lado. Repite la petición con la misma `Idempotency-Key`: no se duplica nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "error_interno": {
                    "$ref": "#/components/examples/error_interno"
                  }
                }
              }
            }
          },
          "501": {
            "description": "`operacion_no_disponible`: Esta operación existe en el contrato, pero todavía no está habilitada. Revisa en la documentación qué rutas ya puedes usar; no se cobró nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "operacion_no_disponible": {
                    "$ref": "#/components/examples/operacion_no_disponible"
                  }
                }
              }
            }
          },
          "503": {
            "description": "`no_disponible`: El dato todavía se está cargando o actualizando de nuestro lado. Vuelve a intentar después de los segundos que indica `Retry-After`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "no_disponible": {
                    "$ref": "#/components/examples/no_disponible"
                  }
                }
              }
            }
          }
        },
        "x-nexum": {
          "permiso": "guias:emitir",
          "cobro": "reserva",
          "puede_pedir_confirmacion": false,
          "confirmacion_obligatoria": false,
          "acepta_credenciales": true,
          "idempotencia": "requerida",
          "herramienta_mcp": "guia_emitir"
        }
      },
      "get": {
        "operationId": "guia_listar",
        "summary": "Lista guías de un emisor",
        "description": "Guías de remisión del emisor, de la más reciente a la más antigua.\n\n**Permiso:** `comprobantes:leer`. **Cobro:** No cobra.",
        "tags": [
          "Guías"
        ],
        "security": [
          {
            "claveApi": []
          }
        ],
        "parameters": [
          {
            "name": "ruc",
            "in": "path",
            "required": true,
            "description": "RUC del emisor o contribuyente.",
            "schema": {
              "type": "string",
              "pattern": "^(10|15|16|17|20)\\d{9}$",
              "examples": [
                "20000000001"
              ]
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "Cursor opaco que devolvió la página anterior en `siguiente_cursor`.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 512
            }
          },
          {
            "name": "limite",
            "in": "query",
            "required": false,
            "description": "Cuántos elementos traer (1 a 100; por defecto 20).",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100
            }
          },
          {
            "$ref": "#/components/parameters/RequestId"
          }
        ],
        "responses": {
          "200": {
            "description": "Página de guías.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ListaGuias"
                }
              }
            }
          },
          "400": {
            "description": "`validacion`: Algún dato no cumple el formato. En `detalle` va cada campo con su problema.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "validacion": {
                    "$ref": "#/components/examples/validacion"
                  }
                }
              }
            }
          },
          "401": {
            "description": "`clave_invalida`: Falta la clave de API, está mal escrita, venció o fue revocada. Envíala como `Authorization: Bearer onx_live_…`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "clave_invalida": {
                    "$ref": "#/components/examples/clave_invalida"
                  }
                }
              }
            }
          },
          "403": {
            "description": "`permiso_faltante`: La clave no tiene el permiso que pide esta ruta o no tiene acceso a ese RUC.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "permiso_faltante": {
                    "$ref": "#/components/examples/permiso_faltante"
                  }
                }
              }
            }
          },
          "404": {
            "description": "`no_encontrado`: No existe o no pertenece a tu cuenta.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "no_encontrado": {
                    "$ref": "#/components/examples/no_encontrado"
                  }
                }
              }
            }
          },
          "429": {
            "description": "`limite_uso`: Hiciste demasiadas peticiones seguidas. Espera los segundos que indica `Retry-After` y vuelve a intentar.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "limite_uso": {
                    "$ref": "#/components/examples/limite_uso"
                  }
                }
              }
            }
          },
          "500": {
            "description": "`error_interno`: Algo falló de nuestro lado. Repite la petición con la misma `Idempotency-Key`: no se duplica nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "error_interno": {
                    "$ref": "#/components/examples/error_interno"
                  }
                }
              }
            }
          },
          "501": {
            "description": "`operacion_no_disponible`: Esta operación existe en el contrato, pero todavía no está habilitada. Revisa en la documentación qué rutas ya puedes usar; no se cobró nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "operacion_no_disponible": {
                    "$ref": "#/components/examples/operacion_no_disponible"
                  }
                }
              }
            }
          },
          "503": {
            "description": "`no_disponible`: El dato todavía se está cargando o actualizando de nuestro lado. Vuelve a intentar después de los segundos que indica `Retry-After`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "no_disponible": {
                    "$ref": "#/components/examples/no_disponible"
                  }
                }
              }
            }
          }
        },
        "x-nexum": {
          "permiso": "comprobantes:leer",
          "cobro": "no",
          "puede_pedir_confirmacion": false,
          "confirmacion_obligatoria": false,
          "acepta_credenciales": false,
          "idempotencia": "no_aplica",
          "herramienta_mcp": "guia_listar"
        }
      }
    },
    "/v1/emisores/{ruc}/guias/{id}": {
      "get": {
        "operationId": "guia_ver",
        "summary": "Consulta una guía",
        "description": "Detalle y estado ante SUNAT de una guía de remisión.\n\n**Permiso:** `comprobantes:leer`. **Cobro:** No cobra.",
        "tags": [
          "Guías"
        ],
        "security": [
          {
            "claveApi": []
          }
        ],
        "parameters": [
          {
            "name": "ruc",
            "in": "path",
            "required": true,
            "description": "RUC del emisor.",
            "schema": {
              "type": "string",
              "pattern": "^(10|15|16|17|20)\\d{9}$",
              "examples": [
                "20000000001"
              ]
            }
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Identificador que empieza con `gre_`.",
            "schema": {
              "type": "string",
              "pattern": "^gre_[A-Za-z0-9]{8,64}$",
              "examples": [
                "gre_8f2c1a7d9e"
              ]
            }
          },
          {
            "$ref": "#/components/parameters/RequestId"
          }
        ],
        "responses": {
          "200": {
            "description": "Guía.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Guia"
                }
              }
            }
          },
          "400": {
            "description": "`validacion`: Algún dato no cumple el formato. En `detalle` va cada campo con su problema.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "validacion": {
                    "$ref": "#/components/examples/validacion"
                  }
                }
              }
            }
          },
          "401": {
            "description": "`clave_invalida`: Falta la clave de API, está mal escrita, venció o fue revocada. Envíala como `Authorization: Bearer onx_live_…`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "clave_invalida": {
                    "$ref": "#/components/examples/clave_invalida"
                  }
                }
              }
            }
          },
          "403": {
            "description": "`permiso_faltante`: La clave no tiene el permiso que pide esta ruta o no tiene acceso a ese RUC.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "permiso_faltante": {
                    "$ref": "#/components/examples/permiso_faltante"
                  }
                }
              }
            }
          },
          "404": {
            "description": "`no_encontrado`: No existe o no pertenece a tu cuenta.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "no_encontrado": {
                    "$ref": "#/components/examples/no_encontrado"
                  }
                }
              }
            }
          },
          "429": {
            "description": "`limite_uso`: Hiciste demasiadas peticiones seguidas. Espera los segundos que indica `Retry-After` y vuelve a intentar.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "limite_uso": {
                    "$ref": "#/components/examples/limite_uso"
                  }
                }
              }
            }
          },
          "500": {
            "description": "`error_interno`: Algo falló de nuestro lado. Repite la petición con la misma `Idempotency-Key`: no se duplica nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "error_interno": {
                    "$ref": "#/components/examples/error_interno"
                  }
                }
              }
            }
          },
          "501": {
            "description": "`operacion_no_disponible`: Esta operación existe en el contrato, pero todavía no está habilitada. Revisa en la documentación qué rutas ya puedes usar; no se cobró nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "operacion_no_disponible": {
                    "$ref": "#/components/examples/operacion_no_disponible"
                  }
                }
              }
            }
          },
          "503": {
            "description": "`no_disponible`: El dato todavía se está cargando o actualizando de nuestro lado. Vuelve a intentar después de los segundos que indica `Retry-After`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "no_disponible": {
                    "$ref": "#/components/examples/no_disponible"
                  }
                }
              }
            }
          }
        },
        "x-nexum": {
          "permiso": "comprobantes:leer",
          "cobro": "no",
          "puede_pedir_confirmacion": false,
          "confirmacion_obligatoria": false,
          "acepta_credenciales": false,
          "idempotencia": "no_aplica",
          "herramienta_mcp": "guia_ver"
        }
      }
    },
    "/v1/emisores/{ruc}/sire/propuestas": {
      "post": {
        "operationId": "sire_propuesta_pedir",
        "summary": "Pide la propuesta del SIRE de un periodo",
        "description": "Pide a SUNAT la propuesta del RVIE (ventas) o del RCE (compras). SUNAT la prepara en segundo plano: responde 202 y consultas el resultado con el `id`.\n\n**Permiso:** `sire:leer`. **Cobro:** Reserva el precio del saldo y lo cobra solo si el servicio confirma.\n\n**Idempotency-Key:** obligatoria.\n\nSi envías `credenciales`, la clave necesita además `credenciales:por_llamada`.",
        "tags": [
          "SIRE"
        ],
        "security": [
          {
            "claveApi": []
          }
        ],
        "parameters": [
          {
            "name": "ruc",
            "in": "path",
            "required": true,
            "description": "RUC del emisor o contribuyente.",
            "schema": {
              "type": "string",
              "pattern": "^(10|15|16|17|20)\\d{9}$",
              "examples": [
                "20000000001"
              ]
            }
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "$ref": "#/components/parameters/RequestId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PedirPropuestaSire"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Propuesta en cola.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RespuestaEnCola"
                }
              }
            }
          },
          "400": {
            "description": "`validacion`: Algún dato no cumple el formato. En `detalle` va cada campo con su problema.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "validacion": {
                    "$ref": "#/components/examples/validacion"
                  }
                }
              }
            }
          },
          "401": {
            "description": "`clave_invalida`: Falta la clave de API, está mal escrita, venció o fue revocada. Envíala como `Authorization: Bearer onx_live_…`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "clave_invalida": {
                    "$ref": "#/components/examples/clave_invalida"
                  }
                }
              }
            }
          },
          "402": {
            "description": "`saldo_insuficiente`: No te alcanza el saldo para esta operación. Pásale `recarga_url` a una persona de tu cuenta para que recargue.\n\n`tope_alcanzado`: La clave llegó a su tope de gasto del periodo. Una persona de tu cuenta puede subirlo desde el panel.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error402"
                },
                "examples": {
                  "saldo_insuficiente": {
                    "$ref": "#/components/examples/saldo_insuficiente"
                  },
                  "tope_alcanzado": {
                    "$ref": "#/components/examples/tope_alcanzado"
                  }
                }
              }
            }
          },
          "403": {
            "description": "`permiso_faltante`: La clave no tiene el permiso que pide esta ruta o no tiene acceso a ese RUC.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "permiso_faltante": {
                    "$ref": "#/components/examples/permiso_faltante"
                  }
                }
              }
            }
          },
          "404": {
            "description": "`no_encontrado`: No existe o no pertenece a tu cuenta.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "no_encontrado": {
                    "$ref": "#/components/examples/no_encontrado"
                  }
                }
              }
            }
          },
          "409": {
            "description": "`idempotencia_en_conflicto`: Usaste la misma `Idempotency-Key` con otro cuerpo. Genera una clave nueva para cada operación distinta.\n\n`solicitud_en_curso`: Ya estamos procesando una petición con esa `Idempotency-Key`. Espera unos segundos y vuelve a consultar.\n\n`boveda_inactiva`: La bóveda de credenciales todavía no está activa. Envía `credenciales` en cada llamada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "idempotencia_en_conflicto": {
                    "$ref": "#/components/examples/idempotencia_en_conflicto"
                  },
                  "solicitud_en_curso": {
                    "$ref": "#/components/examples/solicitud_en_curso"
                  },
                  "boveda_inactiva": {
                    "$ref": "#/components/examples/boveda_inactiva"
                  }
                }
              }
            }
          },
          "422": {
            "description": "`credenciales_sunat`: SUNAT no aceptó el certificado o el usuario SOL, o el certificado es de otro RUC.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "credenciales_sunat": {
                    "$ref": "#/components/examples/credenciales_sunat"
                  }
                }
              }
            }
          },
          "429": {
            "description": "`limite_uso`: Hiciste demasiadas peticiones seguidas. Espera los segundos que indica `Retry-After` y vuelve a intentar.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "limite_uso": {
                    "$ref": "#/components/examples/limite_uso"
                  }
                }
              }
            }
          },
          "500": {
            "description": "`error_interno`: Algo falló de nuestro lado. Repite la petición con la misma `Idempotency-Key`: no se duplica nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "error_interno": {
                    "$ref": "#/components/examples/error_interno"
                  }
                }
              }
            }
          },
          "501": {
            "description": "`operacion_no_disponible`: Esta operación existe en el contrato, pero todavía no está habilitada. Revisa en la documentación qué rutas ya puedes usar; no se cobró nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "operacion_no_disponible": {
                    "$ref": "#/components/examples/operacion_no_disponible"
                  }
                }
              }
            }
          },
          "502": {
            "description": "`servicio_externo_no_disponible`: SUNAT, el BCRP o el proveedor de mensajería no respondió. Revisa el estado antes de reenviar.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "servicio_externo_no_disponible": {
                    "$ref": "#/components/examples/servicio_externo_no_disponible"
                  }
                }
              }
            }
          },
          "503": {
            "description": "`no_disponible`: El dato todavía se está cargando o actualizando de nuestro lado. Vuelve a intentar después de los segundos que indica `Retry-After`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "no_disponible": {
                    "$ref": "#/components/examples/no_disponible"
                  }
                }
              }
            }
          }
        },
        "x-nexum": {
          "permiso": "sire:leer",
          "cobro": "reserva",
          "puede_pedir_confirmacion": false,
          "confirmacion_obligatoria": false,
          "acepta_credenciales": true,
          "idempotencia": "requerida",
          "herramienta_mcp": "sire_propuesta_pedir"
        }
      }
    },
    "/v1/emisores/{ruc}/sire/propuestas/{id}": {
      "get": {
        "operationId": "sire_propuesta_ver",
        "summary": "Consulta una propuesta del SIRE",
        "description": "Estado de la propuesta y, cuando está `lista`, sus totales.\n\n**Permiso:** `sire:leer`. **Cobro:** No cobra.",
        "tags": [
          "SIRE"
        ],
        "security": [
          {
            "claveApi": []
          }
        ],
        "parameters": [
          {
            "name": "ruc",
            "in": "path",
            "required": true,
            "description": "RUC del emisor.",
            "schema": {
              "type": "string",
              "pattern": "^(10|15|16|17|20)\\d{9}$",
              "examples": [
                "20000000001"
              ]
            }
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Identificador que empieza con `sire_`.",
            "schema": {
              "type": "string",
              "pattern": "^sire_[A-Za-z0-9]{8,64}$",
              "examples": [
                "sire_8f2c1a7d9e"
              ]
            }
          },
          {
            "$ref": "#/components/parameters/RequestId"
          }
        ],
        "responses": {
          "200": {
            "description": "Propuesta.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PropuestaSire"
                }
              }
            }
          },
          "400": {
            "description": "`validacion`: Algún dato no cumple el formato. En `detalle` va cada campo con su problema.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "validacion": {
                    "$ref": "#/components/examples/validacion"
                  }
                }
              }
            }
          },
          "401": {
            "description": "`clave_invalida`: Falta la clave de API, está mal escrita, venció o fue revocada. Envíala como `Authorization: Bearer onx_live_…`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "clave_invalida": {
                    "$ref": "#/components/examples/clave_invalida"
                  }
                }
              }
            }
          },
          "403": {
            "description": "`permiso_faltante`: La clave no tiene el permiso que pide esta ruta o no tiene acceso a ese RUC.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "permiso_faltante": {
                    "$ref": "#/components/examples/permiso_faltante"
                  }
                }
              }
            }
          },
          "404": {
            "description": "`no_encontrado`: No existe o no pertenece a tu cuenta.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "no_encontrado": {
                    "$ref": "#/components/examples/no_encontrado"
                  }
                }
              }
            }
          },
          "429": {
            "description": "`limite_uso`: Hiciste demasiadas peticiones seguidas. Espera los segundos que indica `Retry-After` y vuelve a intentar.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "limite_uso": {
                    "$ref": "#/components/examples/limite_uso"
                  }
                }
              }
            }
          },
          "500": {
            "description": "`error_interno`: Algo falló de nuestro lado. Repite la petición con la misma `Idempotency-Key`: no se duplica nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "error_interno": {
                    "$ref": "#/components/examples/error_interno"
                  }
                }
              }
            }
          },
          "501": {
            "description": "`operacion_no_disponible`: Esta operación existe en el contrato, pero todavía no está habilitada. Revisa en la documentación qué rutas ya puedes usar; no se cobró nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "operacion_no_disponible": {
                    "$ref": "#/components/examples/operacion_no_disponible"
                  }
                }
              }
            }
          },
          "503": {
            "description": "`no_disponible`: El dato todavía se está cargando o actualizando de nuestro lado. Vuelve a intentar después de los segundos que indica `Retry-After`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "no_disponible": {
                    "$ref": "#/components/examples/no_disponible"
                  }
                }
              }
            }
          }
        },
        "x-nexum": {
          "permiso": "sire:leer",
          "cobro": "no",
          "puede_pedir_confirmacion": false,
          "confirmacion_obligatoria": false,
          "acepta_credenciales": false,
          "idempotencia": "no_aplica",
          "herramienta_mcp": "sire_propuesta_ver"
        }
      }
    },
    "/v1/emisores/{ruc}/sire/propuestas/{id}/registros": {
      "get": {
        "operationId": "sire_registros_listar",
        "summary": "Lista las líneas de una propuesta del SIRE",
        "description": "Comprobantes de la propuesta, normalizados. Solo cuando la propuesta está `lista`.\n\n**Permiso:** `sire:leer`. **Cobro:** No cobra.",
        "tags": [
          "SIRE"
        ],
        "security": [
          {
            "claveApi": []
          }
        ],
        "parameters": [
          {
            "name": "ruc",
            "in": "path",
            "required": true,
            "description": "RUC del emisor.",
            "schema": {
              "type": "string",
              "pattern": "^(10|15|16|17|20)\\d{9}$",
              "examples": [
                "20000000001"
              ]
            }
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Identificador que empieza con `sire_`.",
            "schema": {
              "type": "string",
              "pattern": "^sire_[A-Za-z0-9]{8,64}$",
              "examples": [
                "sire_8f2c1a7d9e"
              ]
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "Cursor opaco que devolvió la página anterior en `siguiente_cursor`.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 512
            }
          },
          {
            "name": "limite",
            "in": "query",
            "required": false,
            "description": "Cuántos elementos traer (1 a 100; por defecto 20).",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100
            }
          },
          {
            "$ref": "#/components/parameters/RequestId"
          }
        ],
        "responses": {
          "200": {
            "description": "Página de líneas.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ListaRegistrosSire"
                }
              }
            }
          },
          "400": {
            "description": "`validacion`: Algún dato no cumple el formato. En `detalle` va cada campo con su problema.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "validacion": {
                    "$ref": "#/components/examples/validacion"
                  }
                }
              }
            }
          },
          "401": {
            "description": "`clave_invalida`: Falta la clave de API, está mal escrita, venció o fue revocada. Envíala como `Authorization: Bearer onx_live_…`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "clave_invalida": {
                    "$ref": "#/components/examples/clave_invalida"
                  }
                }
              }
            }
          },
          "403": {
            "description": "`permiso_faltante`: La clave no tiene el permiso que pide esta ruta o no tiene acceso a ese RUC.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "permiso_faltante": {
                    "$ref": "#/components/examples/permiso_faltante"
                  }
                }
              }
            }
          },
          "404": {
            "description": "`no_encontrado`: No existe o no pertenece a tu cuenta.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "no_encontrado": {
                    "$ref": "#/components/examples/no_encontrado"
                  }
                }
              }
            }
          },
          "409": {
            "description": "`estado_no_permite`: El recurso está en un estado que no permite esta operación, por ejemplo anular un comprobante rechazado.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "estado_no_permite": {
                    "$ref": "#/components/examples/estado_no_permite"
                  }
                }
              }
            }
          },
          "429": {
            "description": "`limite_uso`: Hiciste demasiadas peticiones seguidas. Espera los segundos que indica `Retry-After` y vuelve a intentar.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "limite_uso": {
                    "$ref": "#/components/examples/limite_uso"
                  }
                }
              }
            }
          },
          "500": {
            "description": "`error_interno`: Algo falló de nuestro lado. Repite la petición con la misma `Idempotency-Key`: no se duplica nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "error_interno": {
                    "$ref": "#/components/examples/error_interno"
                  }
                }
              }
            }
          },
          "501": {
            "description": "`operacion_no_disponible`: Esta operación existe en el contrato, pero todavía no está habilitada. Revisa en la documentación qué rutas ya puedes usar; no se cobró nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "operacion_no_disponible": {
                    "$ref": "#/components/examples/operacion_no_disponible"
                  }
                }
              }
            }
          },
          "503": {
            "description": "`no_disponible`: El dato todavía se está cargando o actualizando de nuestro lado. Vuelve a intentar después de los segundos que indica `Retry-After`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "no_disponible": {
                    "$ref": "#/components/examples/no_disponible"
                  }
                }
              }
            }
          }
        },
        "x-nexum": {
          "permiso": "sire:leer",
          "cobro": "no",
          "puede_pedir_confirmacion": false,
          "confirmacion_obligatoria": false,
          "acepta_credenciales": false,
          "idempotencia": "no_aplica",
          "herramienta_mcp": "sire_registros_listar"
        }
      }
    },
    "/v1/emisores/{ruc}/comprobantes/validar": {
      "post": {
        "operationId": "comprobante_validar",
        "summary": "Ensaya un comprobante sin emitirlo",
        "description": "Calcula los totales y revisa las reglas de SUNAT con el mismo cuerpo de la emisión, sin numerar, sin enviar y sin cobrar. Úsalo antes de emitir algo dudoso.\n\n**Permiso:** `comprobantes:emitir`. **Cobro:** No cobra.\n\nSi envías `credenciales`, la clave necesita además `credenciales:por_llamada`.",
        "tags": [
          "Comprobantes"
        ],
        "security": [
          {
            "claveApi": []
          }
        ],
        "parameters": [
          {
            "name": "ruc",
            "in": "path",
            "required": true,
            "description": "RUC del emisor o contribuyente.",
            "schema": {
              "type": "string",
              "pattern": "^(10|15|16|17|20)\\d{9}$",
              "examples": [
                "20000000001"
              ]
            }
          },
          {
            "$ref": "#/components/parameters/RequestId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EmitirComprobante"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Resultado del ensayo.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResultadoValidacion"
                }
              }
            }
          },
          "400": {
            "description": "`validacion`: Algún dato no cumple el formato. En `detalle` va cada campo con su problema.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "validacion": {
                    "$ref": "#/components/examples/validacion"
                  }
                }
              }
            }
          },
          "401": {
            "description": "`clave_invalida`: Falta la clave de API, está mal escrita, venció o fue revocada. Envíala como `Authorization: Bearer onx_live_…`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "clave_invalida": {
                    "$ref": "#/components/examples/clave_invalida"
                  }
                }
              }
            }
          },
          "403": {
            "description": "`permiso_faltante`: La clave no tiene el permiso que pide esta ruta o no tiene acceso a ese RUC.\n\n`emisor_obligado_ose`: Ese RUC figura en el padrón de obligados a emitir mediante un OSE; por ahora no podemos emitir por él.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "permiso_faltante": {
                    "$ref": "#/components/examples/permiso_faltante"
                  },
                  "emisor_obligado_ose": {
                    "$ref": "#/components/examples/emisor_obligado_ose"
                  }
                }
              }
            }
          },
          "404": {
            "description": "`no_encontrado`: No existe o no pertenece a tu cuenta.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "no_encontrado": {
                    "$ref": "#/components/examples/no_encontrado"
                  }
                }
              }
            }
          },
          "422": {
            "description": "`credenciales_sunat`: SUNAT no aceptó el certificado o el usuario SOL, o el certificado es de otro RUC.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "credenciales_sunat": {
                    "$ref": "#/components/examples/credenciales_sunat"
                  }
                }
              }
            }
          },
          "429": {
            "description": "`limite_uso`: Hiciste demasiadas peticiones seguidas. Espera los segundos que indica `Retry-After` y vuelve a intentar.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "limite_uso": {
                    "$ref": "#/components/examples/limite_uso"
                  }
                }
              }
            }
          },
          "500": {
            "description": "`error_interno`: Algo falló de nuestro lado. Repite la petición con la misma `Idempotency-Key`: no se duplica nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "error_interno": {
                    "$ref": "#/components/examples/error_interno"
                  }
                }
              }
            }
          },
          "501": {
            "description": "`operacion_no_disponible`: Esta operación existe en el contrato, pero todavía no está habilitada. Revisa en la documentación qué rutas ya puedes usar; no se cobró nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "operacion_no_disponible": {
                    "$ref": "#/components/examples/operacion_no_disponible"
                  }
                }
              }
            }
          },
          "503": {
            "description": "`no_disponible`: El dato todavía se está cargando o actualizando de nuestro lado. Vuelve a intentar después de los segundos que indica `Retry-After`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "no_disponible": {
                    "$ref": "#/components/examples/no_disponible"
                  }
                }
              }
            }
          }
        },
        "x-nexum": {
          "permiso": "comprobantes:emitir",
          "cobro": "no",
          "puede_pedir_confirmacion": false,
          "confirmacion_obligatoria": false,
          "acepta_credenciales": true,
          "idempotencia": "no_aplica",
          "herramienta_mcp": "comprobante_validar"
        }
      }
    },
    "/v1/emisores/{ruc}/comprobantes": {
      "post": {
        "operationId": "comprobante_emitir",
        "summary": "Emite una factura, boleta o nota",
        "description": "Emite y envía a SUNAT. El número lo asigna el servidor. Reserva el precio del saldo y lo cobra solo si SUNAT acepta; si SUNAT rechaza, se libera. Si SUNAT no responde, queda `en_cola` (202) y se envía solo. Según tu clave, notas, bajas o montos altos esperan la aprobación de una persona (202 `requiere_confirmacion`).\n\n**Permiso:** `comprobantes:emitir`. **Cobro:** Reserva el precio del saldo y lo cobra solo si el servicio confirma.\n\n**Idempotency-Key:** obligatoria.\n\n**Puede pedir aprobación humana** según tu clave (202 `requiere_confirmacion`).\n\nSi envías `credenciales`, la clave necesita además `credenciales:por_llamada`.",
        "tags": [
          "Comprobantes"
        ],
        "security": [
          {
            "claveApi": []
          }
        ],
        "parameters": [
          {
            "name": "ruc",
            "in": "path",
            "required": true,
            "description": "RUC del emisor o contribuyente.",
            "schema": {
              "type": "string",
              "pattern": "^(10|15|16|17|20)\\d{9}$",
              "examples": [
                "20000000001"
              ]
            }
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "$ref": "#/components/parameters/RequestId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EmitirComprobante"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Aceptado por SUNAT (o aceptado con observaciones).",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Comprobante"
                }
              }
            }
          },
          "202": {
            "description": "En cola por SUNAT o esperando aprobación humana.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RespuestaAceptada"
                }
              }
            }
          },
          "400": {
            "description": "`validacion`: Algún dato no cumple el formato. En `detalle` va cada campo con su problema.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "validacion": {
                    "$ref": "#/components/examples/validacion"
                  }
                }
              }
            }
          },
          "401": {
            "description": "`clave_invalida`: Falta la clave de API, está mal escrita, venció o fue revocada. Envíala como `Authorization: Bearer onx_live_…`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "clave_invalida": {
                    "$ref": "#/components/examples/clave_invalida"
                  }
                }
              }
            }
          },
          "402": {
            "description": "`saldo_insuficiente`: No te alcanza el saldo para esta operación. Pásale `recarga_url` a una persona de tu cuenta para que recargue.\n\n`tope_alcanzado`: La clave llegó a su tope de gasto del periodo. Una persona de tu cuenta puede subirlo desde el panel.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error402"
                },
                "examples": {
                  "saldo_insuficiente": {
                    "$ref": "#/components/examples/saldo_insuficiente"
                  },
                  "tope_alcanzado": {
                    "$ref": "#/components/examples/tope_alcanzado"
                  }
                }
              }
            }
          },
          "403": {
            "description": "`permiso_faltante`: La clave no tiene el permiso que pide esta ruta o no tiene acceso a ese RUC.\n\n`emisor_obligado_ose`: Ese RUC figura en el padrón de obligados a emitir mediante un OSE; por ahora no podemos emitir por él.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "permiso_faltante": {
                    "$ref": "#/components/examples/permiso_faltante"
                  },
                  "emisor_obligado_ose": {
                    "$ref": "#/components/examples/emisor_obligado_ose"
                  }
                }
              }
            }
          },
          "404": {
            "description": "`no_encontrado`: No existe o no pertenece a tu cuenta.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "no_encontrado": {
                    "$ref": "#/components/examples/no_encontrado"
                  }
                }
              }
            }
          },
          "409": {
            "description": "`idempotencia_en_conflicto`: Usaste la misma `Idempotency-Key` con otro cuerpo. Genera una clave nueva para cada operación distinta.\n\n`solicitud_en_curso`: Ya estamos procesando una petición con esa `Idempotency-Key`. Espera unos segundos y vuelve a consultar.\n\n`boveda_inactiva`: La bóveda de credenciales todavía no está activa. Envía `credenciales` en cada llamada.\n\n`plazo_vencido`: Pasó el plazo que da SUNAT para esta operación. Para anular una factura fuera de plazo, emite una nota de crédito.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "idempotencia_en_conflicto": {
                    "$ref": "#/components/examples/idempotencia_en_conflicto"
                  },
                  "solicitud_en_curso": {
                    "$ref": "#/components/examples/solicitud_en_curso"
                  },
                  "boveda_inactiva": {
                    "$ref": "#/components/examples/boveda_inactiva"
                  },
                  "plazo_vencido": {
                    "$ref": "#/components/examples/plazo_vencido"
                  }
                }
              }
            }
          },
          "422": {
            "description": "`sunat_rechazo`: SUNAT rechazó el comprobante. En `detalle` van el código y la descripción que dio SUNAT.\n\n`credenciales_sunat`: SUNAT no aceptó el certificado o el usuario SOL, o el certificado es de otro RUC.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "sunat_rechazo": {
                    "$ref": "#/components/examples/sunat_rechazo"
                  },
                  "credenciales_sunat": {
                    "$ref": "#/components/examples/credenciales_sunat"
                  }
                }
              }
            }
          },
          "429": {
            "description": "`limite_uso`: Hiciste demasiadas peticiones seguidas. Espera los segundos que indica `Retry-After` y vuelve a intentar.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "limite_uso": {
                    "$ref": "#/components/examples/limite_uso"
                  }
                }
              }
            }
          },
          "500": {
            "description": "`error_interno`: Algo falló de nuestro lado. Repite la petición con la misma `Idempotency-Key`: no se duplica nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "error_interno": {
                    "$ref": "#/components/examples/error_interno"
                  }
                }
              }
            }
          },
          "501": {
            "description": "`operacion_no_disponible`: Esta operación existe en el contrato, pero todavía no está habilitada. Revisa en la documentación qué rutas ya puedes usar; no se cobró nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "operacion_no_disponible": {
                    "$ref": "#/components/examples/operacion_no_disponible"
                  }
                }
              }
            }
          },
          "503": {
            "description": "`no_disponible`: El dato todavía se está cargando o actualizando de nuestro lado. Vuelve a intentar después de los segundos que indica `Retry-After`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "no_disponible": {
                    "$ref": "#/components/examples/no_disponible"
                  }
                }
              }
            }
          }
        },
        "x-nexum": {
          "permiso": "comprobantes:emitir",
          "cobro": "reserva",
          "puede_pedir_confirmacion": true,
          "confirmacion_obligatoria": false,
          "acepta_credenciales": true,
          "idempotencia": "requerida",
          "herramienta_mcp": "comprobante_emitir"
        }
      },
      "get": {
        "operationId": "comprobante_listar",
        "summary": "Lista comprobantes de un emisor",
        "description": "Comprobantes del RUC, del más reciente al más antiguo, con filtros por tipo, serie, estado y fechas.\n\n**Permiso:** `comprobantes:leer`. **Cobro:** No cobra.",
        "tags": [
          "Comprobantes"
        ],
        "security": [
          {
            "claveApi": []
          }
        ],
        "parameters": [
          {
            "name": "ruc",
            "in": "path",
            "required": true,
            "description": "RUC del emisor o contribuyente.",
            "schema": {
              "type": "string",
              "pattern": "^(10|15|16|17|20)\\d{9}$",
              "examples": [
                "20000000001"
              ]
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "Cursor opaco que devolvió la página anterior en `siguiente_cursor`.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 512
            }
          },
          {
            "name": "limite",
            "in": "query",
            "required": false,
            "description": "Cuántos elementos traer (1 a 100; por defecto 20).",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100
            }
          },
          {
            "name": "tipo",
            "in": "query",
            "required": false,
            "description": "01 factura, 03 boleta, 07 nota de crédito, 08 nota de débito.",
            "schema": {
              "type": "string",
              "enum": [
                "01",
                "03",
                "07",
                "08"
              ]
            }
          },
          {
            "name": "serie",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[FB][A-Z0-9]{3}$"
            }
          },
          {
            "name": "estado",
            "in": "query",
            "required": false,
            "description": "`en_cola`: guardado y esperando a SUNAT. `observado`: aceptado con observaciones. `en_baja`: anulación en curso.",
            "schema": {
              "type": "string",
              "enum": [
                "en_cola",
                "aceptado",
                "observado",
                "rechazado",
                "en_baja",
                "anulado"
              ]
            }
          },
          {
            "name": "desde",
            "in": "query",
            "required": false,
            "description": "Emitidos desde este día (incluido).",
            "schema": {
              "type": "string",
              "format": "date",
              "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$",
              "examples": [
                "2026-11-15"
              ]
            }
          },
          {
            "name": "hasta",
            "in": "query",
            "required": false,
            "description": "Emitidos hasta este día (incluido).",
            "schema": {
              "type": "string",
              "format": "date",
              "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$",
              "examples": [
                "2026-11-15"
              ]
            }
          },
          {
            "name": "cliente_documento",
            "in": "query",
            "required": false,
            "description": "Número de documento del cliente.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 15
            }
          },
          {
            "$ref": "#/components/parameters/RequestId"
          }
        ],
        "responses": {
          "200": {
            "description": "Página de comprobantes.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ListaComprobantes"
                }
              }
            }
          },
          "400": {
            "description": "`validacion`: Algún dato no cumple el formato. En `detalle` va cada campo con su problema.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "validacion": {
                    "$ref": "#/components/examples/validacion"
                  }
                }
              }
            }
          },
          "401": {
            "description": "`clave_invalida`: Falta la clave de API, está mal escrita, venció o fue revocada. Envíala como `Authorization: Bearer onx_live_…`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "clave_invalida": {
                    "$ref": "#/components/examples/clave_invalida"
                  }
                }
              }
            }
          },
          "403": {
            "description": "`permiso_faltante`: La clave no tiene el permiso que pide esta ruta o no tiene acceso a ese RUC.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "permiso_faltante": {
                    "$ref": "#/components/examples/permiso_faltante"
                  }
                }
              }
            }
          },
          "404": {
            "description": "`no_encontrado`: No existe o no pertenece a tu cuenta.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "no_encontrado": {
                    "$ref": "#/components/examples/no_encontrado"
                  }
                }
              }
            }
          },
          "429": {
            "description": "`limite_uso`: Hiciste demasiadas peticiones seguidas. Espera los segundos que indica `Retry-After` y vuelve a intentar.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "limite_uso": {
                    "$ref": "#/components/examples/limite_uso"
                  }
                }
              }
            }
          },
          "500": {
            "description": "`error_interno`: Algo falló de nuestro lado. Repite la petición con la misma `Idempotency-Key`: no se duplica nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "error_interno": {
                    "$ref": "#/components/examples/error_interno"
                  }
                }
              }
            }
          },
          "501": {
            "description": "`operacion_no_disponible`: Esta operación existe en el contrato, pero todavía no está habilitada. Revisa en la documentación qué rutas ya puedes usar; no se cobró nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "operacion_no_disponible": {
                    "$ref": "#/components/examples/operacion_no_disponible"
                  }
                }
              }
            }
          },
          "503": {
            "description": "`no_disponible`: El dato todavía se está cargando o actualizando de nuestro lado. Vuelve a intentar después de los segundos que indica `Retry-After`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "no_disponible": {
                    "$ref": "#/components/examples/no_disponible"
                  }
                }
              }
            }
          }
        },
        "x-nexum": {
          "permiso": "comprobantes:leer",
          "cobro": "no",
          "puede_pedir_confirmacion": false,
          "confirmacion_obligatoria": false,
          "acepta_credenciales": false,
          "idempotencia": "no_aplica",
          "herramienta_mcp": "comprobante_listar"
        }
      }
    },
    "/v1/emisores/{ruc}/comprobantes/{id}": {
      "get": {
        "operationId": "comprobante_ver",
        "summary": "Consulta un comprobante",
        "description": "Detalle, estado ante SUNAT y enlaces de descarga de un comprobante.\n\n**Permiso:** `comprobantes:leer`. **Cobro:** No cobra.",
        "tags": [
          "Comprobantes"
        ],
        "security": [
          {
            "claveApi": []
          }
        ],
        "parameters": [
          {
            "name": "ruc",
            "in": "path",
            "required": true,
            "description": "RUC del emisor.",
            "schema": {
              "type": "string",
              "pattern": "^(10|15|16|17|20)\\d{9}$",
              "examples": [
                "20000000001"
              ]
            }
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Identificador que empieza con `cmp_`.",
            "schema": {
              "type": "string",
              "pattern": "^cmp_[A-Za-z0-9]{8,64}$",
              "examples": [
                "cmp_8f2c1a7d9e"
              ]
            }
          },
          {
            "$ref": "#/components/parameters/RequestId"
          }
        ],
        "responses": {
          "200": {
            "description": "Comprobante.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Comprobante"
                }
              }
            }
          },
          "400": {
            "description": "`validacion`: Algún dato no cumple el formato. En `detalle` va cada campo con su problema.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "validacion": {
                    "$ref": "#/components/examples/validacion"
                  }
                }
              }
            }
          },
          "401": {
            "description": "`clave_invalida`: Falta la clave de API, está mal escrita, venció o fue revocada. Envíala como `Authorization: Bearer onx_live_…`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "clave_invalida": {
                    "$ref": "#/components/examples/clave_invalida"
                  }
                }
              }
            }
          },
          "403": {
            "description": "`permiso_faltante`: La clave no tiene el permiso que pide esta ruta o no tiene acceso a ese RUC.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "permiso_faltante": {
                    "$ref": "#/components/examples/permiso_faltante"
                  }
                }
              }
            }
          },
          "404": {
            "description": "`no_encontrado`: No existe o no pertenece a tu cuenta.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "no_encontrado": {
                    "$ref": "#/components/examples/no_encontrado"
                  }
                }
              }
            }
          },
          "429": {
            "description": "`limite_uso`: Hiciste demasiadas peticiones seguidas. Espera los segundos que indica `Retry-After` y vuelve a intentar.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "limite_uso": {
                    "$ref": "#/components/examples/limite_uso"
                  }
                }
              }
            }
          },
          "500": {
            "description": "`error_interno`: Algo falló de nuestro lado. Repite la petición con la misma `Idempotency-Key`: no se duplica nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "error_interno": {
                    "$ref": "#/components/examples/error_interno"
                  }
                }
              }
            }
          },
          "501": {
            "description": "`operacion_no_disponible`: Esta operación existe en el contrato, pero todavía no está habilitada. Revisa en la documentación qué rutas ya puedes usar; no se cobró nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "operacion_no_disponible": {
                    "$ref": "#/components/examples/operacion_no_disponible"
                  }
                }
              }
            }
          },
          "503": {
            "description": "`no_disponible`: El dato todavía se está cargando o actualizando de nuestro lado. Vuelve a intentar después de los segundos que indica `Retry-After`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "no_disponible": {
                    "$ref": "#/components/examples/no_disponible"
                  }
                }
              }
            }
          }
        },
        "x-nexum": {
          "permiso": "comprobantes:leer",
          "cobro": "no",
          "puede_pedir_confirmacion": false,
          "confirmacion_obligatoria": false,
          "acepta_credenciales": false,
          "idempotencia": "no_aplica",
          "herramienta_mcp": "comprobante_ver"
        }
      }
    },
    "/v1/emisores/{ruc}/comprobantes/{id}/xml": {
      "get": {
        "operationId": "comprobante_xml",
        "summary": "Descarga el XML firmado",
        "description": "XML UBL 2.1 firmado tal como se envió a SUNAT.\n\n**Permiso:** `comprobantes:leer`. **Cobro:** No cobra.",
        "tags": [
          "Comprobantes"
        ],
        "security": [
          {
            "claveApi": []
          }
        ],
        "parameters": [
          {
            "name": "ruc",
            "in": "path",
            "required": true,
            "description": "RUC del emisor.",
            "schema": {
              "type": "string",
              "pattern": "^(10|15|16|17|20)\\d{9}$",
              "examples": [
                "20000000001"
              ]
            }
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Identificador que empieza con `cmp_`.",
            "schema": {
              "type": "string",
              "pattern": "^cmp_[A-Za-z0-9]{8,64}$",
              "examples": [
                "cmp_8f2c1a7d9e"
              ]
            }
          },
          {
            "$ref": "#/components/parameters/RequestId"
          }
        ],
        "responses": {
          "200": {
            "description": "Archivo del comprobante.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/xml": {
                "schema": {
                  "type": "string",
                  "contentMediaType": "application/xml"
                }
              }
            }
          },
          "400": {
            "description": "`validacion`: Algún dato no cumple el formato. En `detalle` va cada campo con su problema.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "validacion": {
                    "$ref": "#/components/examples/validacion"
                  }
                }
              }
            }
          },
          "401": {
            "description": "`clave_invalida`: Falta la clave de API, está mal escrita, venció o fue revocada. Envíala como `Authorization: Bearer onx_live_…`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "clave_invalida": {
                    "$ref": "#/components/examples/clave_invalida"
                  }
                }
              }
            }
          },
          "403": {
            "description": "`permiso_faltante`: La clave no tiene el permiso que pide esta ruta o no tiene acceso a ese RUC.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "permiso_faltante": {
                    "$ref": "#/components/examples/permiso_faltante"
                  }
                }
              }
            }
          },
          "404": {
            "description": "`no_encontrado`: No existe o no pertenece a tu cuenta.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "no_encontrado": {
                    "$ref": "#/components/examples/no_encontrado"
                  }
                }
              }
            }
          },
          "409": {
            "description": "`estado_no_permite`: El recurso está en un estado que no permite esta operación, por ejemplo anular un comprobante rechazado.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "estado_no_permite": {
                    "$ref": "#/components/examples/estado_no_permite"
                  }
                }
              }
            }
          },
          "429": {
            "description": "`limite_uso`: Hiciste demasiadas peticiones seguidas. Espera los segundos que indica `Retry-After` y vuelve a intentar.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "limite_uso": {
                    "$ref": "#/components/examples/limite_uso"
                  }
                }
              }
            }
          },
          "500": {
            "description": "`error_interno`: Algo falló de nuestro lado. Repite la petición con la misma `Idempotency-Key`: no se duplica nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "error_interno": {
                    "$ref": "#/components/examples/error_interno"
                  }
                }
              }
            }
          },
          "501": {
            "description": "`operacion_no_disponible`: Esta operación existe en el contrato, pero todavía no está habilitada. Revisa en la documentación qué rutas ya puedes usar; no se cobró nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "operacion_no_disponible": {
                    "$ref": "#/components/examples/operacion_no_disponible"
                  }
                }
              }
            }
          },
          "503": {
            "description": "`no_disponible`: El dato todavía se está cargando o actualizando de nuestro lado. Vuelve a intentar después de los segundos que indica `Retry-After`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "no_disponible": {
                    "$ref": "#/components/examples/no_disponible"
                  }
                }
              }
            }
          }
        },
        "x-nexum": {
          "permiso": "comprobantes:leer",
          "cobro": "no",
          "puede_pedir_confirmacion": false,
          "confirmacion_obligatoria": false,
          "acepta_credenciales": false,
          "idempotencia": "no_aplica",
          "herramienta_mcp": null
        }
      }
    },
    "/v1/emisores/{ruc}/comprobantes/{id}/cdr": {
      "get": {
        "operationId": "comprobante_cdr",
        "summary": "Descarga el CDR",
        "description": "Constancia de recepción (CDR) de SUNAT en XML. Mientras está `en_cola` responde `estado_no_permite`.\n\n**Permiso:** `comprobantes:leer`. **Cobro:** No cobra.",
        "tags": [
          "Comprobantes"
        ],
        "security": [
          {
            "claveApi": []
          }
        ],
        "parameters": [
          {
            "name": "ruc",
            "in": "path",
            "required": true,
            "description": "RUC del emisor.",
            "schema": {
              "type": "string",
              "pattern": "^(10|15|16|17|20)\\d{9}$",
              "examples": [
                "20000000001"
              ]
            }
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Identificador que empieza con `cmp_`.",
            "schema": {
              "type": "string",
              "pattern": "^cmp_[A-Za-z0-9]{8,64}$",
              "examples": [
                "cmp_8f2c1a7d9e"
              ]
            }
          },
          {
            "$ref": "#/components/parameters/RequestId"
          }
        ],
        "responses": {
          "200": {
            "description": "Archivo del comprobante.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/xml": {
                "schema": {
                  "type": "string",
                  "contentMediaType": "application/xml"
                }
              }
            }
          },
          "400": {
            "description": "`validacion`: Algún dato no cumple el formato. En `detalle` va cada campo con su problema.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "validacion": {
                    "$ref": "#/components/examples/validacion"
                  }
                }
              }
            }
          },
          "401": {
            "description": "`clave_invalida`: Falta la clave de API, está mal escrita, venció o fue revocada. Envíala como `Authorization: Bearer onx_live_…`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "clave_invalida": {
                    "$ref": "#/components/examples/clave_invalida"
                  }
                }
              }
            }
          },
          "403": {
            "description": "`permiso_faltante`: La clave no tiene el permiso que pide esta ruta o no tiene acceso a ese RUC.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "permiso_faltante": {
                    "$ref": "#/components/examples/permiso_faltante"
                  }
                }
              }
            }
          },
          "404": {
            "description": "`no_encontrado`: No existe o no pertenece a tu cuenta.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "no_encontrado": {
                    "$ref": "#/components/examples/no_encontrado"
                  }
                }
              }
            }
          },
          "409": {
            "description": "`estado_no_permite`: El recurso está en un estado que no permite esta operación, por ejemplo anular un comprobante rechazado.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "estado_no_permite": {
                    "$ref": "#/components/examples/estado_no_permite"
                  }
                }
              }
            }
          },
          "429": {
            "description": "`limite_uso`: Hiciste demasiadas peticiones seguidas. Espera los segundos que indica `Retry-After` y vuelve a intentar.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "limite_uso": {
                    "$ref": "#/components/examples/limite_uso"
                  }
                }
              }
            }
          },
          "500": {
            "description": "`error_interno`: Algo falló de nuestro lado. Repite la petición con la misma `Idempotency-Key`: no se duplica nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "error_interno": {
                    "$ref": "#/components/examples/error_interno"
                  }
                }
              }
            }
          },
          "501": {
            "description": "`operacion_no_disponible`: Esta operación existe en el contrato, pero todavía no está habilitada. Revisa en la documentación qué rutas ya puedes usar; no se cobró nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "operacion_no_disponible": {
                    "$ref": "#/components/examples/operacion_no_disponible"
                  }
                }
              }
            }
          },
          "503": {
            "description": "`no_disponible`: El dato todavía se está cargando o actualizando de nuestro lado. Vuelve a intentar después de los segundos que indica `Retry-After`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "no_disponible": {
                    "$ref": "#/components/examples/no_disponible"
                  }
                }
              }
            }
          }
        },
        "x-nexum": {
          "permiso": "comprobantes:leer",
          "cobro": "no",
          "puede_pedir_confirmacion": false,
          "confirmacion_obligatoria": false,
          "acepta_credenciales": false,
          "idempotencia": "no_aplica",
          "herramienta_mcp": null
        }
      }
    },
    "/v1/emisores/{ruc}/comprobantes/{id}/pdf": {
      "get": {
        "operationId": "comprobante_pdf",
        "summary": "Descarga el PDF",
        "description": "Representación impresa con QR, en A4 o ticket de 80 mm.\n\n**Permiso:** `comprobantes:leer`. **Cobro:** No cobra.",
        "tags": [
          "Comprobantes"
        ],
        "security": [
          {
            "claveApi": []
          }
        ],
        "parameters": [
          {
            "name": "ruc",
            "in": "path",
            "required": true,
            "description": "RUC del emisor.",
            "schema": {
              "type": "string",
              "pattern": "^(10|15|16|17|20)\\d{9}$",
              "examples": [
                "20000000001"
              ]
            }
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Identificador que empieza con `cmp_`.",
            "schema": {
              "type": "string",
              "pattern": "^cmp_[A-Za-z0-9]{8,64}$",
              "examples": [
                "cmp_8f2c1a7d9e"
              ]
            }
          },
          {
            "name": "formato",
            "in": "query",
            "required": false,
            "description": "`a4` (por defecto) o `ticket80` para impresoras de 80 mm.",
            "schema": {
              "type": "string",
              "enum": [
                "a4",
                "ticket80"
              ]
            }
          },
          {
            "$ref": "#/components/parameters/RequestId"
          }
        ],
        "responses": {
          "200": {
            "description": "Archivo del comprobante.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/pdf": {
                "schema": {
                  "type": "string",
                  "contentMediaType": "application/pdf"
                }
              }
            }
          },
          "400": {
            "description": "`validacion`: Algún dato no cumple el formato. En `detalle` va cada campo con su problema.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "validacion": {
                    "$ref": "#/components/examples/validacion"
                  }
                }
              }
            }
          },
          "401": {
            "description": "`clave_invalida`: Falta la clave de API, está mal escrita, venció o fue revocada. Envíala como `Authorization: Bearer onx_live_…`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "clave_invalida": {
                    "$ref": "#/components/examples/clave_invalida"
                  }
                }
              }
            }
          },
          "403": {
            "description": "`permiso_faltante`: La clave no tiene el permiso que pide esta ruta o no tiene acceso a ese RUC.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "permiso_faltante": {
                    "$ref": "#/components/examples/permiso_faltante"
                  }
                }
              }
            }
          },
          "404": {
            "description": "`no_encontrado`: No existe o no pertenece a tu cuenta.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "no_encontrado": {
                    "$ref": "#/components/examples/no_encontrado"
                  }
                }
              }
            }
          },
          "409": {
            "description": "`estado_no_permite`: El recurso está en un estado que no permite esta operación, por ejemplo anular un comprobante rechazado.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "estado_no_permite": {
                    "$ref": "#/components/examples/estado_no_permite"
                  }
                }
              }
            }
          },
          "429": {
            "description": "`limite_uso`: Hiciste demasiadas peticiones seguidas. Espera los segundos que indica `Retry-After` y vuelve a intentar.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "limite_uso": {
                    "$ref": "#/components/examples/limite_uso"
                  }
                }
              }
            }
          },
          "500": {
            "description": "`error_interno`: Algo falló de nuestro lado. Repite la petición con la misma `Idempotency-Key`: no se duplica nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "error_interno": {
                    "$ref": "#/components/examples/error_interno"
                  }
                }
              }
            }
          },
          "501": {
            "description": "`operacion_no_disponible`: Esta operación existe en el contrato, pero todavía no está habilitada. Revisa en la documentación qué rutas ya puedes usar; no se cobró nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "operacion_no_disponible": {
                    "$ref": "#/components/examples/operacion_no_disponible"
                  }
                }
              }
            }
          },
          "503": {
            "description": "`no_disponible`: El dato todavía se está cargando o actualizando de nuestro lado. Vuelve a intentar después de los segundos que indica `Retry-After`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "no_disponible": {
                    "$ref": "#/components/examples/no_disponible"
                  }
                }
              }
            }
          }
        },
        "x-nexum": {
          "permiso": "comprobantes:leer",
          "cobro": "no",
          "puede_pedir_confirmacion": false,
          "confirmacion_obligatoria": false,
          "acepta_credenciales": false,
          "idempotencia": "no_aplica",
          "herramienta_mcp": "comprobante_pdf"
        }
      }
    },
    "/v1/emisores/{ruc}/comprobantes/{id}/anular": {
      "post": {
        "operationId": "comprobante_anular",
        "summary": "Da de baja un comprobante",
        "description": "Comunicación de baja para facturas y resumen diario para boletas, dentro del plazo de SUNAT. La baja es asíncrona (202 `en_cola`). Según tu clave, puede esperar la aprobación de una persona.\n\n**Permiso:** `comprobantes:anular`. **Cobro:** No cobra.\n\n**Idempotency-Key:** obligatoria.\n\n**Puede pedir aprobación humana** según tu clave (202 `requiere_confirmacion`).\n\nSi envías `credenciales`, la clave necesita además `credenciales:por_llamada`.",
        "tags": [
          "Comprobantes"
        ],
        "security": [
          {
            "claveApi": []
          }
        ],
        "parameters": [
          {
            "name": "ruc",
            "in": "path",
            "required": true,
            "description": "RUC del emisor.",
            "schema": {
              "type": "string",
              "pattern": "^(10|15|16|17|20)\\d{9}$",
              "examples": [
                "20000000001"
              ]
            }
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Identificador que empieza con `cmp_`.",
            "schema": {
              "type": "string",
              "pattern": "^cmp_[A-Za-z0-9]{8,64}$",
              "examples": [
                "cmp_8f2c1a7d9e"
              ]
            }
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "$ref": "#/components/parameters/RequestId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AnularComprobante"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Baja en cola o esperando aprobación.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RespuestaAceptada"
                }
              }
            }
          },
          "400": {
            "description": "`validacion`: Algún dato no cumple el formato. En `detalle` va cada campo con su problema.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "validacion": {
                    "$ref": "#/components/examples/validacion"
                  }
                }
              }
            }
          },
          "401": {
            "description": "`clave_invalida`: Falta la clave de API, está mal escrita, venció o fue revocada. Envíala como `Authorization: Bearer onx_live_…`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "clave_invalida": {
                    "$ref": "#/components/examples/clave_invalida"
                  }
                }
              }
            }
          },
          "403": {
            "description": "`permiso_faltante`: La clave no tiene el permiso que pide esta ruta o no tiene acceso a ese RUC.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "permiso_faltante": {
                    "$ref": "#/components/examples/permiso_faltante"
                  }
                }
              }
            }
          },
          "404": {
            "description": "`no_encontrado`: No existe o no pertenece a tu cuenta.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "no_encontrado": {
                    "$ref": "#/components/examples/no_encontrado"
                  }
                }
              }
            }
          },
          "409": {
            "description": "`idempotencia_en_conflicto`: Usaste la misma `Idempotency-Key` con otro cuerpo. Genera una clave nueva para cada operación distinta.\n\n`solicitud_en_curso`: Ya estamos procesando una petición con esa `Idempotency-Key`. Espera unos segundos y vuelve a consultar.\n\n`boveda_inactiva`: La bóveda de credenciales todavía no está activa. Envía `credenciales` en cada llamada.\n\n`estado_no_permite`: El recurso está en un estado que no permite esta operación, por ejemplo anular un comprobante rechazado.\n\n`plazo_vencido`: Pasó el plazo que da SUNAT para esta operación. Para anular una factura fuera de plazo, emite una nota de crédito.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "idempotencia_en_conflicto": {
                    "$ref": "#/components/examples/idempotencia_en_conflicto"
                  },
                  "solicitud_en_curso": {
                    "$ref": "#/components/examples/solicitud_en_curso"
                  },
                  "boveda_inactiva": {
                    "$ref": "#/components/examples/boveda_inactiva"
                  },
                  "estado_no_permite": {
                    "$ref": "#/components/examples/estado_no_permite"
                  },
                  "plazo_vencido": {
                    "$ref": "#/components/examples/plazo_vencido"
                  }
                }
              }
            }
          },
          "422": {
            "description": "`credenciales_sunat`: SUNAT no aceptó el certificado o el usuario SOL, o el certificado es de otro RUC.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "credenciales_sunat": {
                    "$ref": "#/components/examples/credenciales_sunat"
                  }
                }
              }
            }
          },
          "429": {
            "description": "`limite_uso`: Hiciste demasiadas peticiones seguidas. Espera los segundos que indica `Retry-After` y vuelve a intentar.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "limite_uso": {
                    "$ref": "#/components/examples/limite_uso"
                  }
                }
              }
            }
          },
          "500": {
            "description": "`error_interno`: Algo falló de nuestro lado. Repite la petición con la misma `Idempotency-Key`: no se duplica nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "error_interno": {
                    "$ref": "#/components/examples/error_interno"
                  }
                }
              }
            }
          },
          "501": {
            "description": "`operacion_no_disponible`: Esta operación existe en el contrato, pero todavía no está habilitada. Revisa en la documentación qué rutas ya puedes usar; no se cobró nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "operacion_no_disponible": {
                    "$ref": "#/components/examples/operacion_no_disponible"
                  }
                }
              }
            }
          },
          "503": {
            "description": "`no_disponible`: El dato todavía se está cargando o actualizando de nuestro lado. Vuelve a intentar después de los segundos que indica `Retry-After`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "no_disponible": {
                    "$ref": "#/components/examples/no_disponible"
                  }
                }
              }
            }
          }
        },
        "x-nexum": {
          "permiso": "comprobantes:anular",
          "cobro": "no",
          "puede_pedir_confirmacion": true,
          "confirmacion_obligatoria": false,
          "acepta_credenciales": true,
          "idempotencia": "requerida",
          "herramienta_mcp": "comprobante_anular"
        }
      }
    },
    "/v1/emisores/{ruc}/comprobantes/{id}/consultar-sunat": {
      "post": {
        "operationId": "comprobante_consultar_sunat",
        "summary": "Pregunta a SUNAT el estado de un comprobante",
        "description": "Consulta el estado en SUNAT, guarda el CDR si llega y devuelve el comprobante actualizado.\n\n**Permiso:** `comprobantes:leer`. **Cobro:** No cobra.\n\nSi envías `credenciales`, la clave necesita además `credenciales:por_llamada`.",
        "tags": [
          "Comprobantes"
        ],
        "security": [
          {
            "claveApi": []
          }
        ],
        "parameters": [
          {
            "name": "ruc",
            "in": "path",
            "required": true,
            "description": "RUC del emisor.",
            "schema": {
              "type": "string",
              "pattern": "^(10|15|16|17|20)\\d{9}$",
              "examples": [
                "20000000001"
              ]
            }
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Identificador que empieza con `cmp_`.",
            "schema": {
              "type": "string",
              "pattern": "^cmp_[A-Za-z0-9]{8,64}$",
              "examples": [
                "cmp_8f2c1a7d9e"
              ]
            }
          },
          {
            "$ref": "#/components/parameters/RequestId"
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ConsultarSunat"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Comprobante con el estado que dio SUNAT.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Comprobante"
                }
              }
            }
          },
          "400": {
            "description": "`validacion`: Algún dato no cumple el formato. En `detalle` va cada campo con su problema.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "validacion": {
                    "$ref": "#/components/examples/validacion"
                  }
                }
              }
            }
          },
          "401": {
            "description": "`clave_invalida`: Falta la clave de API, está mal escrita, venció o fue revocada. Envíala como `Authorization: Bearer onx_live_…`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "clave_invalida": {
                    "$ref": "#/components/examples/clave_invalida"
                  }
                }
              }
            }
          },
          "403": {
            "description": "`permiso_faltante`: La clave no tiene el permiso que pide esta ruta o no tiene acceso a ese RUC.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "permiso_faltante": {
                    "$ref": "#/components/examples/permiso_faltante"
                  }
                }
              }
            }
          },
          "404": {
            "description": "`no_encontrado`: No existe o no pertenece a tu cuenta.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "no_encontrado": {
                    "$ref": "#/components/examples/no_encontrado"
                  }
                }
              }
            }
          },
          "409": {
            "description": "`boveda_inactiva`: La bóveda de credenciales todavía no está activa. Envía `credenciales` en cada llamada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "boveda_inactiva": {
                    "$ref": "#/components/examples/boveda_inactiva"
                  }
                }
              }
            }
          },
          "422": {
            "description": "`credenciales_sunat`: SUNAT no aceptó el certificado o el usuario SOL, o el certificado es de otro RUC.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "credenciales_sunat": {
                    "$ref": "#/components/examples/credenciales_sunat"
                  }
                }
              }
            }
          },
          "429": {
            "description": "`limite_uso`: Hiciste demasiadas peticiones seguidas. Espera los segundos que indica `Retry-After` y vuelve a intentar.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "limite_uso": {
                    "$ref": "#/components/examples/limite_uso"
                  }
                }
              }
            }
          },
          "500": {
            "description": "`error_interno`: Algo falló de nuestro lado. Repite la petición con la misma `Idempotency-Key`: no se duplica nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "error_interno": {
                    "$ref": "#/components/examples/error_interno"
                  }
                }
              }
            }
          },
          "501": {
            "description": "`operacion_no_disponible`: Esta operación existe en el contrato, pero todavía no está habilitada. Revisa en la documentación qué rutas ya puedes usar; no se cobró nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "operacion_no_disponible": {
                    "$ref": "#/components/examples/operacion_no_disponible"
                  }
                }
              }
            }
          },
          "502": {
            "description": "`servicio_externo_no_disponible`: SUNAT, el BCRP o el proveedor de mensajería no respondió. Revisa el estado antes de reenviar.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "servicio_externo_no_disponible": {
                    "$ref": "#/components/examples/servicio_externo_no_disponible"
                  }
                }
              }
            }
          },
          "503": {
            "description": "`no_disponible`: El dato todavía se está cargando o actualizando de nuestro lado. Vuelve a intentar después de los segundos que indica `Retry-After`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "no_disponible": {
                    "$ref": "#/components/examples/no_disponible"
                  }
                }
              }
            }
          }
        },
        "x-nexum": {
          "permiso": "comprobantes:leer",
          "cobro": "no",
          "puede_pedir_confirmacion": false,
          "confirmacion_obligatoria": false,
          "acepta_credenciales": true,
          "idempotencia": "no_aplica",
          "herramienta_mcp": "comprobante_consultar_sunat"
        }
      }
    },
    "/v1/conecta/conexiones": {
      "post": {
        "operationId": "conexion_crear",
        "summary": "Crea una conexión de WhatsApp, Instagram o Messenger",
        "description": "Crea la conexión y devuelve `alta_url` para que una persona complete el alta con el proveedor. El proveedor es un dato de la conexión: tu integración no cambia si el número pasa de un proveedor a otro.\n\n**Permiso:** `conecta:administrar`. **Cobro:** No cobra.",
        "tags": [
          "Conexiones"
        ],
        "security": [
          {
            "claveApi": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKeyOpcional"
          },
          {
            "$ref": "#/components/parameters/RequestId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CrearConexion"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Conexión creada, pendiente de alta.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Conexion"
                }
              }
            }
          },
          "400": {
            "description": "`validacion`: Algún dato no cumple el formato. En `detalle` va cada campo con su problema.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "validacion": {
                    "$ref": "#/components/examples/validacion"
                  }
                }
              }
            }
          },
          "401": {
            "description": "`clave_invalida`: Falta la clave de API, está mal escrita, venció o fue revocada. Envíala como `Authorization: Bearer onx_live_…`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "clave_invalida": {
                    "$ref": "#/components/examples/clave_invalida"
                  }
                }
              }
            }
          },
          "403": {
            "description": "`permiso_faltante`: La clave no tiene el permiso que pide esta ruta o no tiene acceso a ese RUC.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "permiso_faltante": {
                    "$ref": "#/components/examples/permiso_faltante"
                  }
                }
              }
            }
          },
          "409": {
            "description": "`idempotencia_en_conflicto`: Usaste la misma `Idempotency-Key` con otro cuerpo. Genera una clave nueva para cada operación distinta.\n\n`solicitud_en_curso`: Ya estamos procesando una petición con esa `Idempotency-Key`. Espera unos segundos y vuelve a consultar.\n\n`ya_registrado`: Eso ya está registrado: por ejemplo, el RUC ya está en otra cuenta o la serie ya existe.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "idempotencia_en_conflicto": {
                    "$ref": "#/components/examples/idempotencia_en_conflicto"
                  },
                  "solicitud_en_curso": {
                    "$ref": "#/components/examples/solicitud_en_curso"
                  },
                  "ya_registrado": {
                    "$ref": "#/components/examples/ya_registrado"
                  }
                }
              }
            }
          },
          "429": {
            "description": "`limite_uso`: Hiciste demasiadas peticiones seguidas. Espera los segundos que indica `Retry-After` y vuelve a intentar.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "limite_uso": {
                    "$ref": "#/components/examples/limite_uso"
                  }
                }
              }
            }
          },
          "500": {
            "description": "`error_interno`: Algo falló de nuestro lado. Repite la petición con la misma `Idempotency-Key`: no se duplica nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "error_interno": {
                    "$ref": "#/components/examples/error_interno"
                  }
                }
              }
            }
          },
          "501": {
            "description": "`operacion_no_disponible`: Esta operación existe en el contrato, pero todavía no está habilitada. Revisa en la documentación qué rutas ya puedes usar; no se cobró nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "operacion_no_disponible": {
                    "$ref": "#/components/examples/operacion_no_disponible"
                  }
                }
              }
            }
          },
          "503": {
            "description": "`no_disponible`: El dato todavía se está cargando o actualizando de nuestro lado. Vuelve a intentar después de los segundos que indica `Retry-After`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "no_disponible": {
                    "$ref": "#/components/examples/no_disponible"
                  }
                }
              }
            }
          }
        },
        "x-nexum": {
          "permiso": "conecta:administrar",
          "cobro": "no",
          "puede_pedir_confirmacion": false,
          "confirmacion_obligatoria": false,
          "acepta_credenciales": false,
          "idempotencia": "opcional",
          "herramienta_mcp": "conexion_crear"
        }
      },
      "get": {
        "operationId": "conexion_listar",
        "summary": "Lista tus conexiones",
        "description": "Conexiones de la cuenta con su canal, proveedor y estado.\n\n**Permiso:** `conecta:leer`. **Cobro:** No cobra.",
        "tags": [
          "Conexiones"
        ],
        "security": [
          {
            "claveApi": []
          }
        ],
        "parameters": [
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "Cursor opaco que devolvió la página anterior en `siguiente_cursor`.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 512
            }
          },
          {
            "name": "limite",
            "in": "query",
            "required": false,
            "description": "Cuántos elementos traer (1 a 100; por defecto 20).",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100
            }
          },
          {
            "name": "canal",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "whatsapp",
                "instagram",
                "messenger"
              ]
            }
          },
          {
            "name": "estado",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "pendiente",
                "activa",
                "desconectada",
                "error"
              ]
            }
          },
          {
            "$ref": "#/components/parameters/RequestId"
          }
        ],
        "responses": {
          "200": {
            "description": "Página de conexiones.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ListaConexiones"
                }
              }
            }
          },
          "400": {
            "description": "`validacion`: Algún dato no cumple el formato. En `detalle` va cada campo con su problema.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "validacion": {
                    "$ref": "#/components/examples/validacion"
                  }
                }
              }
            }
          },
          "401": {
            "description": "`clave_invalida`: Falta la clave de API, está mal escrita, venció o fue revocada. Envíala como `Authorization: Bearer onx_live_…`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "clave_invalida": {
                    "$ref": "#/components/examples/clave_invalida"
                  }
                }
              }
            }
          },
          "403": {
            "description": "`permiso_faltante`: La clave no tiene el permiso que pide esta ruta o no tiene acceso a ese RUC.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "permiso_faltante": {
                    "$ref": "#/components/examples/permiso_faltante"
                  }
                }
              }
            }
          },
          "429": {
            "description": "`limite_uso`: Hiciste demasiadas peticiones seguidas. Espera los segundos que indica `Retry-After` y vuelve a intentar.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "limite_uso": {
                    "$ref": "#/components/examples/limite_uso"
                  }
                }
              }
            }
          },
          "500": {
            "description": "`error_interno`: Algo falló de nuestro lado. Repite la petición con la misma `Idempotency-Key`: no se duplica nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "error_interno": {
                    "$ref": "#/components/examples/error_interno"
                  }
                }
              }
            }
          },
          "501": {
            "description": "`operacion_no_disponible`: Esta operación existe en el contrato, pero todavía no está habilitada. Revisa en la documentación qué rutas ya puedes usar; no se cobró nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "operacion_no_disponible": {
                    "$ref": "#/components/examples/operacion_no_disponible"
                  }
                }
              }
            }
          },
          "503": {
            "description": "`no_disponible`: El dato todavía se está cargando o actualizando de nuestro lado. Vuelve a intentar después de los segundos que indica `Retry-After`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "no_disponible": {
                    "$ref": "#/components/examples/no_disponible"
                  }
                }
              }
            }
          }
        },
        "x-nexum": {
          "permiso": "conecta:leer",
          "cobro": "no",
          "puede_pedir_confirmacion": false,
          "confirmacion_obligatoria": false,
          "acepta_credenciales": false,
          "idempotencia": "no_aplica",
          "herramienta_mcp": "conexion_listar"
        }
      }
    },
    "/v1/conecta/conexiones/{id}": {
      "get": {
        "operationId": "conexion_ver",
        "summary": "Consulta una conexión",
        "description": "Estado de una conexión y, si está pendiente, su enlace de alta.\n\n**Permiso:** `conecta:leer`. **Cobro:** No cobra.",
        "tags": [
          "Conexiones"
        ],
        "security": [
          {
            "claveApi": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Identificador que empieza con `con_`.",
            "schema": {
              "type": "string",
              "pattern": "^con_[A-Za-z0-9]{8,64}$",
              "examples": [
                "con_8f2c1a7d9e"
              ]
            }
          },
          {
            "$ref": "#/components/parameters/RequestId"
          }
        ],
        "responses": {
          "200": {
            "description": "Conexión.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Conexion"
                }
              }
            }
          },
          "400": {
            "description": "`validacion`: Algún dato no cumple el formato. En `detalle` va cada campo con su problema.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "validacion": {
                    "$ref": "#/components/examples/validacion"
                  }
                }
              }
            }
          },
          "401": {
            "description": "`clave_invalida`: Falta la clave de API, está mal escrita, venció o fue revocada. Envíala como `Authorization: Bearer onx_live_…`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "clave_invalida": {
                    "$ref": "#/components/examples/clave_invalida"
                  }
                }
              }
            }
          },
          "403": {
            "description": "`permiso_faltante`: La clave no tiene el permiso que pide esta ruta o no tiene acceso a ese RUC.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "permiso_faltante": {
                    "$ref": "#/components/examples/permiso_faltante"
                  }
                }
              }
            }
          },
          "404": {
            "description": "`no_encontrado`: No existe o no pertenece a tu cuenta.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "no_encontrado": {
                    "$ref": "#/components/examples/no_encontrado"
                  }
                }
              }
            }
          },
          "429": {
            "description": "`limite_uso`: Hiciste demasiadas peticiones seguidas. Espera los segundos que indica `Retry-After` y vuelve a intentar.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "limite_uso": {
                    "$ref": "#/components/examples/limite_uso"
                  }
                }
              }
            }
          },
          "500": {
            "description": "`error_interno`: Algo falló de nuestro lado. Repite la petición con la misma `Idempotency-Key`: no se duplica nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "error_interno": {
                    "$ref": "#/components/examples/error_interno"
                  }
                }
              }
            }
          },
          "501": {
            "description": "`operacion_no_disponible`: Esta operación existe en el contrato, pero todavía no está habilitada. Revisa en la documentación qué rutas ya puedes usar; no se cobró nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "operacion_no_disponible": {
                    "$ref": "#/components/examples/operacion_no_disponible"
                  }
                }
              }
            }
          },
          "503": {
            "description": "`no_disponible`: El dato todavía se está cargando o actualizando de nuestro lado. Vuelve a intentar después de los segundos que indica `Retry-After`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "no_disponible": {
                    "$ref": "#/components/examples/no_disponible"
                  }
                }
              }
            }
          }
        },
        "x-nexum": {
          "permiso": "conecta:leer",
          "cobro": "no",
          "puede_pedir_confirmacion": false,
          "confirmacion_obligatoria": false,
          "acepta_credenciales": false,
          "idempotencia": "no_aplica",
          "herramienta_mcp": "conexion_ver"
        }
      },
      "delete": {
        "operationId": "conexion_borrar",
        "summary": "Borra una conexión",
        "description": "Desconecta el número o la cuenta. Las conversaciones quedan guardadas para consulta. Según tu clave, puede esperar la aprobación de una persona.\n\n**Permiso:** `conecta:administrar`. **Cobro:** No cobra.\n\n**Puede pedir aprobación humana** según tu clave (202 `requiere_confirmacion`).",
        "tags": [
          "Conexiones"
        ],
        "security": [
          {
            "claveApi": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Identificador que empieza con `con_`.",
            "schema": {
              "type": "string",
              "pattern": "^con_[A-Za-z0-9]{8,64}$",
              "examples": [
                "con_8f2c1a7d9e"
              ]
            }
          },
          {
            "$ref": "#/components/parameters/RequestId"
          }
        ],
        "responses": {
          "200": {
            "description": "Conexión desconectada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Conexion"
                }
              }
            }
          },
          "202": {
            "description": "Espera la aprobación de una persona.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RespuestaRequiereConfirmacion"
                }
              }
            }
          },
          "400": {
            "description": "`validacion`: Algún dato no cumple el formato. En `detalle` va cada campo con su problema.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "validacion": {
                    "$ref": "#/components/examples/validacion"
                  }
                }
              }
            }
          },
          "401": {
            "description": "`clave_invalida`: Falta la clave de API, está mal escrita, venció o fue revocada. Envíala como `Authorization: Bearer onx_live_…`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "clave_invalida": {
                    "$ref": "#/components/examples/clave_invalida"
                  }
                }
              }
            }
          },
          "403": {
            "description": "`permiso_faltante`: La clave no tiene el permiso que pide esta ruta o no tiene acceso a ese RUC.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "permiso_faltante": {
                    "$ref": "#/components/examples/permiso_faltante"
                  }
                }
              }
            }
          },
          "404": {
            "description": "`no_encontrado`: No existe o no pertenece a tu cuenta.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "no_encontrado": {
                    "$ref": "#/components/examples/no_encontrado"
                  }
                }
              }
            }
          },
          "429": {
            "description": "`limite_uso`: Hiciste demasiadas peticiones seguidas. Espera los segundos que indica `Retry-After` y vuelve a intentar.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "limite_uso": {
                    "$ref": "#/components/examples/limite_uso"
                  }
                }
              }
            }
          },
          "500": {
            "description": "`error_interno`: Algo falló de nuestro lado. Repite la petición con la misma `Idempotency-Key`: no se duplica nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "error_interno": {
                    "$ref": "#/components/examples/error_interno"
                  }
                }
              }
            }
          },
          "501": {
            "description": "`operacion_no_disponible`: Esta operación existe en el contrato, pero todavía no está habilitada. Revisa en la documentación qué rutas ya puedes usar; no se cobró nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "operacion_no_disponible": {
                    "$ref": "#/components/examples/operacion_no_disponible"
                  }
                }
              }
            }
          },
          "503": {
            "description": "`no_disponible`: El dato todavía se está cargando o actualizando de nuestro lado. Vuelve a intentar después de los segundos que indica `Retry-After`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "no_disponible": {
                    "$ref": "#/components/examples/no_disponible"
                  }
                }
              }
            }
          }
        },
        "x-nexum": {
          "permiso": "conecta:administrar",
          "cobro": "no",
          "puede_pedir_confirmacion": true,
          "confirmacion_obligatoria": false,
          "acepta_credenciales": false,
          "idempotencia": "no_aplica",
          "herramienta_mcp": "conexion_borrar"
        }
      }
    },
    "/v1/conecta/conexiones/{id}/probar": {
      "post": {
        "operationId": "conexion_probar",
        "summary": "Prueba una conexión",
        "description": "Verifica con el proveedor que la conexión funciona. No envía mensajes a nadie.\n\n**Permiso:** `conecta:leer`. **Cobro:** No cobra.",
        "tags": [
          "Conexiones"
        ],
        "security": [
          {
            "claveApi": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Identificador que empieza con `con_`.",
            "schema": {
              "type": "string",
              "pattern": "^con_[A-Za-z0-9]{8,64}$",
              "examples": [
                "con_8f2c1a7d9e"
              ]
            }
          },
          {
            "$ref": "#/components/parameters/RequestId"
          }
        ],
        "responses": {
          "200": {
            "description": "Resultado de la prueba.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResultadoPrueba"
                }
              }
            }
          },
          "400": {
            "description": "`validacion`: Algún dato no cumple el formato. En `detalle` va cada campo con su problema.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "validacion": {
                    "$ref": "#/components/examples/validacion"
                  }
                }
              }
            }
          },
          "401": {
            "description": "`clave_invalida`: Falta la clave de API, está mal escrita, venció o fue revocada. Envíala como `Authorization: Bearer onx_live_…`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "clave_invalida": {
                    "$ref": "#/components/examples/clave_invalida"
                  }
                }
              }
            }
          },
          "403": {
            "description": "`permiso_faltante`: La clave no tiene el permiso que pide esta ruta o no tiene acceso a ese RUC.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "permiso_faltante": {
                    "$ref": "#/components/examples/permiso_faltante"
                  }
                }
              }
            }
          },
          "404": {
            "description": "`no_encontrado`: No existe o no pertenece a tu cuenta.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "no_encontrado": {
                    "$ref": "#/components/examples/no_encontrado"
                  }
                }
              }
            }
          },
          "429": {
            "description": "`limite_uso`: Hiciste demasiadas peticiones seguidas. Espera los segundos que indica `Retry-After` y vuelve a intentar.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "limite_uso": {
                    "$ref": "#/components/examples/limite_uso"
                  }
                }
              }
            }
          },
          "500": {
            "description": "`error_interno`: Algo falló de nuestro lado. Repite la petición con la misma `Idempotency-Key`: no se duplica nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "error_interno": {
                    "$ref": "#/components/examples/error_interno"
                  }
                }
              }
            }
          },
          "501": {
            "description": "`operacion_no_disponible`: Esta operación existe en el contrato, pero todavía no está habilitada. Revisa en la documentación qué rutas ya puedes usar; no se cobró nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "operacion_no_disponible": {
                    "$ref": "#/components/examples/operacion_no_disponible"
                  }
                }
              }
            }
          },
          "502": {
            "description": "`servicio_externo_no_disponible`: SUNAT, el BCRP o el proveedor de mensajería no respondió. Revisa el estado antes de reenviar.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "servicio_externo_no_disponible": {
                    "$ref": "#/components/examples/servicio_externo_no_disponible"
                  }
                }
              }
            }
          },
          "503": {
            "description": "`no_disponible`: El dato todavía se está cargando o actualizando de nuestro lado. Vuelve a intentar después de los segundos que indica `Retry-After`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "no_disponible": {
                    "$ref": "#/components/examples/no_disponible"
                  }
                }
              }
            }
          }
        },
        "x-nexum": {
          "permiso": "conecta:leer",
          "cobro": "no",
          "puede_pedir_confirmacion": false,
          "confirmacion_obligatoria": false,
          "acepta_credenciales": false,
          "idempotencia": "no_aplica",
          "herramienta_mcp": "conexion_probar"
        }
      }
    },
    "/v1/conecta/mensajes": {
      "post": {
        "operationId": "mensaje_enviar",
        "summary": "Envía un mensaje",
        "description": "Envía texto, un archivo o una plantilla por la conexión indicada. Fuera de la ventana de atención solo acepta plantillas (si no, 409 `ventana_cerrada` con plantillas sugeridas). Si el proveedor no confirma, el mensaje queda `incierto` y no se reenvía solo. Los cargos de Meta por mensaje los paga tu cuenta de Meta.\n\n**Permiso:** `conecta:enviar`. **Cobro:** No cobra.\n\n**Idempotency-Key:** obligatoria.\n\n**Puede pedir aprobación humana** según tu clave (202 `requiere_confirmacion`).",
        "tags": [
          "Mensajes"
        ],
        "security": [
          {
            "claveApi": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "$ref": "#/components/parameters/RequestId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EnviarMensaje"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Mensaje aceptado por el proveedor.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Mensaje"
                }
              }
            }
          },
          "202": {
            "description": "Espera la aprobación de una persona.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RespuestaRequiereConfirmacion"
                }
              }
            }
          },
          "400": {
            "description": "`validacion`: Algún dato no cumple el formato. En `detalle` va cada campo con su problema.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "validacion": {
                    "$ref": "#/components/examples/validacion"
                  }
                }
              }
            }
          },
          "401": {
            "description": "`clave_invalida`: Falta la clave de API, está mal escrita, venció o fue revocada. Envíala como `Authorization: Bearer onx_live_…`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "clave_invalida": {
                    "$ref": "#/components/examples/clave_invalida"
                  }
                }
              }
            }
          },
          "403": {
            "description": "`permiso_faltante`: La clave no tiene el permiso que pide esta ruta o no tiene acceso a ese RUC.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "permiso_faltante": {
                    "$ref": "#/components/examples/permiso_faltante"
                  }
                }
              }
            }
          },
          "404": {
            "description": "`no_encontrado`: No existe o no pertenece a tu cuenta.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "no_encontrado": {
                    "$ref": "#/components/examples/no_encontrado"
                  }
                }
              }
            }
          },
          "409": {
            "description": "`idempotencia_en_conflicto`: Usaste la misma `Idempotency-Key` con otro cuerpo. Genera una clave nueva para cada operación distinta.\n\n`solicitud_en_curso`: Ya estamos procesando una petición con esa `Idempotency-Key`. Espera unos segundos y vuelve a consultar.\n\n`ventana_cerrada`: La conversación está fuera de la ventana de atención: solo puedes escribir con una plantilla aprobada. `detalle.plantillas_sugeridas` trae opciones.\n\n`estado_no_permite`: El recurso está en un estado que no permite esta operación, por ejemplo anular un comprobante rechazado.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "idempotencia_en_conflicto": {
                    "$ref": "#/components/examples/idempotencia_en_conflicto"
                  },
                  "solicitud_en_curso": {
                    "$ref": "#/components/examples/solicitud_en_curso"
                  },
                  "ventana_cerrada": {
                    "$ref": "#/components/examples/ventana_cerrada"
                  },
                  "estado_no_permite": {
                    "$ref": "#/components/examples/estado_no_permite"
                  }
                }
              }
            }
          },
          "429": {
            "description": "`limite_uso`: Hiciste demasiadas peticiones seguidas. Espera los segundos que indica `Retry-After` y vuelve a intentar.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "limite_uso": {
                    "$ref": "#/components/examples/limite_uso"
                  }
                }
              }
            }
          },
          "500": {
            "description": "`error_interno`: Algo falló de nuestro lado. Repite la petición con la misma `Idempotency-Key`: no se duplica nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "error_interno": {
                    "$ref": "#/components/examples/error_interno"
                  }
                }
              }
            }
          },
          "501": {
            "description": "`operacion_no_disponible`: Esta operación existe en el contrato, pero todavía no está habilitada. Revisa en la documentación qué rutas ya puedes usar; no se cobró nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "operacion_no_disponible": {
                    "$ref": "#/components/examples/operacion_no_disponible"
                  }
                }
              }
            }
          },
          "502": {
            "description": "`servicio_externo_no_disponible`: SUNAT, el BCRP o el proveedor de mensajería no respondió. Revisa el estado antes de reenviar.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "servicio_externo_no_disponible": {
                    "$ref": "#/components/examples/servicio_externo_no_disponible"
                  }
                }
              }
            }
          },
          "503": {
            "description": "`no_disponible`: El dato todavía se está cargando o actualizando de nuestro lado. Vuelve a intentar después de los segundos que indica `Retry-After`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "no_disponible": {
                    "$ref": "#/components/examples/no_disponible"
                  }
                }
              }
            }
          }
        },
        "x-nexum": {
          "permiso": "conecta:enviar",
          "cobro": "no",
          "puede_pedir_confirmacion": true,
          "confirmacion_obligatoria": false,
          "acepta_credenciales": false,
          "idempotencia": "requerida",
          "herramienta_mcp": "mensaje_enviar"
        }
      }
    },
    "/v1/conecta/mensajes/{id}": {
      "get": {
        "operationId": "mensaje_ver",
        "summary": "Consulta un mensaje",
        "description": "Estado de entrega de un mensaje enviado o detalle de uno recibido.\n\n**Permiso:** `conecta:leer`. **Cobro:** No cobra.",
        "tags": [
          "Mensajes"
        ],
        "security": [
          {
            "claveApi": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Identificador que empieza con `msg_`.",
            "schema": {
              "type": "string",
              "pattern": "^msg_[A-Za-z0-9]{8,64}$",
              "examples": [
                "msg_8f2c1a7d9e"
              ]
            }
          },
          {
            "$ref": "#/components/parameters/RequestId"
          }
        ],
        "responses": {
          "200": {
            "description": "Mensaje.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Mensaje"
                }
              }
            }
          },
          "400": {
            "description": "`validacion`: Algún dato no cumple el formato. En `detalle` va cada campo con su problema.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "validacion": {
                    "$ref": "#/components/examples/validacion"
                  }
                }
              }
            }
          },
          "401": {
            "description": "`clave_invalida`: Falta la clave de API, está mal escrita, venció o fue revocada. Envíala como `Authorization: Bearer onx_live_…`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "clave_invalida": {
                    "$ref": "#/components/examples/clave_invalida"
                  }
                }
              }
            }
          },
          "403": {
            "description": "`permiso_faltante`: La clave no tiene el permiso que pide esta ruta o no tiene acceso a ese RUC.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "permiso_faltante": {
                    "$ref": "#/components/examples/permiso_faltante"
                  }
                }
              }
            }
          },
          "404": {
            "description": "`no_encontrado`: No existe o no pertenece a tu cuenta.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "no_encontrado": {
                    "$ref": "#/components/examples/no_encontrado"
                  }
                }
              }
            }
          },
          "429": {
            "description": "`limite_uso`: Hiciste demasiadas peticiones seguidas. Espera los segundos que indica `Retry-After` y vuelve a intentar.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "limite_uso": {
                    "$ref": "#/components/examples/limite_uso"
                  }
                }
              }
            }
          },
          "500": {
            "description": "`error_interno`: Algo falló de nuestro lado. Repite la petición con la misma `Idempotency-Key`: no se duplica nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "error_interno": {
                    "$ref": "#/components/examples/error_interno"
                  }
                }
              }
            }
          },
          "501": {
            "description": "`operacion_no_disponible`: Esta operación existe en el contrato, pero todavía no está habilitada. Revisa en la documentación qué rutas ya puedes usar; no se cobró nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "operacion_no_disponible": {
                    "$ref": "#/components/examples/operacion_no_disponible"
                  }
                }
              }
            }
          },
          "503": {
            "description": "`no_disponible`: El dato todavía se está cargando o actualizando de nuestro lado. Vuelve a intentar después de los segundos que indica `Retry-After`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "no_disponible": {
                    "$ref": "#/components/examples/no_disponible"
                  }
                }
              }
            }
          }
        },
        "x-nexum": {
          "permiso": "conecta:leer",
          "cobro": "no",
          "puede_pedir_confirmacion": false,
          "confirmacion_obligatoria": false,
          "acepta_credenciales": false,
          "idempotencia": "no_aplica",
          "herramienta_mcp": "mensaje_ver"
        }
      }
    },
    "/v1/conecta/conversaciones": {
      "get": {
        "operationId": "conversacion_listar",
        "summary": "Lista conversaciones",
        "description": "Bandeja de WhatsApp, Instagram y Messenger, con la ventana de atención de cada conversación.\n\n**Permiso:** `conecta:leer`. **Cobro:** No cobra.",
        "tags": [
          "Mensajes"
        ],
        "security": [
          {
            "claveApi": []
          }
        ],
        "parameters": [
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "Cursor opaco que devolvió la página anterior en `siguiente_cursor`.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 512
            }
          },
          {
            "name": "limite",
            "in": "query",
            "required": false,
            "description": "Cuántos elementos traer (1 a 100; por defecto 20).",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100
            }
          },
          {
            "name": "conexion_id",
            "in": "query",
            "required": false,
            "description": "Identificador que empieza con `con_`.",
            "schema": {
              "type": "string",
              "pattern": "^con_[A-Za-z0-9]{8,64}$",
              "examples": [
                "con_8f2c1a7d9e"
              ]
            }
          },
          {
            "name": "canal",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "whatsapp",
                "instagram",
                "messenger"
              ]
            }
          },
          {
            "$ref": "#/components/parameters/RequestId"
          }
        ],
        "responses": {
          "200": {
            "description": "Página de conversaciones.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ListaConversaciones"
                }
              }
            }
          },
          "400": {
            "description": "`validacion`: Algún dato no cumple el formato. En `detalle` va cada campo con su problema.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "validacion": {
                    "$ref": "#/components/examples/validacion"
                  }
                }
              }
            }
          },
          "401": {
            "description": "`clave_invalida`: Falta la clave de API, está mal escrita, venció o fue revocada. Envíala como `Authorization: Bearer onx_live_…`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "clave_invalida": {
                    "$ref": "#/components/examples/clave_invalida"
                  }
                }
              }
            }
          },
          "403": {
            "description": "`permiso_faltante`: La clave no tiene el permiso que pide esta ruta o no tiene acceso a ese RUC.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "permiso_faltante": {
                    "$ref": "#/components/examples/permiso_faltante"
                  }
                }
              }
            }
          },
          "429": {
            "description": "`limite_uso`: Hiciste demasiadas peticiones seguidas. Espera los segundos que indica `Retry-After` y vuelve a intentar.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "limite_uso": {
                    "$ref": "#/components/examples/limite_uso"
                  }
                }
              }
            }
          },
          "500": {
            "description": "`error_interno`: Algo falló de nuestro lado. Repite la petición con la misma `Idempotency-Key`: no se duplica nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "error_interno": {
                    "$ref": "#/components/examples/error_interno"
                  }
                }
              }
            }
          },
          "501": {
            "description": "`operacion_no_disponible`: Esta operación existe en el contrato, pero todavía no está habilitada. Revisa en la documentación qué rutas ya puedes usar; no se cobró nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "operacion_no_disponible": {
                    "$ref": "#/components/examples/operacion_no_disponible"
                  }
                }
              }
            }
          },
          "503": {
            "description": "`no_disponible`: El dato todavía se está cargando o actualizando de nuestro lado. Vuelve a intentar después de los segundos que indica `Retry-After`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "no_disponible": {
                    "$ref": "#/components/examples/no_disponible"
                  }
                }
              }
            }
          }
        },
        "x-nexum": {
          "permiso": "conecta:leer",
          "cobro": "no",
          "puede_pedir_confirmacion": false,
          "confirmacion_obligatoria": false,
          "acepta_credenciales": false,
          "idempotencia": "no_aplica",
          "herramienta_mcp": "conversacion_listar"
        }
      }
    },
    "/v1/conecta/conversaciones/{id}": {
      "get": {
        "operationId": "conversacion_ver",
        "summary": "Consulta una conversación",
        "description": "Contacto, ventana de atención y mensajes sin leer de una conversación.\n\n**Permiso:** `conecta:leer`. **Cobro:** No cobra.",
        "tags": [
          "Mensajes"
        ],
        "security": [
          {
            "claveApi": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Identificador que empieza con `cnv_`.",
            "schema": {
              "type": "string",
              "pattern": "^cnv_[A-Za-z0-9]{8,64}$",
              "examples": [
                "cnv_8f2c1a7d9e"
              ]
            }
          },
          {
            "$ref": "#/components/parameters/RequestId"
          }
        ],
        "responses": {
          "200": {
            "description": "Conversación.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Conversacion"
                }
              }
            }
          },
          "400": {
            "description": "`validacion`: Algún dato no cumple el formato. En `detalle` va cada campo con su problema.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "validacion": {
                    "$ref": "#/components/examples/validacion"
                  }
                }
              }
            }
          },
          "401": {
            "description": "`clave_invalida`: Falta la clave de API, está mal escrita, venció o fue revocada. Envíala como `Authorization: Bearer onx_live_…`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "clave_invalida": {
                    "$ref": "#/components/examples/clave_invalida"
                  }
                }
              }
            }
          },
          "403": {
            "description": "`permiso_faltante`: La clave no tiene el permiso que pide esta ruta o no tiene acceso a ese RUC.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "permiso_faltante": {
                    "$ref": "#/components/examples/permiso_faltante"
                  }
                }
              }
            }
          },
          "404": {
            "description": "`no_encontrado`: No existe o no pertenece a tu cuenta.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "no_encontrado": {
                    "$ref": "#/components/examples/no_encontrado"
                  }
                }
              }
            }
          },
          "429": {
            "description": "`limite_uso`: Hiciste demasiadas peticiones seguidas. Espera los segundos que indica `Retry-After` y vuelve a intentar.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "limite_uso": {
                    "$ref": "#/components/examples/limite_uso"
                  }
                }
              }
            }
          },
          "500": {
            "description": "`error_interno`: Algo falló de nuestro lado. Repite la petición con la misma `Idempotency-Key`: no se duplica nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "error_interno": {
                    "$ref": "#/components/examples/error_interno"
                  }
                }
              }
            }
          },
          "501": {
            "description": "`operacion_no_disponible`: Esta operación existe en el contrato, pero todavía no está habilitada. Revisa en la documentación qué rutas ya puedes usar; no se cobró nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "operacion_no_disponible": {
                    "$ref": "#/components/examples/operacion_no_disponible"
                  }
                }
              }
            }
          },
          "503": {
            "description": "`no_disponible`: El dato todavía se está cargando o actualizando de nuestro lado. Vuelve a intentar después de los segundos que indica `Retry-After`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "no_disponible": {
                    "$ref": "#/components/examples/no_disponible"
                  }
                }
              }
            }
          }
        },
        "x-nexum": {
          "permiso": "conecta:leer",
          "cobro": "no",
          "puede_pedir_confirmacion": false,
          "confirmacion_obligatoria": false,
          "acepta_credenciales": false,
          "idempotencia": "no_aplica",
          "herramienta_mcp": "conversacion_ver"
        }
      }
    },
    "/v1/conecta/conversaciones/{id}/mensajes": {
      "get": {
        "operationId": "conversacion_mensajes",
        "summary": "Lista los mensajes de una conversación",
        "description": "Mensajes enviados y recibidos, del más reciente al más antiguo.\n\n**Permiso:** `conecta:leer`. **Cobro:** No cobra.",
        "tags": [
          "Mensajes"
        ],
        "security": [
          {
            "claveApi": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Identificador que empieza con `cnv_`.",
            "schema": {
              "type": "string",
              "pattern": "^cnv_[A-Za-z0-9]{8,64}$",
              "examples": [
                "cnv_8f2c1a7d9e"
              ]
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "Cursor opaco que devolvió la página anterior en `siguiente_cursor`.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 512
            }
          },
          {
            "name": "limite",
            "in": "query",
            "required": false,
            "description": "Cuántos elementos traer (1 a 100; por defecto 20).",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100
            }
          },
          {
            "$ref": "#/components/parameters/RequestId"
          }
        ],
        "responses": {
          "200": {
            "description": "Página de mensajes.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ListaMensajes"
                }
              }
            }
          },
          "400": {
            "description": "`validacion`: Algún dato no cumple el formato. En `detalle` va cada campo con su problema.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "validacion": {
                    "$ref": "#/components/examples/validacion"
                  }
                }
              }
            }
          },
          "401": {
            "description": "`clave_invalida`: Falta la clave de API, está mal escrita, venció o fue revocada. Envíala como `Authorization: Bearer onx_live_…`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "clave_invalida": {
                    "$ref": "#/components/examples/clave_invalida"
                  }
                }
              }
            }
          },
          "403": {
            "description": "`permiso_faltante`: La clave no tiene el permiso que pide esta ruta o no tiene acceso a ese RUC.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "permiso_faltante": {
                    "$ref": "#/components/examples/permiso_faltante"
                  }
                }
              }
            }
          },
          "404": {
            "description": "`no_encontrado`: No existe o no pertenece a tu cuenta.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "no_encontrado": {
                    "$ref": "#/components/examples/no_encontrado"
                  }
                }
              }
            }
          },
          "429": {
            "description": "`limite_uso`: Hiciste demasiadas peticiones seguidas. Espera los segundos que indica `Retry-After` y vuelve a intentar.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "limite_uso": {
                    "$ref": "#/components/examples/limite_uso"
                  }
                }
              }
            }
          },
          "500": {
            "description": "`error_interno`: Algo falló de nuestro lado. Repite la petición con la misma `Idempotency-Key`: no se duplica nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "error_interno": {
                    "$ref": "#/components/examples/error_interno"
                  }
                }
              }
            }
          },
          "501": {
            "description": "`operacion_no_disponible`: Esta operación existe en el contrato, pero todavía no está habilitada. Revisa en la documentación qué rutas ya puedes usar; no se cobró nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "operacion_no_disponible": {
                    "$ref": "#/components/examples/operacion_no_disponible"
                  }
                }
              }
            }
          },
          "503": {
            "description": "`no_disponible`: El dato todavía se está cargando o actualizando de nuestro lado. Vuelve a intentar después de los segundos que indica `Retry-After`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "no_disponible": {
                    "$ref": "#/components/examples/no_disponible"
                  }
                }
              }
            }
          }
        },
        "x-nexum": {
          "permiso": "conecta:leer",
          "cobro": "no",
          "puede_pedir_confirmacion": false,
          "confirmacion_obligatoria": false,
          "acepta_credenciales": false,
          "idempotencia": "no_aplica",
          "herramienta_mcp": "conversacion_mensajes"
        }
      }
    },
    "/v1/conecta/plantillas": {
      "get": {
        "operationId": "plantilla_listar",
        "summary": "Lista plantillas",
        "description": "Plantillas de mensaje por conexión, con su estado de revisión.\n\n**Permiso:** `conecta:leer`. **Cobro:** No cobra.",
        "tags": [
          "Plantillas"
        ],
        "security": [
          {
            "claveApi": []
          }
        ],
        "parameters": [
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "Cursor opaco que devolvió la página anterior en `siguiente_cursor`.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 512
            }
          },
          {
            "name": "limite",
            "in": "query",
            "required": false,
            "description": "Cuántos elementos traer (1 a 100; por defecto 20).",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100
            }
          },
          {
            "name": "conexion_id",
            "in": "query",
            "required": false,
            "description": "Identificador que empieza con `con_`.",
            "schema": {
              "type": "string",
              "pattern": "^con_[A-Za-z0-9]{8,64}$",
              "examples": [
                "con_8f2c1a7d9e"
              ]
            }
          },
          {
            "name": "estado",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "pendiente",
                "aprobada",
                "rechazada",
                "pausada",
                "deshabilitada"
              ]
            }
          },
          {
            "$ref": "#/components/parameters/RequestId"
          }
        ],
        "responses": {
          "200": {
            "description": "Página de plantillas.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ListaPlantillas"
                }
              }
            }
          },
          "400": {
            "description": "`validacion`: Algún dato no cumple el formato. En `detalle` va cada campo con su problema.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "validacion": {
                    "$ref": "#/components/examples/validacion"
                  }
                }
              }
            }
          },
          "401": {
            "description": "`clave_invalida`: Falta la clave de API, está mal escrita, venció o fue revocada. Envíala como `Authorization: Bearer onx_live_…`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "clave_invalida": {
                    "$ref": "#/components/examples/clave_invalida"
                  }
                }
              }
            }
          },
          "403": {
            "description": "`permiso_faltante`: La clave no tiene el permiso que pide esta ruta o no tiene acceso a ese RUC.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "permiso_faltante": {
                    "$ref": "#/components/examples/permiso_faltante"
                  }
                }
              }
            }
          },
          "429": {
            "description": "`limite_uso`: Hiciste demasiadas peticiones seguidas. Espera los segundos que indica `Retry-After` y vuelve a intentar.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "limite_uso": {
                    "$ref": "#/components/examples/limite_uso"
                  }
                }
              }
            }
          },
          "500": {
            "description": "`error_interno`: Algo falló de nuestro lado. Repite la petición con la misma `Idempotency-Key`: no se duplica nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "error_interno": {
                    "$ref": "#/components/examples/error_interno"
                  }
                }
              }
            }
          },
          "501": {
            "description": "`operacion_no_disponible`: Esta operación existe en el contrato, pero todavía no está habilitada. Revisa en la documentación qué rutas ya puedes usar; no se cobró nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "operacion_no_disponible": {
                    "$ref": "#/components/examples/operacion_no_disponible"
                  }
                }
              }
            }
          },
          "503": {
            "description": "`no_disponible`: El dato todavía se está cargando o actualizando de nuestro lado. Vuelve a intentar después de los segundos que indica `Retry-After`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "no_disponible": {
                    "$ref": "#/components/examples/no_disponible"
                  }
                }
              }
            }
          }
        },
        "x-nexum": {
          "permiso": "conecta:leer",
          "cobro": "no",
          "puede_pedir_confirmacion": false,
          "confirmacion_obligatoria": false,
          "acepta_credenciales": false,
          "idempotencia": "no_aplica",
          "herramienta_mcp": "plantilla_listar"
        }
      },
      "post": {
        "operationId": "plantilla_crear",
        "summary": "Crea una plantilla",
        "description": "Crea una plantilla y la manda a revisión. Te avisamos con el evento `plantilla.estado`.\n\n**Permiso:** `conecta:administrar`. **Cobro:** No cobra.",
        "tags": [
          "Plantillas"
        ],
        "security": [
          {
            "claveApi": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKeyOpcional"
          },
          {
            "$ref": "#/components/parameters/RequestId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CrearPlantilla"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Plantilla creada, pendiente de revisión.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Plantilla"
                }
              }
            }
          },
          "400": {
            "description": "`validacion`: Algún dato no cumple el formato. En `detalle` va cada campo con su problema.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "validacion": {
                    "$ref": "#/components/examples/validacion"
                  }
                }
              }
            }
          },
          "401": {
            "description": "`clave_invalida`: Falta la clave de API, está mal escrita, venció o fue revocada. Envíala como `Authorization: Bearer onx_live_…`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "clave_invalida": {
                    "$ref": "#/components/examples/clave_invalida"
                  }
                }
              }
            }
          },
          "403": {
            "description": "`permiso_faltante`: La clave no tiene el permiso que pide esta ruta o no tiene acceso a ese RUC.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "permiso_faltante": {
                    "$ref": "#/components/examples/permiso_faltante"
                  }
                }
              }
            }
          },
          "404": {
            "description": "`no_encontrado`: No existe o no pertenece a tu cuenta.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "no_encontrado": {
                    "$ref": "#/components/examples/no_encontrado"
                  }
                }
              }
            }
          },
          "409": {
            "description": "`idempotencia_en_conflicto`: Usaste la misma `Idempotency-Key` con otro cuerpo. Genera una clave nueva para cada operación distinta.\n\n`solicitud_en_curso`: Ya estamos procesando una petición con esa `Idempotency-Key`. Espera unos segundos y vuelve a consultar.\n\n`ya_registrado`: Eso ya está registrado: por ejemplo, el RUC ya está en otra cuenta o la serie ya existe.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "idempotencia_en_conflicto": {
                    "$ref": "#/components/examples/idempotencia_en_conflicto"
                  },
                  "solicitud_en_curso": {
                    "$ref": "#/components/examples/solicitud_en_curso"
                  },
                  "ya_registrado": {
                    "$ref": "#/components/examples/ya_registrado"
                  }
                }
              }
            }
          },
          "429": {
            "description": "`limite_uso`: Hiciste demasiadas peticiones seguidas. Espera los segundos que indica `Retry-After` y vuelve a intentar.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "limite_uso": {
                    "$ref": "#/components/examples/limite_uso"
                  }
                }
              }
            }
          },
          "500": {
            "description": "`error_interno`: Algo falló de nuestro lado. Repite la petición con la misma `Idempotency-Key`: no se duplica nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "error_interno": {
                    "$ref": "#/components/examples/error_interno"
                  }
                }
              }
            }
          },
          "501": {
            "description": "`operacion_no_disponible`: Esta operación existe en el contrato, pero todavía no está habilitada. Revisa en la documentación qué rutas ya puedes usar; no se cobró nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "operacion_no_disponible": {
                    "$ref": "#/components/examples/operacion_no_disponible"
                  }
                }
              }
            }
          },
          "502": {
            "description": "`servicio_externo_no_disponible`: SUNAT, el BCRP o el proveedor de mensajería no respondió. Revisa el estado antes de reenviar.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "servicio_externo_no_disponible": {
                    "$ref": "#/components/examples/servicio_externo_no_disponible"
                  }
                }
              }
            }
          },
          "503": {
            "description": "`no_disponible`: El dato todavía se está cargando o actualizando de nuestro lado. Vuelve a intentar después de los segundos que indica `Retry-After`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "no_disponible": {
                    "$ref": "#/components/examples/no_disponible"
                  }
                }
              }
            }
          }
        },
        "x-nexum": {
          "permiso": "conecta:administrar",
          "cobro": "no",
          "puede_pedir_confirmacion": false,
          "confirmacion_obligatoria": false,
          "acepta_credenciales": false,
          "idempotencia": "opcional",
          "herramienta_mcp": "plantilla_crear"
        }
      }
    },
    "/v1/conecta/comprobantes/enviar": {
      "post": {
        "operationId": "comprobante_enviar",
        "summary": "Envía un comprobante por mensaje",
        "description": "Envía el PDF de un comprobante de tu cuenta (aceptado u observado) por WhatsApp. Dentro de la ventana de atención va como documento con un texto corto (serie, número y total, o el tuyo). Fuera de ella usamos una plantilla de utilidad aprobada de la conexión con un documento en el encabezado (la que indiques o la que encontremos); si no hay una, o la conexión es de Zernio, responde 409 `ventana_cerrada` con `detalle.plantilla_faltante`: qué falta y el texto sugerido para registrarla en Meta. Un resultado `incierto` no se reenvía solo. Reserva el precio y lo cobra solo si se envía.\n\n**Permiso:** `conecta:enviar`. **Cobro:** Reserva el precio del saldo y lo cobra solo si el servicio confirma.\n\n**Idempotency-Key:** obligatoria.\n\n**Puede pedir aprobación humana** según tu clave (202 `requiere_confirmacion`).",
        "tags": [
          "Mensajes"
        ],
        "security": [
          {
            "claveApi": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "$ref": "#/components/parameters/RequestId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EnviarComprobante"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Comprobante enviado.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Mensaje"
                }
              }
            }
          },
          "202": {
            "description": "Espera la aprobación de una persona.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RespuestaRequiereConfirmacion"
                }
              }
            }
          },
          "400": {
            "description": "`validacion`: Algún dato no cumple el formato. En `detalle` va cada campo con su problema.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "validacion": {
                    "$ref": "#/components/examples/validacion"
                  }
                }
              }
            }
          },
          "401": {
            "description": "`clave_invalida`: Falta la clave de API, está mal escrita, venció o fue revocada. Envíala como `Authorization: Bearer onx_live_…`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "clave_invalida": {
                    "$ref": "#/components/examples/clave_invalida"
                  }
                }
              }
            }
          },
          "402": {
            "description": "`saldo_insuficiente`: No te alcanza el saldo para esta operación. Pásale `recarga_url` a una persona de tu cuenta para que recargue.\n\n`tope_alcanzado`: La clave llegó a su tope de gasto del periodo. Una persona de tu cuenta puede subirlo desde el panel.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error402"
                },
                "examples": {
                  "saldo_insuficiente": {
                    "$ref": "#/components/examples/saldo_insuficiente"
                  },
                  "tope_alcanzado": {
                    "$ref": "#/components/examples/tope_alcanzado"
                  }
                }
              }
            }
          },
          "403": {
            "description": "`permiso_faltante`: La clave no tiene el permiso que pide esta ruta o no tiene acceso a ese RUC.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "permiso_faltante": {
                    "$ref": "#/components/examples/permiso_faltante"
                  }
                }
              }
            }
          },
          "404": {
            "description": "`no_encontrado`: No existe o no pertenece a tu cuenta.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "no_encontrado": {
                    "$ref": "#/components/examples/no_encontrado"
                  }
                }
              }
            }
          },
          "409": {
            "description": "`idempotencia_en_conflicto`: Usaste la misma `Idempotency-Key` con otro cuerpo. Genera una clave nueva para cada operación distinta.\n\n`solicitud_en_curso`: Ya estamos procesando una petición con esa `Idempotency-Key`. Espera unos segundos y vuelve a consultar.\n\n`ventana_cerrada`: La conversación está fuera de la ventana de atención: solo puedes escribir con una plantilla aprobada. `detalle.plantillas_sugeridas` trae opciones.\n\n`estado_no_permite`: El recurso está en un estado que no permite esta operación, por ejemplo anular un comprobante rechazado.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "idempotencia_en_conflicto": {
                    "$ref": "#/components/examples/idempotencia_en_conflicto"
                  },
                  "solicitud_en_curso": {
                    "$ref": "#/components/examples/solicitud_en_curso"
                  },
                  "ventana_cerrada": {
                    "$ref": "#/components/examples/ventana_cerrada"
                  },
                  "estado_no_permite": {
                    "$ref": "#/components/examples/estado_no_permite"
                  }
                }
              }
            }
          },
          "429": {
            "description": "`limite_uso`: Hiciste demasiadas peticiones seguidas. Espera los segundos que indica `Retry-After` y vuelve a intentar.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "limite_uso": {
                    "$ref": "#/components/examples/limite_uso"
                  }
                }
              }
            }
          },
          "500": {
            "description": "`error_interno`: Algo falló de nuestro lado. Repite la petición con la misma `Idempotency-Key`: no se duplica nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "error_interno": {
                    "$ref": "#/components/examples/error_interno"
                  }
                }
              }
            }
          },
          "501": {
            "description": "`operacion_no_disponible`: Esta operación existe en el contrato, pero todavía no está habilitada. Revisa en la documentación qué rutas ya puedes usar; no se cobró nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "operacion_no_disponible": {
                    "$ref": "#/components/examples/operacion_no_disponible"
                  }
                }
              }
            }
          },
          "502": {
            "description": "`servicio_externo_no_disponible`: SUNAT, el BCRP o el proveedor de mensajería no respondió. Revisa el estado antes de reenviar.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "servicio_externo_no_disponible": {
                    "$ref": "#/components/examples/servicio_externo_no_disponible"
                  }
                }
              }
            }
          },
          "503": {
            "description": "`no_disponible`: El dato todavía se está cargando o actualizando de nuestro lado. Vuelve a intentar después de los segundos que indica `Retry-After`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "no_disponible": {
                    "$ref": "#/components/examples/no_disponible"
                  }
                }
              }
            }
          }
        },
        "x-nexum": {
          "permiso": "conecta:enviar",
          "cobro": "reserva",
          "puede_pedir_confirmacion": true,
          "confirmacion_obligatoria": false,
          "acepta_credenciales": false,
          "idempotencia": "requerida",
          "herramienta_mcp": "comprobante_enviar"
        }
      }
    },
    "/v1/conecta/webhooks": {
      "post": {
        "operationId": "webhook_crear",
        "summary": "Registra un webhook",
        "description": "Registra tu endpoint para recibir eventos normalizados y firmados. Siempre espera la aprobación de una persona (por ese endpoint pasarán los mensajes de tus clientes). Ya aprobado, repite la petición con la misma `Idempotency-Key`: la primera respuesta 201 trae `secreto`; las siguientes responden `ya_registrado`.\n\n**Permiso:** `webhooks:administrar`. **Cobro:** No cobra.\n\n**Idempotency-Key:** obligatoria.\n\n**Siempre espera la aprobación de una persona** (202 `requiere_confirmacion`).",
        "tags": [
          "Webhooks"
        ],
        "security": [
          {
            "claveApi": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "$ref": "#/components/parameters/RequestId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CrearWebhook"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Webhook creado; guarda `secreto` ahora.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookCreado"
                }
              }
            }
          },
          "202": {
            "description": "Espera la aprobación de una persona.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RespuestaRequiereConfirmacion"
                }
              }
            }
          },
          "400": {
            "description": "`validacion`: Algún dato no cumple el formato. En `detalle` va cada campo con su problema.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "validacion": {
                    "$ref": "#/components/examples/validacion"
                  }
                }
              }
            }
          },
          "401": {
            "description": "`clave_invalida`: Falta la clave de API, está mal escrita, venció o fue revocada. Envíala como `Authorization: Bearer onx_live_…`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "clave_invalida": {
                    "$ref": "#/components/examples/clave_invalida"
                  }
                }
              }
            }
          },
          "403": {
            "description": "`permiso_faltante`: La clave no tiene el permiso que pide esta ruta o no tiene acceso a ese RUC.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "permiso_faltante": {
                    "$ref": "#/components/examples/permiso_faltante"
                  }
                }
              }
            }
          },
          "409": {
            "description": "`idempotencia_en_conflicto`: Usaste la misma `Idempotency-Key` con otro cuerpo. Genera una clave nueva para cada operación distinta.\n\n`solicitud_en_curso`: Ya estamos procesando una petición con esa `Idempotency-Key`. Espera unos segundos y vuelve a consultar.\n\n`ya_registrado`: Eso ya está registrado: por ejemplo, el RUC ya está en otra cuenta o la serie ya existe.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "idempotencia_en_conflicto": {
                    "$ref": "#/components/examples/idempotencia_en_conflicto"
                  },
                  "solicitud_en_curso": {
                    "$ref": "#/components/examples/solicitud_en_curso"
                  },
                  "ya_registrado": {
                    "$ref": "#/components/examples/ya_registrado"
                  }
                }
              }
            }
          },
          "429": {
            "description": "`limite_uso`: Hiciste demasiadas peticiones seguidas. Espera los segundos que indica `Retry-After` y vuelve a intentar.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "limite_uso": {
                    "$ref": "#/components/examples/limite_uso"
                  }
                }
              }
            }
          },
          "500": {
            "description": "`error_interno`: Algo falló de nuestro lado. Repite la petición con la misma `Idempotency-Key`: no se duplica nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "error_interno": {
                    "$ref": "#/components/examples/error_interno"
                  }
                }
              }
            }
          },
          "501": {
            "description": "`operacion_no_disponible`: Esta operación existe en el contrato, pero todavía no está habilitada. Revisa en la documentación qué rutas ya puedes usar; no se cobró nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "operacion_no_disponible": {
                    "$ref": "#/components/examples/operacion_no_disponible"
                  }
                }
              }
            }
          },
          "503": {
            "description": "`no_disponible`: El dato todavía se está cargando o actualizando de nuestro lado. Vuelve a intentar después de los segundos que indica `Retry-After`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "no_disponible": {
                    "$ref": "#/components/examples/no_disponible"
                  }
                }
              }
            }
          }
        },
        "x-nexum": {
          "permiso": "webhooks:administrar",
          "cobro": "no",
          "puede_pedir_confirmacion": true,
          "confirmacion_obligatoria": true,
          "acepta_credenciales": false,
          "idempotencia": "requerida",
          "herramienta_mcp": null
        }
      },
      "get": {
        "operationId": "webhook_listar",
        "summary": "Lista tus webhooks",
        "description": "Webhooks registrados, sus eventos y su estado. Nunca devuelve el secreto.\n\n**Permiso:** `conecta:leer`. **Cobro:** No cobra.",
        "tags": [
          "Webhooks"
        ],
        "security": [
          {
            "claveApi": []
          }
        ],
        "parameters": [
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "Cursor opaco que devolvió la página anterior en `siguiente_cursor`.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 512
            }
          },
          {
            "name": "limite",
            "in": "query",
            "required": false,
            "description": "Cuántos elementos traer (1 a 100; por defecto 20).",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100
            }
          },
          {
            "$ref": "#/components/parameters/RequestId"
          }
        ],
        "responses": {
          "200": {
            "description": "Página de webhooks.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ListaWebhooks"
                }
              }
            }
          },
          "400": {
            "description": "`validacion`: Algún dato no cumple el formato. En `detalle` va cada campo con su problema.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "validacion": {
                    "$ref": "#/components/examples/validacion"
                  }
                }
              }
            }
          },
          "401": {
            "description": "`clave_invalida`: Falta la clave de API, está mal escrita, venció o fue revocada. Envíala como `Authorization: Bearer onx_live_…`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "clave_invalida": {
                    "$ref": "#/components/examples/clave_invalida"
                  }
                }
              }
            }
          },
          "403": {
            "description": "`permiso_faltante`: La clave no tiene el permiso que pide esta ruta o no tiene acceso a ese RUC.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "permiso_faltante": {
                    "$ref": "#/components/examples/permiso_faltante"
                  }
                }
              }
            }
          },
          "429": {
            "description": "`limite_uso`: Hiciste demasiadas peticiones seguidas. Espera los segundos que indica `Retry-After` y vuelve a intentar.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "limite_uso": {
                    "$ref": "#/components/examples/limite_uso"
                  }
                }
              }
            }
          },
          "500": {
            "description": "`error_interno`: Algo falló de nuestro lado. Repite la petición con la misma `Idempotency-Key`: no se duplica nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "error_interno": {
                    "$ref": "#/components/examples/error_interno"
                  }
                }
              }
            }
          },
          "501": {
            "description": "`operacion_no_disponible`: Esta operación existe en el contrato, pero todavía no está habilitada. Revisa en la documentación qué rutas ya puedes usar; no se cobró nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "operacion_no_disponible": {
                    "$ref": "#/components/examples/operacion_no_disponible"
                  }
                }
              }
            }
          },
          "503": {
            "description": "`no_disponible`: El dato todavía se está cargando o actualizando de nuestro lado. Vuelve a intentar después de los segundos que indica `Retry-After`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "no_disponible": {
                    "$ref": "#/components/examples/no_disponible"
                  }
                }
              }
            }
          }
        },
        "x-nexum": {
          "permiso": "conecta:leer",
          "cobro": "no",
          "puede_pedir_confirmacion": false,
          "confirmacion_obligatoria": false,
          "acepta_credenciales": false,
          "idempotencia": "no_aplica",
          "herramienta_mcp": "webhook_listar"
        }
      }
    },
    "/v1/conecta/webhooks/{id}": {
      "delete": {
        "operationId": "webhook_borrar",
        "summary": "Borra un webhook",
        "description": "Deja de enviar eventos a ese endpoint y cancela las entregas pendientes. Según tu clave, puede esperar la aprobación de una persona.\n\n**Permiso:** `webhooks:administrar`. **Cobro:** No cobra.\n\n**Puede pedir aprobación humana** según tu clave (202 `requiere_confirmacion`).",
        "tags": [
          "Webhooks"
        ],
        "security": [
          {
            "claveApi": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Identificador que empieza con `whk_`.",
            "schema": {
              "type": "string",
              "pattern": "^whk_[A-Za-z0-9]{8,64}$",
              "examples": [
                "whk_8f2c1a7d9e"
              ]
            }
          },
          {
            "$ref": "#/components/parameters/RequestId"
          }
        ],
        "responses": {
          "202": {
            "description": "Espera la aprobación de una persona.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RespuestaRequiereConfirmacion"
                }
              }
            }
          },
          "204": {
            "description": "Webhook borrado.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            }
          },
          "400": {
            "description": "`validacion`: Algún dato no cumple el formato. En `detalle` va cada campo con su problema.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "validacion": {
                    "$ref": "#/components/examples/validacion"
                  }
                }
              }
            }
          },
          "401": {
            "description": "`clave_invalida`: Falta la clave de API, está mal escrita, venció o fue revocada. Envíala como `Authorization: Bearer onx_live_…`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "clave_invalida": {
                    "$ref": "#/components/examples/clave_invalida"
                  }
                }
              }
            }
          },
          "403": {
            "description": "`permiso_faltante`: La clave no tiene el permiso que pide esta ruta o no tiene acceso a ese RUC.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "permiso_faltante": {
                    "$ref": "#/components/examples/permiso_faltante"
                  }
                }
              }
            }
          },
          "404": {
            "description": "`no_encontrado`: No existe o no pertenece a tu cuenta.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "no_encontrado": {
                    "$ref": "#/components/examples/no_encontrado"
                  }
                }
              }
            }
          },
          "429": {
            "description": "`limite_uso`: Hiciste demasiadas peticiones seguidas. Espera los segundos que indica `Retry-After` y vuelve a intentar.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "limite_uso": {
                    "$ref": "#/components/examples/limite_uso"
                  }
                }
              }
            }
          },
          "500": {
            "description": "`error_interno`: Algo falló de nuestro lado. Repite la petición con la misma `Idempotency-Key`: no se duplica nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "error_interno": {
                    "$ref": "#/components/examples/error_interno"
                  }
                }
              }
            }
          },
          "501": {
            "description": "`operacion_no_disponible`: Esta operación existe en el contrato, pero todavía no está habilitada. Revisa en la documentación qué rutas ya puedes usar; no se cobró nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "operacion_no_disponible": {
                    "$ref": "#/components/examples/operacion_no_disponible"
                  }
                }
              }
            }
          },
          "503": {
            "description": "`no_disponible`: El dato todavía se está cargando o actualizando de nuestro lado. Vuelve a intentar después de los segundos que indica `Retry-After`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "no_disponible": {
                    "$ref": "#/components/examples/no_disponible"
                  }
                }
              }
            }
          }
        },
        "x-nexum": {
          "permiso": "webhooks:administrar",
          "cobro": "no",
          "puede_pedir_confirmacion": true,
          "confirmacion_obligatoria": false,
          "acepta_credenciales": false,
          "idempotencia": "no_aplica",
          "herramienta_mcp": "webhook_borrar"
        }
      }
    },
    "/v1/conecta/webhooks/{id}/probar": {
      "post": {
        "operationId": "webhook_probar",
        "summary": "Envía un evento de prueba",
        "description": "Envía un evento `webhook.prueba` firmado y devuelve cómo respondió tu endpoint.\n\n**Permiso:** `webhooks:administrar`. **Cobro:** No cobra.",
        "tags": [
          "Webhooks"
        ],
        "security": [
          {
            "claveApi": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Identificador que empieza con `whk_`.",
            "schema": {
              "type": "string",
              "pattern": "^whk_[A-Za-z0-9]{8,64}$",
              "examples": [
                "whk_8f2c1a7d9e"
              ]
            }
          },
          {
            "$ref": "#/components/parameters/RequestId"
          }
        ],
        "responses": {
          "200": {
            "description": "Resultado de la entrega de prueba.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Entrega"
                }
              }
            }
          },
          "400": {
            "description": "`validacion`: Algún dato no cumple el formato. En `detalle` va cada campo con su problema.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "validacion": {
                    "$ref": "#/components/examples/validacion"
                  }
                }
              }
            }
          },
          "401": {
            "description": "`clave_invalida`: Falta la clave de API, está mal escrita, venció o fue revocada. Envíala como `Authorization: Bearer onx_live_…`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "clave_invalida": {
                    "$ref": "#/components/examples/clave_invalida"
                  }
                }
              }
            }
          },
          "403": {
            "description": "`permiso_faltante`: La clave no tiene el permiso que pide esta ruta o no tiene acceso a ese RUC.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "permiso_faltante": {
                    "$ref": "#/components/examples/permiso_faltante"
                  }
                }
              }
            }
          },
          "404": {
            "description": "`no_encontrado`: No existe o no pertenece a tu cuenta.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "no_encontrado": {
                    "$ref": "#/components/examples/no_encontrado"
                  }
                }
              }
            }
          },
          "429": {
            "description": "`limite_uso`: Hiciste demasiadas peticiones seguidas. Espera los segundos que indica `Retry-After` y vuelve a intentar.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "limite_uso": {
                    "$ref": "#/components/examples/limite_uso"
                  }
                }
              }
            }
          },
          "500": {
            "description": "`error_interno`: Algo falló de nuestro lado. Repite la petición con la misma `Idempotency-Key`: no se duplica nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "error_interno": {
                    "$ref": "#/components/examples/error_interno"
                  }
                }
              }
            }
          },
          "501": {
            "description": "`operacion_no_disponible`: Esta operación existe en el contrato, pero todavía no está habilitada. Revisa en la documentación qué rutas ya puedes usar; no se cobró nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "operacion_no_disponible": {
                    "$ref": "#/components/examples/operacion_no_disponible"
                  }
                }
              }
            }
          },
          "503": {
            "description": "`no_disponible`: El dato todavía se está cargando o actualizando de nuestro lado. Vuelve a intentar después de los segundos que indica `Retry-After`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "no_disponible": {
                    "$ref": "#/components/examples/no_disponible"
                  }
                }
              }
            }
          }
        },
        "x-nexum": {
          "permiso": "webhooks:administrar",
          "cobro": "no",
          "puede_pedir_confirmacion": false,
          "confirmacion_obligatoria": false,
          "acepta_credenciales": false,
          "idempotencia": "no_aplica",
          "herramienta_mcp": "webhook_probar"
        }
      }
    },
    "/v1/conecta/webhooks/{id}/rotar-secreto": {
      "post": {
        "operationId": "webhook_rotar_secreto",
        "summary": "Rota el secreto de un webhook",
        "description": "Genera un secreto nuevo. Durante 24 horas firmamos con los dos (dos `v1` en la cabecera) para que cambies el tuyo sin perder eventos.\n\n**Permiso:** `webhooks:administrar`. **Cobro:** No cobra.\n\n**Idempotency-Key:** obligatoria.",
        "tags": [
          "Webhooks"
        ],
        "security": [
          {
            "claveApi": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Identificador que empieza con `whk_`.",
            "schema": {
              "type": "string",
              "pattern": "^whk_[A-Za-z0-9]{8,64}$",
              "examples": [
                "whk_8f2c1a7d9e"
              ]
            }
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "$ref": "#/components/parameters/RequestId"
          }
        ],
        "responses": {
          "200": {
            "description": "Secreto nuevo; guárdalo ahora.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SecretoRotado"
                }
              }
            }
          },
          "400": {
            "description": "`validacion`: Algún dato no cumple el formato. En `detalle` va cada campo con su problema.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "validacion": {
                    "$ref": "#/components/examples/validacion"
                  }
                }
              }
            }
          },
          "401": {
            "description": "`clave_invalida`: Falta la clave de API, está mal escrita, venció o fue revocada. Envíala como `Authorization: Bearer onx_live_…`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "clave_invalida": {
                    "$ref": "#/components/examples/clave_invalida"
                  }
                }
              }
            }
          },
          "403": {
            "description": "`permiso_faltante`: La clave no tiene el permiso que pide esta ruta o no tiene acceso a ese RUC.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "permiso_faltante": {
                    "$ref": "#/components/examples/permiso_faltante"
                  }
                }
              }
            }
          },
          "404": {
            "description": "`no_encontrado`: No existe o no pertenece a tu cuenta.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "no_encontrado": {
                    "$ref": "#/components/examples/no_encontrado"
                  }
                }
              }
            }
          },
          "409": {
            "description": "`idempotencia_en_conflicto`: Usaste la misma `Idempotency-Key` con otro cuerpo. Genera una clave nueva para cada operación distinta.\n\n`solicitud_en_curso`: Ya estamos procesando una petición con esa `Idempotency-Key`. Espera unos segundos y vuelve a consultar.\n\n`ya_registrado`: Eso ya está registrado: por ejemplo, el RUC ya está en otra cuenta o la serie ya existe.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "idempotencia_en_conflicto": {
                    "$ref": "#/components/examples/idempotencia_en_conflicto"
                  },
                  "solicitud_en_curso": {
                    "$ref": "#/components/examples/solicitud_en_curso"
                  },
                  "ya_registrado": {
                    "$ref": "#/components/examples/ya_registrado"
                  }
                }
              }
            }
          },
          "429": {
            "description": "`limite_uso`: Hiciste demasiadas peticiones seguidas. Espera los segundos que indica `Retry-After` y vuelve a intentar.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "limite_uso": {
                    "$ref": "#/components/examples/limite_uso"
                  }
                }
              }
            }
          },
          "500": {
            "description": "`error_interno`: Algo falló de nuestro lado. Repite la petición con la misma `Idempotency-Key`: no se duplica nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "error_interno": {
                    "$ref": "#/components/examples/error_interno"
                  }
                }
              }
            }
          },
          "501": {
            "description": "`operacion_no_disponible`: Esta operación existe en el contrato, pero todavía no está habilitada. Revisa en la documentación qué rutas ya puedes usar; no se cobró nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "operacion_no_disponible": {
                    "$ref": "#/components/examples/operacion_no_disponible"
                  }
                }
              }
            }
          },
          "503": {
            "description": "`no_disponible`: El dato todavía se está cargando o actualizando de nuestro lado. Vuelve a intentar después de los segundos que indica `Retry-After`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "no_disponible": {
                    "$ref": "#/components/examples/no_disponible"
                  }
                }
              }
            }
          }
        },
        "x-nexum": {
          "permiso": "webhooks:administrar",
          "cobro": "no",
          "puede_pedir_confirmacion": false,
          "confirmacion_obligatoria": false,
          "acepta_credenciales": false,
          "idempotencia": "requerida",
          "herramienta_mcp": null
        }
      }
    },
    "/v1/conecta/entregas": {
      "get": {
        "operationId": "entrega_listar",
        "summary": "Lista entregas de eventos",
        "description": "Intentos de entrega a tus webhooks, con el código HTTP que respondió tu endpoint.\n\n**Permiso:** `conecta:leer`. **Cobro:** No cobra.",
        "tags": [
          "Webhooks"
        ],
        "security": [
          {
            "claveApi": []
          }
        ],
        "parameters": [
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "Cursor opaco que devolvió la página anterior en `siguiente_cursor`.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 512
            }
          },
          {
            "name": "limite",
            "in": "query",
            "required": false,
            "description": "Cuántos elementos traer (1 a 100; por defecto 20).",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100
            }
          },
          {
            "name": "webhook_id",
            "in": "query",
            "required": false,
            "description": "Identificador que empieza con `whk_`.",
            "schema": {
              "type": "string",
              "pattern": "^whk_[A-Za-z0-9]{8,64}$",
              "examples": [
                "whk_8f2c1a7d9e"
              ]
            }
          },
          {
            "name": "estado",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "pendiente",
                "entregada",
                "fallida",
                "pausada"
              ]
            }
          },
          {
            "$ref": "#/components/parameters/RequestId"
          }
        ],
        "responses": {
          "200": {
            "description": "Página de entregas.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ListaEntregas"
                }
              }
            }
          },
          "400": {
            "description": "`validacion`: Algún dato no cumple el formato. En `detalle` va cada campo con su problema.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "validacion": {
                    "$ref": "#/components/examples/validacion"
                  }
                }
              }
            }
          },
          "401": {
            "description": "`clave_invalida`: Falta la clave de API, está mal escrita, venció o fue revocada. Envíala como `Authorization: Bearer onx_live_…`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "clave_invalida": {
                    "$ref": "#/components/examples/clave_invalida"
                  }
                }
              }
            }
          },
          "403": {
            "description": "`permiso_faltante`: La clave no tiene el permiso que pide esta ruta o no tiene acceso a ese RUC.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "permiso_faltante": {
                    "$ref": "#/components/examples/permiso_faltante"
                  }
                }
              }
            }
          },
          "429": {
            "description": "`limite_uso`: Hiciste demasiadas peticiones seguidas. Espera los segundos que indica `Retry-After` y vuelve a intentar.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "limite_uso": {
                    "$ref": "#/components/examples/limite_uso"
                  }
                }
              }
            }
          },
          "500": {
            "description": "`error_interno`: Algo falló de nuestro lado. Repite la petición con la misma `Idempotency-Key`: no se duplica nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "error_interno": {
                    "$ref": "#/components/examples/error_interno"
                  }
                }
              }
            }
          },
          "501": {
            "description": "`operacion_no_disponible`: Esta operación existe en el contrato, pero todavía no está habilitada. Revisa en la documentación qué rutas ya puedes usar; no se cobró nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "operacion_no_disponible": {
                    "$ref": "#/components/examples/operacion_no_disponible"
                  }
                }
              }
            }
          },
          "503": {
            "description": "`no_disponible`: El dato todavía se está cargando o actualizando de nuestro lado. Vuelve a intentar después de los segundos que indica `Retry-After`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "no_disponible": {
                    "$ref": "#/components/examples/no_disponible"
                  }
                }
              }
            }
          }
        },
        "x-nexum": {
          "permiso": "conecta:leer",
          "cobro": "no",
          "puede_pedir_confirmacion": false,
          "confirmacion_obligatoria": false,
          "acepta_credenciales": false,
          "idempotencia": "no_aplica",
          "herramienta_mcp": "entrega_listar"
        }
      }
    },
    "/v1/conecta/entregas/{id}/reintentar": {
      "post": {
        "operationId": "entrega_reintentar",
        "summary": "Reintenta una entrega",
        "description": "Vuelve a encolar una entrega fallida o pausada. El evento conserva su `id` para que no lo dupliques.\n\n**Permiso:** `webhooks:administrar`. **Cobro:** No cobra.",
        "tags": [
          "Webhooks"
        ],
        "security": [
          {
            "claveApi": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Identificador que empieza con `ent_`.",
            "schema": {
              "type": "string",
              "pattern": "^ent_[A-Za-z0-9]{8,64}$",
              "examples": [
                "ent_8f2c1a7d9e"
              ]
            }
          },
          {
            "$ref": "#/components/parameters/IdempotencyKeyOpcional"
          },
          {
            "$ref": "#/components/parameters/RequestId"
          }
        ],
        "responses": {
          "202": {
            "description": "Entrega en cola.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Entrega"
                }
              }
            }
          },
          "400": {
            "description": "`validacion`: Algún dato no cumple el formato. En `detalle` va cada campo con su problema.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "validacion": {
                    "$ref": "#/components/examples/validacion"
                  }
                }
              }
            }
          },
          "401": {
            "description": "`clave_invalida`: Falta la clave de API, está mal escrita, venció o fue revocada. Envíala como `Authorization: Bearer onx_live_…`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "clave_invalida": {
                    "$ref": "#/components/examples/clave_invalida"
                  }
                }
              }
            }
          },
          "403": {
            "description": "`permiso_faltante`: La clave no tiene el permiso que pide esta ruta o no tiene acceso a ese RUC.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "permiso_faltante": {
                    "$ref": "#/components/examples/permiso_faltante"
                  }
                }
              }
            }
          },
          "404": {
            "description": "`no_encontrado`: No existe o no pertenece a tu cuenta.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "no_encontrado": {
                    "$ref": "#/components/examples/no_encontrado"
                  }
                }
              }
            }
          },
          "409": {
            "description": "`idempotencia_en_conflicto`: Usaste la misma `Idempotency-Key` con otro cuerpo. Genera una clave nueva para cada operación distinta.\n\n`solicitud_en_curso`: Ya estamos procesando una petición con esa `Idempotency-Key`. Espera unos segundos y vuelve a consultar.\n\n`estado_no_permite`: El recurso está en un estado que no permite esta operación, por ejemplo anular un comprobante rechazado.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "idempotencia_en_conflicto": {
                    "$ref": "#/components/examples/idempotencia_en_conflicto"
                  },
                  "solicitud_en_curso": {
                    "$ref": "#/components/examples/solicitud_en_curso"
                  },
                  "estado_no_permite": {
                    "$ref": "#/components/examples/estado_no_permite"
                  }
                }
              }
            }
          },
          "429": {
            "description": "`limite_uso`: Hiciste demasiadas peticiones seguidas. Espera los segundos que indica `Retry-After` y vuelve a intentar.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "limite_uso": {
                    "$ref": "#/components/examples/limite_uso"
                  }
                }
              }
            }
          },
          "500": {
            "description": "`error_interno`: Algo falló de nuestro lado. Repite la petición con la misma `Idempotency-Key`: no se duplica nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "error_interno": {
                    "$ref": "#/components/examples/error_interno"
                  }
                }
              }
            }
          },
          "501": {
            "description": "`operacion_no_disponible`: Esta operación existe en el contrato, pero todavía no está habilitada. Revisa en la documentación qué rutas ya puedes usar; no se cobró nada.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "operacion_no_disponible": {
                    "$ref": "#/components/examples/operacion_no_disponible"
                  }
                }
              }
            }
          },
          "503": {
            "description": "`no_disponible`: El dato todavía se está cargando o actualizando de nuestro lado. Vuelve a intentar después de los segundos que indica `Retry-After`.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "no_disponible": {
                    "$ref": "#/components/examples/no_disponible"
                  }
                }
              }
            }
          }
        },
        "x-nexum": {
          "permiso": "webhooks:administrar",
          "cobro": "no",
          "puede_pedir_confirmacion": false,
          "confirmacion_obligatoria": false,
          "acepta_credenciales": false,
          "idempotencia": "opcional",
          "herramienta_mcp": "entrega_reintentar"
        }
      }
    }
  },
  "webhooks": {
    "eventoConecta": {
      "post": {
        "summary": "Evento de Nexum Conecta hacia tu sistema",
        "description": "Enviamos cada evento con `POST` a la URL de tu webhook, con el cuerpo en JSON y la cabecera `X-Nexum-Signature`.\n\n**Cómo verificar la firma**\n1. Lee la cabecera: `t=<segundos unix>,v1=<firma>`. Durante una rotación de secreto llegan dos `v1`.\n2. Arma el texto `<t>.<cuerpo crudo>` con el cuerpo exacto, sin volver a serializarlo.\n3. Calcula HMAC-SHA256 de ese texto con tu secreto `whsec_…` y pásalo a hexadecimal.\n4. Compáralo en tiempo constante con algún `v1`. Rechaza si no coincide o si `t` difiere en más de 300 segundos de tu reloj.\n\n**Cómo responder**\nResponde 2xx en menos de 10 segundos y procesa después. Si fallas, reintentamos hasta 8 veces con espera creciente; luego el webhook se pausa y puedes reenviar desde `/v1/conecta/entregas`. Un mismo evento puede llegar más de una vez: usa su `id` para no procesarlo dos veces.",
        "parameters": [
          {
            "name": "X-Nexum-Signature",
            "in": "header",
            "required": true,
            "description": "`t=<segundos unix>,v1=<HMAC-SHA256 en hexadecimal>`; durante una rotación de secreto llegan dos `v1`.",
            "schema": {
              "type": "string",
              "maxLength": 200,
              "pattern": "^t=\\d{1,12}(,v1=[0-9a-f]{64}){1,2}$",
              "examples": [
                "t=1763300000,v1=1c8e566733fdb646907e1a98842649cec9832ef8c7c7d31edb2325465ba26b99"
              ]
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EventoConecta"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Recibido. Cualquier respuesta 2xx en menos de 10 segundos sirve."
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "codigo": {
                "type": "string",
                "enum": [
                  "validacion",
                  "clave_invalida",
                  "saldo_insuficiente",
                  "tope_alcanzado",
                  "permiso_faltante",
                  "emisor_obligado_ose",
                  "no_encontrado",
                  "idempotencia_en_conflicto",
                  "solicitud_en_curso",
                  "ya_registrado",
                  "ventana_cerrada",
                  "boveda_inactiva",
                  "estado_no_permite",
                  "plazo_vencido",
                  "sunat_rechazo",
                  "credenciales_sunat",
                  "limite_uso",
                  "error_interno",
                  "servicio_externo_no_disponible",
                  "no_disponible",
                  "operacion_no_disponible"
                ]
              },
              "mensaje": {
                "type": "string",
                "minLength": 1,
                "description": "Qué pasó y cómo se arregla, en español."
              },
              "detalle": {
                "description": "Datos para corregir: campos con problemas, código de SUNAT, etc."
              },
              "request_id": {
                "type": "string",
                "minLength": 1,
                "description": "Identificador de la petición; menciónalo a soporte."
              },
              "docs": {
                "description": "Enlace a la explicación del código.",
                "type": "string",
                "format": "uri"
              },
              "recarga_url": {
                "description": "Solo en errores de saldo: dónde recarga una persona.",
                "type": "string",
                "format": "uri"
              }
            },
            "required": [
              "codigo",
              "mensaje",
              "request_id"
            ]
          }
        },
        "required": [
          "error"
        ],
        "description": "Formato de todos los errores de la API."
      },
      "Monto": {
        "type": "string",
        "pattern": "^(0|[1-9]\\d{0,11})\\.\\d{2}$",
        "description": "Monto como texto con dos decimales y punto decimal, sin separador de miles. \"1250.50\" es S/ 1,250.50.",
        "examples": [
          "1250.50"
        ]
      },
      "MontoConSigno": {
        "type": "string",
        "pattern": "^-?(0|[1-9]\\d{0,11})\\.\\d{2}$",
        "description": "Monto con dos decimales; negativo en notas de crédito.",
        "examples": [
          "-1250.50"
        ]
      },
      "PrecioUnitario": {
        "type": "string",
        "pattern": "^(0|[1-9]\\d{0,11})\\.\\d{2,6}$",
        "description": "Precio por unidad como texto, con 2 a 6 decimales.",
        "examples": [
          "1250.50"
        ]
      },
      "Cantidad": {
        "type": "string",
        "pattern": "^(0|[1-9]\\d{0,11})(\\.\\d{1,6})?$",
        "description": "Cantidad como texto, mayor que cero, con hasta 6 decimales.",
        "examples": [
          "2"
        ]
      },
      "TipoCambioValor": {
        "type": "string",
        "pattern": "^\\d{1,4}\\.\\d{3}$",
        "description": "Soles por dólar, con tres decimales.",
        "examples": [
          "3.752"
        ]
      },
      "Fecha": {
        "type": "string",
        "format": "date",
        "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$",
        "description": "Fecha AAAA-MM-DD (día en Lima).",
        "examples": [
          "2026-11-15"
        ]
      },
      "FechaHoraLima": {
        "type": "string",
        "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,3})?-05:00$",
        "format": "date-time",
        "description": "Fecha y hora ISO 8601 con la zona de Lima (-05:00).",
        "examples": [
          "2026-11-15T16:30:00-05:00"
        ]
      },
      "Periodo": {
        "type": "string",
        "pattern": "^\\d{4}(0[1-9]|1[0-2])$",
        "description": "Periodo tributario AAAAMM.",
        "examples": [
          "202611"
        ]
      },
      "Ubigeo": {
        "type": "string",
        "pattern": "^\\d{6}$",
        "description": "Ubigeo INEI de 6 dígitos.",
        "examples": [
          "150101"
        ]
      },
      "Telefono": {
        "type": "string",
        "pattern": "^\\+[1-9]\\d{7,14}$",
        "description": "Teléfono en formato E.164, sin espacios.",
        "examples": [
          "+51987654321"
        ]
      },
      "Ruc": {
        "type": "string",
        "pattern": "^(10|15|16|17|20)\\d{9}$",
        "description": "RUC de 11 dígitos. Se valida el dígito verificador (módulo 11 de SUNAT).",
        "examples": [
          "20000000001"
        ]
      },
      "Error402": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "codigo": {
                "type": "string",
                "enum": [
                  "saldo_insuficiente",
                  "tope_alcanzado"
                ]
              },
              "mensaje": {
                "type": "string",
                "minLength": 1
              },
              "detalle": {
                "type": "object",
                "properties": {
                  "disponible": {
                    "description": "Saldo (o tope) que queda.",
                    "$ref": "#/components/schemas/Monto"
                  },
                  "requerido": {
                    "description": "Lo que costaría esta operación.",
                    "$ref": "#/components/schemas/Monto"
                  }
                },
                "required": [
                  "disponible",
                  "requerido"
                ]
              },
              "request_id": {
                "type": "string",
                "minLength": 1
              },
              "docs": {
                "type": "string",
                "format": "uri"
              },
              "recarga_url": {
                "type": "string",
                "format": "uri",
                "description": "Enlace del panel para que una persona recargue saldo o suba el tope. El agente no puede hacerlo."
              }
            },
            "required": [
              "codigo",
              "mensaje",
              "request_id",
              "recarga_url"
            ]
          }
        },
        "required": [
          "error"
        ],
        "description": "Error de saldo (402). El agente debe pasarle `recarga_url` a una persona y esperar."
      },
      "RespuestaRequiereConfirmacion": {
        "type": "object",
        "properties": {
          "estado": {
            "type": "string",
            "const": "requiere_confirmacion"
          },
          "operacion_id": {
            "type": "string",
            "pattern": "^op_[A-Za-z0-9]{8,64}$",
            "description": "Úsalo en `GET /v1/confirmaciones/{id}` para saber si se aprobó.",
            "examples": [
              "op_8f2c1a7d9e"
            ]
          },
          "confirmacion_url": {
            "type": "string",
            "maxLength": 2048,
            "format": "uri",
            "description": "Enlace del panel donde una persona aprueba o rechaza. Pásaselo tal cual."
          },
          "consulta_url": {
            "type": "string",
            "format": "starts_with",
            "pattern": "^\\/v1\\/confirmaciones\\/.*",
            "description": "Ruta para consultar el estado."
          },
          "expira_en": {
            "description": "Si nadie aprueba antes, la operación vence y no se hace.",
            "$ref": "#/components/schemas/FechaHoraLima"
          },
          "mensaje": {
            "type": "string",
            "minLength": 1,
            "description": "Qué falta, en palabras para una persona."
          }
        },
        "required": [
          "estado",
          "operacion_id",
          "confirmacion_url",
          "consulta_url",
          "expira_en",
          "mensaje"
        ],
        "description": "La operación quedó en espera de aprobación humana (según la configuración de tu clave). Nada se cobró todavía. El «sí» se da en el panel, nunca como argumento de la API."
      },
      "RespuestaEnCola": {
        "type": "object",
        "properties": {
          "estado": {
            "type": "string",
            "const": "en_cola"
          },
          "recurso": {
            "type": "object",
            "properties": {
              "tipo": {
                "type": "string",
                "enum": [
                  "comprobante",
                  "baja",
                  "resumen",
                  "guia",
                  "sire_propuesta",
                  "mensaje",
                  "entrega",
                  "clave",
                  "conexion",
                  "webhook"
                ]
              },
              "id": {
                "type": "string",
                "minLength": 1
              }
            },
            "required": [
              "tipo",
              "id"
            ],
            "description": "Lo que se creó y queda en proceso."
          },
          "consulta_url": {
            "type": "string",
            "format": "starts_with",
            "pattern": "^\\/v1\\/.*",
            "description": "Ruta para consultar cómo va."
          },
          "mensaje": {
            "type": "string",
            "minLength": 1
          },
          "reintento_en": {
            "description": "Próximo intento estimado, si aplica.",
            "$ref": "#/components/schemas/FechaHoraLima"
          }
        },
        "required": [
          "estado",
          "recurso",
          "consulta_url",
          "mensaje"
        ],
        "description": "Recibimos la operación y la terminamos en segundo plano. No la repitas: consulta `consulta_url`."
      },
      "RespuestaAceptada": {
        "oneOf": [
          {
            "$ref": "#/components/schemas/RespuestaRequiereConfirmacion"
          },
          {
            "$ref": "#/components/schemas/RespuestaEnCola"
          }
        ],
        "description": "Respuesta 202: `requiere_confirmacion` o `en_cola`, según `estado`."
      },
      "Saldo": {
        "type": "object",
        "properties": {
          "moneda": {
            "type": "string",
            "const": "PEN"
          },
          "disponible": {
            "description": "Lo que puedes gastar ahora.",
            "$ref": "#/components/schemas/Monto"
          },
          "reservado": {
            "description": "Separado para operaciones en curso; se cobra solo si se completan.",
            "$ref": "#/components/schemas/Monto"
          },
          "recarga_url": {
            "type": "string",
            "maxLength": 2048,
            "format": "uri",
            "description": "Dónde recarga una persona de tu cuenta."
          },
          "tope_clave": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "periodo": {
                    "type": "string",
                    "enum": [
                      "diario",
                      "semanal",
                      "mensual",
                      "total"
                    ]
                  },
                  "limite": {
                    "$ref": "#/components/schemas/Monto"
                  },
                  "consumido": {
                    "$ref": "#/components/schemas/Monto"
                  },
                  "renueva_en": {
                    "anyOf": [
                      {
                        "$ref": "#/components/schemas/FechaHoraLima"
                      },
                      {
                        "type": "null"
                      }
                    ],
                    "description": "Cuándo vuelve a cero lo consumido; `null` en un tope `total`."
                  }
                },
                "required": [
                  "periodo",
                  "limite",
                  "consumido",
                  "renueva_en"
                ]
              },
              {
                "type": "null"
              }
            ],
            "description": "Tope de la clave con la que preguntas; `null` si no tiene."
          },
          "actualizado_en": {
            "$ref": "#/components/schemas/FechaHoraLima"
          }
        },
        "required": [
          "moneda",
          "disponible",
          "reservado",
          "recarga_url",
          "tope_clave",
          "actualizado_en"
        ],
        "description": "Saldo prepagado de tu cuenta, en soles."
      },
      "Yo": {
        "type": "object",
        "properties": {
          "cuenta": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "pattern": "^cta_[A-Za-z0-9]{8,64}$",
                "description": "Identificador público de tu cuenta.",
                "examples": [
                  "cta_8f2c1a7d9e"
                ]
              },
              "nombre": {
                "type": "string",
                "minLength": 1,
                "maxLength": 200,
                "description": "Nombre de la cuenta."
              }
            },
            "required": [
              "id",
              "nombre"
            ],
            "description": "La cuenta a la que pertenece la credencial."
          },
          "entorno": {
            "type": "string",
            "enum": [
              "live",
              "test"
            ],
            "description": "`live` en producción; `test` en sandbox (SUNAT beta)."
          },
          "credencial": {
            "type": "string",
            "enum": [
              "clave",
              "oauth"
            ],
            "description": "Con qué preguntas: una clave `onx_live_`/`onx_test_` o el token OAuth de un agente conectado."
          },
          "permisos": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "datos:leer",
                "emisores:administrar",
                "comprobantes:emitir",
                "comprobantes:leer",
                "comprobantes:anular",
                "guias:emitir",
                "sire:leer",
                "conecta:leer",
                "conecta:enviar",
                "conecta:administrar",
                "webhooks:administrar",
                "cuenta:leer",
                "cuenta:recargar",
                "claves:administrar",
                "credenciales:por_llamada"
              ],
              "description": "Permiso de una clave de API."
            },
            "description": "Lo que puede hacer esta credencial."
          },
          "emisores": {
            "anyOf": [
              {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Ruc"
                }
              },
              {
                "type": "null"
              }
            ],
            "description": "RUC a los que llega: `null` = todos los de tu cuenta; una lista vacía = ninguno."
          },
          "tope": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "periodo": {
                    "type": "string",
                    "enum": [
                      "diario",
                      "semanal",
                      "mensual",
                      "total"
                    ]
                  },
                  "limite": {
                    "$ref": "#/components/schemas/Monto"
                  }
                },
                "required": [
                  "periodo",
                  "limite"
                ]
              },
              {
                "type": "null"
              }
            ],
            "description": "Tope de gasto de la credencial; `null` si no tiene. Lo consumido está en `GET /v1/cuenta/saldo`."
          }
        },
        "required": [
          "cuenta",
          "entorno",
          "credencial",
          "permisos",
          "emisores",
          "tope"
        ],
        "description": "Quién eres para la API: la cuenta, el entorno y lo que puede hacer la credencial con la que preguntas. Nunca incluye la clave, el token ni su hash."
      },
      "MovimientoConsumo": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^mov_[A-Za-z0-9]{8,64}$",
            "description": "Identificador que empieza con `mov_`.",
            "examples": [
              "mov_8f2c1a7d9e"
            ]
          },
          "tipo": {
            "type": "string",
            "enum": [
              "consumo",
              "recarga"
            ],
            "description": "`consumo`: lo que gastó una clave; `recarga`: saldo que sumaste."
          },
          "fecha": {
            "$ref": "#/components/schemas/FechaHoraLima"
          },
          "servicio": {
            "anyOf": [
              {
                "type": "string",
                "enum": [
                  "datos",
                  "comprobantes",
                  "conecta"
                ]
              },
              {
                "type": "null"
              }
            ],
            "description": "Servicio del consumo; `null` en una recarga."
          },
          "operacion": {
            "type": "string",
            "minLength": 1,
            "description": "operationId de la ruta, por ejemplo `comprobante_emitir` o `recarga_crear`."
          },
          "monto": {
            "$ref": "#/components/schemas/Monto"
          },
          "moneda": {
            "type": "string",
            "const": "PEN"
          },
          "estado": {
            "type": "string",
            "enum": [
              "reservado",
              "cobrado",
              "liberado",
              "acreditado"
            ],
            "description": "Consumo: reservado mientras se completa, cobrado al confirmarse, liberado si falló o venció. Recarga: acreditado."
          },
          "clave_id": {
            "anyOf": [
              {
                "type": "string",
                "pattern": "^clv_[A-Za-z0-9]{8,64}$",
                "description": "Identificador que empieza con `clv_`.",
                "examples": [
                  "clv_8f2c1a7d9e"
                ]
              },
              {
                "type": "null"
              }
            ],
            "description": "Clave (o agente conectado) que gastó; `null` en una recarga."
          },
          "request_id": {
            "anyOf": [
              {
                "type": "string",
                "minLength": 1
              },
              {
                "type": "null"
              }
            ]
          },
          "recurso": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "tipo": {
                    "type": "string",
                    "enum": [
                      "comprobante",
                      "baja",
                      "resumen",
                      "guia",
                      "sire_propuesta",
                      "mensaje",
                      "entrega",
                      "clave",
                      "conexion",
                      "webhook"
                    ]
                  },
                  "id": {
                    "type": "string",
                    "minLength": 1
                  }
                },
                "required": [
                  "tipo",
                  "id"
                ]
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "id",
          "tipo",
          "fecha",
          "servicio",
          "operacion",
          "monto",
          "moneda",
          "estado",
          "clave_id",
          "request_id",
          "recurso"
        ],
        "description": "Un movimiento de tu saldo: un consumo de una clave o una recarga acreditada."
      },
      "GastoClave": {
        "type": "object",
        "properties": {
          "clave_id": {
            "type": "string",
            "pattern": "^clv_[A-Za-z0-9]{8,64}$",
            "description": "Identificador que empieza con `clv_`.",
            "examples": [
              "clv_8f2c1a7d9e"
            ]
          },
          "nombre": {
            "type": "string",
            "minLength": 1
          },
          "prefijo": {
            "type": "string",
            "minLength": 1,
            "description": "Inicio visible de la clave; `onx_<entorno>_oauth` si es un agente conectado."
          },
          "origen": {
            "type": "string",
            "enum": [
              "clave",
              "agente_oauth"
            ],
            "description": "`agente_oauth`: un agente conectado desde el panel con OAuth."
          },
          "cobrado": {
            "$ref": "#/components/schemas/Monto"
          },
          "reservado": {
            "description": "Retenido en operaciones que todavía no terminan.",
            "$ref": "#/components/schemas/Monto"
          },
          "operaciones": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991,
            "description": "Operaciones que cobraron o reservaron saldo en el periodo."
          }
        },
        "required": [
          "clave_id",
          "nombre",
          "prefijo",
          "origen",
          "cobrado",
          "reservado",
          "operaciones"
        ],
        "description": "Lo que gastó una clave o un agente en el periodo consultado."
      },
      "ListaConsumo": {
        "type": "object",
        "properties": {
          "elementos": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/MovimientoConsumo"
            }
          },
          "siguiente_cursor": {
            "description": "Pásalo como `cursor` para la página siguiente; `null` si ya no hay más.",
            "type": [
              "string",
              "null"
            ]
          },
          "periodo": {
            "type": "object",
            "properties": {
              "desde": {
                "$ref": "#/components/schemas/Fecha"
              },
              "hasta": {
                "$ref": "#/components/schemas/Fecha"
              }
            },
            "required": [
              "desde",
              "hasta"
            ],
            "description": "Días consultados, en hora de Lima."
          },
          "gasto_por_clave": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/GastoClave"
            },
            "description": "Gasto de cada clave o agente en todo el periodo (no solo en esta página), de mayor a menor."
          }
        },
        "required": [
          "elementos",
          "siguiente_cursor",
          "periodo",
          "gasto_por_clave"
        ],
        "description": "Página de movimientos, del más reciente al más antiguo, con el gasto por clave del periodo."
      },
      "CrearRecarga": {
        "type": "object",
        "properties": {
          "monto": {
            "type": "string",
            "pattern": "^(0|[1-9]\\d{0,11})\\.\\d{2}$",
            "description": "Lo que pagaste. Hay un monto mínimo (S/ 20.00 por omisión).",
            "examples": [
              "1250.50"
            ],
            "$ref": "#/components/schemas/Monto"
          },
          "metodo": {
            "type": "string",
            "enum": [
              "yape",
              "plin"
            ]
          },
          "numero_operacion": {
            "type": "string",
            "pattern": "^[A-Za-z0-9-]{4,40}$",
            "description": "Número de operación del pago, como lo muestra la app de Yape o Plin.",
            "examples": [
              "01234567"
            ]
          },
          "fecha_pago": {
            "description": "Día del pago según tu app, en hora de Lima. No puede ser futuro ni de hace más de 30 días.",
            "$ref": "#/components/schemas/Fecha"
          },
          "voucher": {
            "type": "object",
            "properties": {
              "tipo": {
                "type": "string",
                "enum": [
                  "image/jpeg",
                  "image/png",
                  "image/webp"
                ],
                "description": "Formato del archivo: JPG, PNG o WEBP."
              },
              "contenido_base64": {
                "type": "string",
                "minLength": 8,
                "maxLength": 6990508,
                "pattern": "^[A-Za-z0-9+/]+={0,2}$"
              }
            },
            "required": [
              "tipo",
              "contenido_base64"
            ],
            "additionalProperties": false,
            "description": "Captura del pago en base64 (JPG, PNG o WEBP de hasta 5 MB). Revisamos el contenido real del archivo."
          },
          "ruc_factura": {
            "description": "RUC para la factura de la recarga; si no lo envías, usamos el de tu cuenta.",
            "$ref": "#/components/schemas/Ruc"
          }
        },
        "required": [
          "monto",
          "metodo",
          "numero_operacion",
          "fecha_pago",
          "voucher"
        ],
        "additionalProperties": false,
        "description": "Declara un pago por Yape o Plin y sube su voucher. Una persona lo revisa y, al aprobarlo, se acredita una sola vez."
      },
      "Recarga": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^rec_[A-Za-z0-9]{8,64}$",
            "description": "Identificador que empieza con `rec_`.",
            "examples": [
              "rec_8f2c1a7d9e"
            ]
          },
          "estado": {
            "type": "string",
            "enum": [
              "en_revision",
              "acreditada",
              "rechazada"
            ],
            "description": "`en_revision` hasta que una persona revisa el voucher; luego `acreditada` o `rechazada` (con motivo)."
          },
          "monto": {
            "$ref": "#/components/schemas/Monto"
          },
          "moneda": {
            "type": "string",
            "const": "PEN"
          },
          "metodo": {
            "type": "string",
            "enum": [
              "yape",
              "plin"
            ]
          },
          "numero_operacion": {
            "type": "string",
            "minLength": 1
          },
          "fecha_pago": {
            "$ref": "#/components/schemas/Fecha"
          },
          "ruc_factura": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/Ruc"
              },
              {
                "type": "null"
              }
            ]
          },
          "motivo_rechazo": {
            "description": "Por qué se rechazó; `null` si no se rechazó.",
            "type": [
              "string",
              "null"
            ]
          },
          "creada_en": {
            "$ref": "#/components/schemas/FechaHoraLima"
          },
          "revisada_en": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/FechaHoraLima"
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "id",
          "estado",
          "monto",
          "moneda",
          "metodo",
          "numero_operacion",
          "fecha_pago",
          "ruc_factura",
          "motivo_rechazo",
          "creada_en",
          "revisada_en"
        ],
        "description": "Recarga de saldo. Se acredita una sola vez, cuando una persona aprueba el voucher."
      },
      "Confirmacion": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^op_[A-Za-z0-9]{8,64}$",
            "description": "Identificador que empieza con `op_`.",
            "examples": [
              "op_8f2c1a7d9e"
            ]
          },
          "estado": {
            "type": "string",
            "enum": [
              "pendiente",
              "aprobada",
              "rechazada",
              "vencida",
              "ejecutada",
              "fallida"
            ],
            "description": "`ejecutada`: se aprobó y la operación ya corrió; mira `resultado`."
          },
          "operacion": {
            "type": "string",
            "minLength": 1,
            "description": "operationId de la ruta que pidió aprobación."
          },
          "resumen": {
            "type": "string",
            "minLength": 1,
            "description": "Lo que se aprueba, en palabras para una persona."
          },
          "confirmacion_url": {
            "type": "string",
            "maxLength": 2048,
            "format": "uri",
            "description": "URL pública con https (sin IP literal, localhost, dominios internos ni usuario y clave)."
          },
          "creada_en": {
            "$ref": "#/components/schemas/FechaHoraLima"
          },
          "expira_en": {
            "$ref": "#/components/schemas/FechaHoraLima"
          },
          "decidida_en": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/FechaHoraLima"
              },
              {
                "type": "null"
              }
            ]
          },
          "resultado": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "estado_http": {
                    "type": "integer",
                    "minimum": 100,
                    "maximum": 599
                  },
                  "recurso": {
                    "anyOf": [
                      {
                        "type": "object",
                        "properties": {
                          "tipo": {
                            "type": "string",
                            "enum": [
                              "comprobante",
                              "baja",
                              "resumen",
                              "guia",
                              "sire_propuesta",
                              "mensaje",
                              "entrega",
                              "clave",
                              "conexion",
                              "webhook"
                            ]
                          },
                          "id": {
                            "type": "string",
                            "minLength": 1
                          }
                        },
                        "required": [
                          "tipo",
                          "id"
                        ]
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "error": {
                    "anyOf": [
                      {
                        "type": "object",
                        "properties": {
                          "codigo": {
                            "type": "string",
                            "enum": [
                              "validacion",
                              "clave_invalida",
                              "saldo_insuficiente",
                              "tope_alcanzado",
                              "permiso_faltante",
                              "emisor_obligado_ose",
                              "no_encontrado",
                              "idempotencia_en_conflicto",
                              "solicitud_en_curso",
                              "ya_registrado",
                              "ventana_cerrada",
                              "boveda_inactiva",
                              "estado_no_permite",
                              "plazo_vencido",
                              "sunat_rechazo",
                              "credenciales_sunat",
                              "limite_uso",
                              "error_interno",
                              "servicio_externo_no_disponible",
                              "no_disponible",
                              "operacion_no_disponible"
                            ]
                          },
                          "mensaje": {
                            "type": "string"
                          }
                        },
                        "required": [
                          "codigo",
                          "mensaje"
                        ]
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                },
                "required": [
                  "estado_http",
                  "recurso",
                  "error"
                ]
              },
              {
                "type": "null"
              }
            ],
            "description": "Resultado de la operación una vez ejecutada."
          }
        },
        "required": [
          "id",
          "estado",
          "operacion",
          "resumen",
          "confirmacion_url",
          "creada_en",
          "expira_en",
          "decidida_en",
          "resultado"
        ],
        "description": "Estado de una operación que pidió aprobación humana. Solo la ve la clave que la pidió."
      },
      "Clave": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^clv_[A-Za-z0-9]{8,64}$",
            "description": "Identificador que empieza con `clv_`.",
            "examples": [
              "clv_8f2c1a7d9e"
            ]
          },
          "nombre": {
            "type": "string",
            "minLength": 1
          },
          "prefijo": {
            "type": "string",
            "pattern": "^onx_(live|test)_[A-Za-z0-9]{4}$",
            "description": "Inicio visible de la clave, para reconocerla. La clave completa solo se muestra al crearla."
          },
          "entorno": {
            "type": "string",
            "enum": [
              "live",
              "test"
            ],
            "description": "`live` en producción; `test` en sandbox (SUNAT beta)."
          },
          "permisos": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "datos:leer",
                "emisores:administrar",
                "comprobantes:emitir",
                "comprobantes:leer",
                "comprobantes:anular",
                "guias:emitir",
                "sire:leer",
                "conecta:leer",
                "conecta:enviar",
                "conecta:administrar",
                "webhooks:administrar",
                "cuenta:leer",
                "cuenta:recargar",
                "claves:administrar",
                "credenciales:por_llamada"
              ],
              "description": "Permiso de una clave de API."
            },
            "description": "Puede estar vacía (una clave sin permisos solo autentica)."
          },
          "emisores": {
            "anyOf": [
              {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Ruc"
                }
              },
              {
                "type": "null"
              }
            ],
            "description": "RUC a los que puede acceder; `null` = todos los de tu cuenta."
          },
          "tope": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "periodo": {
                    "type": "string",
                    "enum": [
                      "diario",
                      "semanal",
                      "mensual",
                      "total"
                    ]
                  },
                  "limite": {
                    "$ref": "#/components/schemas/Monto"
                  }
                },
                "required": [
                  "periodo",
                  "limite"
                ]
              },
              {
                "type": "null"
              }
            ]
          },
          "confirmacion": {
            "type": "object",
            "properties": {
              "notas": {
                "type": "boolean",
                "description": "Notas de crédito y débito."
              },
              "bajas": {
                "type": "boolean",
                "description": "Bajas y anulaciones."
              },
              "mensajes": {
                "type": "boolean",
                "description": "Envío de mensajes y comprobantes por Conecta."
              },
              "monto_desde": {
                "anyOf": [
                  {
                    "$ref": "#/components/schemas/Monto"
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "Comprobantes desde este total; `null` para no pedirla por monto."
              }
            },
            "required": [
              "notas",
              "bajas",
              "mensajes",
              "monto_desde"
            ],
            "additionalProperties": false,
            "description": "Qué operaciones de esta clave esperan la aprobación de una persona en el panel."
          },
          "vence_el": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/Fecha"
              },
              {
                "type": "null"
              }
            ]
          },
          "ultimo_uso_en": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/FechaHoraLima"
              },
              {
                "type": "null"
              }
            ]
          },
          "creada_en": {
            "$ref": "#/components/schemas/FechaHoraLima"
          },
          "revocada_en": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/FechaHoraLima"
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "id",
          "nombre",
          "prefijo",
          "entorno",
          "permisos",
          "emisores",
          "tope",
          "confirmacion",
          "vence_el",
          "ultimo_uso_en",
          "creada_en",
          "revocada_en"
        ],
        "description": "Clave de API para un agente o sistema. Se guarda solo su hash."
      },
      "CrearClave": {
        "type": "object",
        "properties": {
          "nombre": {
            "type": "string",
            "minLength": 1,
            "maxLength": 80,
            "description": "Para reconocerla, por ejemplo «Agente de facturación»."
          },
          "permisos": {
            "minItems": 1,
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "datos:leer",
                "emisores:administrar",
                "comprobantes:emitir",
                "comprobantes:leer",
                "comprobantes:anular",
                "guias:emitir",
                "sire:leer",
                "conecta:leer",
                "conecta:enviar",
                "conecta:administrar",
                "webhooks:administrar",
                "cuenta:leer",
                "cuenta:recargar",
                "claves:administrar",
                "credenciales:por_llamada"
              ],
              "description": "Permiso de una clave de API."
            },
            "description": "Solo puedes dar permisos que tu propia clave ya tiene."
          },
          "emisores": {
            "description": "Limita la clave a estos RUC (dentro del alcance de tu clave); si no lo envías, hereda el de tu clave.",
            "minItems": 1,
            "maxItems": 100,
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Ruc"
            }
          },
          "tope": {
            "type": "object",
            "properties": {
              "periodo": {
                "type": "string",
                "enum": [
                  "diario",
                  "semanal",
                  "mensual",
                  "total"
                ]
              },
              "limite": {
                "$ref": "#/components/schemas/Monto"
              }
            },
            "required": [
              "periodo",
              "limite"
            ],
            "additionalProperties": false,
            "description": "No puede superar el tope de la clave que la crea."
          },
          "confirmacion": {
            "description": "Al menos tan estricta como la de tu clave. Si no la envías, se usa la de tu cuenta (notas, bajas y montos altos).",
            "type": "object",
            "properties": {
              "notas": {
                "type": "boolean",
                "description": "Notas de crédito y débito."
              },
              "bajas": {
                "type": "boolean",
                "description": "Bajas y anulaciones."
              },
              "mensajes": {
                "type": "boolean",
                "description": "Envío de mensajes y comprobantes por Conecta."
              },
              "monto_desde": {
                "anyOf": [
                  {
                    "$ref": "#/components/schemas/Monto"
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "Comprobantes desde este total; `null` para no pedirla por monto."
              }
            },
            "additionalProperties": false
          },
          "vence_el": {
            "description": "Día en que deja de funcionar; no puede ser posterior al de tu clave.",
            "$ref": "#/components/schemas/Fecha"
          }
        },
        "required": [
          "nombre",
          "permisos",
          "tope"
        ],
        "additionalProperties": false,
        "description": "Crea una clave hija: nunca con más permisos, RUC, tope, plazo ni menos aprobaciones que la clave que la crea. Siempre espera la aprobación de una persona."
      },
      "ClaveCreada": {
        "type": "object",
        "properties": {
          "clave": {
            "$ref": "#/components/schemas/Clave"
          },
          "secreto": {
            "type": "string",
            "pattern": "^onx_(live|test)_[A-Za-z0-9]{32,64}$",
            "description": "La clave completa. Se muestra solo esta vez: guárdala en un gestor de secretos."
          }
        },
        "required": [
          "clave",
          "secreto"
        ],
        "description": "Clave recién creada con su secreto, que no se vuelve a mostrar."
      },
      "ListaClaves": {
        "type": "object",
        "properties": {
          "elementos": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Clave"
            }
          },
          "siguiente_cursor": {
            "description": "Pásalo como `cursor` para la página siguiente; `null` si ya no hay más.",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "elementos",
          "siguiente_cursor"
        ],
        "description": "Página de resultados, del más reciente al más antiguo."
      },
      "CrearTicket": {
        "type": "object",
        "properties": {
          "asunto": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200,
            "description": "Qué pasa, en una línea."
          },
          "texto": {
            "type": "string",
            "minLength": 1,
            "maxLength": 5000,
            "description": "Detalle: qué hiciste, qué esperabas y qué pasó, con el `request_id` si lo tienes. Nunca pegues claves ni contraseñas."
          },
          "categoria": {
            "description": "Si no la envías, `soporte`.",
            "type": "string",
            "enum": [
              "soporte",
              "mejora",
              "facturacion",
              "seguridad"
            ]
          }
        },
        "required": [
          "asunto",
          "texto"
        ],
        "additionalProperties": false,
        "description": "Abre un ticket de soporte o propone una mejora."
      },
      "ResponderTicket": {
        "type": "object",
        "properties": {
          "texto": {
            "type": "string",
            "minLength": 1,
            "maxLength": 5000
          }
        },
        "required": [
          "texto"
        ],
        "additionalProperties": false,
        "description": "Tu respuesta en un ticket abierto."
      },
      "MensajeTicket": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^tkm_[A-Za-z0-9]{8,64}$",
            "description": "Identificador que empieza con `tkm_`.",
            "examples": [
              "tkm_8f2c1a7d9e"
            ]
          },
          "autor": {
            "type": "string",
            "enum": [
              "cliente",
              "soporte",
              "claude"
            ],
            "description": "`cliente`: tú; `soporte`: una persona de OpenNexum; `claude`: el asistente de soporte."
          },
          "texto": {
            "type": "string",
            "minLength": 1
          },
          "creado_en": {
            "$ref": "#/components/schemas/FechaHoraLima"
          }
        },
        "required": [
          "id",
          "autor",
          "texto",
          "creado_en"
        ],
        "description": "Un mensaje de un ticket."
      },
      "Ticket": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^tkt_[A-Za-z0-9]{8,64}$",
            "description": "Identificador que empieza con `tkt_`.",
            "examples": [
              "tkt_8f2c1a7d9e"
            ]
          },
          "asunto": {
            "type": "string",
            "minLength": 1
          },
          "categoria": {
            "type": "string",
            "enum": [
              "soporte",
              "mejora",
              "facturacion",
              "seguridad"
            ],
            "description": "`soporte`: algo no funciona · `mejora`: una idea · `facturacion`: saldo o facturas · `seguridad`: un riesgo."
          },
          "estado": {
            "type": "string",
            "enum": [
              "abierto",
              "en_revision",
              "respondido",
              "escalado",
              "cerrado"
            ],
            "description": "`abierto` espera respuesta; `respondido` espera la tuya; `cerrado` ya no recibe mensajes."
          },
          "creado_en": {
            "$ref": "#/components/schemas/FechaHoraLima"
          },
          "actualizado_en": {
            "$ref": "#/components/schemas/FechaHoraLima"
          },
          "cerrado_en": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/FechaHoraLima"
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "id",
          "asunto",
          "categoria",
          "estado",
          "creado_en",
          "actualizado_en",
          "cerrado_en"
        ],
        "description": "Ticket de soporte, sin sus mensajes."
      },
      "TicketDetalle": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^tkt_[A-Za-z0-9]{8,64}$",
            "description": "Identificador que empieza con `tkt_`.",
            "examples": [
              "tkt_8f2c1a7d9e"
            ]
          },
          "asunto": {
            "type": "string",
            "minLength": 1
          },
          "categoria": {
            "type": "string",
            "enum": [
              "soporte",
              "mejora",
              "facturacion",
              "seguridad"
            ],
            "description": "`soporte`: algo no funciona · `mejora`: una idea · `facturacion`: saldo o facturas · `seguridad`: un riesgo."
          },
          "estado": {
            "type": "string",
            "enum": [
              "abierto",
              "en_revision",
              "respondido",
              "escalado",
              "cerrado"
            ],
            "description": "`abierto` espera respuesta; `respondido` espera la tuya; `cerrado` ya no recibe mensajes."
          },
          "creado_en": {
            "$ref": "#/components/schemas/FechaHoraLima"
          },
          "actualizado_en": {
            "$ref": "#/components/schemas/FechaHoraLima"
          },
          "cerrado_en": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/FechaHoraLima"
              },
              {
                "type": "null"
              }
            ]
          },
          "mensajes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/MensajeTicket"
            },
            "description": "Del más antiguo al más nuevo."
          }
        },
        "required": [
          "id",
          "asunto",
          "categoria",
          "estado",
          "creado_en",
          "actualizado_en",
          "cerrado_en",
          "mensajes"
        ],
        "description": "Ticket de soporte con todos sus mensajes."
      },
      "ListaTickets": {
        "type": "object",
        "properties": {
          "elementos": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Ticket"
            }
          },
          "siguiente_cursor": {
            "description": "Pásalo como `cursor` para la página siguiente; `null` si ya no hay más.",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "elementos",
          "siguiente_cursor"
        ],
        "description": "Página de resultados, del más reciente al más antiguo."
      },
      "Contribuyente": {
        "type": "object",
        "properties": {
          "ruc": {
            "$ref": "#/components/schemas/Ruc"
          },
          "razon_social": {
            "type": "string",
            "minLength": 1
          },
          "estado": {
            "anyOf": [
              {
                "type": "string",
                "minLength": 1
              },
              {
                "type": "null"
              }
            ],
            "description": "Estado en SUNAT, por ejemplo ACTIVO o BAJA DE OFICIO; null si el padrón no lo trae."
          },
          "condicion": {
            "anyOf": [
              {
                "type": "string",
                "minLength": 1
              },
              {
                "type": "null"
              }
            ],
            "description": "Condición de domicilio, por ejemplo HABIDO o NO HABIDO; null si el padrón no la trae."
          },
          "ubigeo": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/Ubigeo"
              },
              {
                "type": "null"
              }
            ]
          },
          "direccion": {
            "type": [
              "string",
              "null"
            ]
          },
          "departamento": {
            "description": "Del ubigeo, con la tabla del INEI; null si el ubigeo no está en ella.",
            "type": [
              "string",
              "null"
            ]
          },
          "provincia": {
            "type": [
              "string",
              "null"
            ]
          },
          "distrito": {
            "type": [
              "string",
              "null"
            ]
          },
          "padron_actualizado_al": {
            "description": "Fecha del padrón reducido de SUNAT que respondió.",
            "$ref": "#/components/schemas/Fecha"
          }
        },
        "required": [
          "ruc",
          "razon_social",
          "estado",
          "condicion",
          "ubigeo",
          "direccion",
          "departamento",
          "provincia",
          "distrito",
          "padron_actualizado_al"
        ],
        "description": "Datos públicos del padrón reducido del RUC de SUNAT."
      },
      "Padrones": {
        "type": "object",
        "properties": {
          "ruc": {
            "$ref": "#/components/schemas/Ruc"
          },
          "agente_retencion": {
            "type": "object",
            "properties": {
              "incluido": {
                "type": "boolean"
              },
              "desde": {
                "anyOf": [
                  {
                    "$ref": "#/components/schemas/Fecha"
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "Desde cuándo figura, si SUNAT lo publica."
              },
              "resolucion": {
                "description": "Resolución que lo incorporó, si SUNAT la publica.",
                "type": [
                  "string",
                  "null"
                ]
              }
            },
            "required": [
              "incluido",
              "desde",
              "resolucion"
            ]
          },
          "agente_percepcion": {
            "type": "object",
            "properties": {
              "incluido": {
                "type": "boolean"
              },
              "desde": {
                "anyOf": [
                  {
                    "$ref": "#/components/schemas/Fecha"
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "Desde cuándo figura, si SUNAT lo publica."
              },
              "resolucion": {
                "description": "Resolución que lo incorporó, si SUNAT la publica.",
                "type": [
                  "string",
                  "null"
                ]
              }
            },
            "required": [
              "incluido",
              "desde",
              "resolucion"
            ]
          },
          "buen_contribuyente": {
            "type": "object",
            "properties": {
              "incluido": {
                "type": "boolean"
              },
              "desde": {
                "anyOf": [
                  {
                    "$ref": "#/components/schemas/Fecha"
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "Desde cuándo figura, si SUNAT lo publica."
              },
              "resolucion": {
                "description": "Resolución que lo incorporó, si SUNAT la publica.",
                "type": [
                  "string",
                  "null"
                ]
              }
            },
            "required": [
              "incluido",
              "desde",
              "resolucion"
            ]
          },
          "actualizado_al": {
            "description": "Fecha de la última descarga de los padrones de SUNAT.",
            "$ref": "#/components/schemas/Fecha"
          },
          "desactualizado": {
            "type": "boolean",
            "description": "`true` si la última descarga tiene más días de lo normal: tómalo con cuidado."
          }
        },
        "required": [
          "ruc",
          "agente_retencion",
          "agente_percepcion",
          "buen_contribuyente",
          "actualizado_al",
          "desactualizado"
        ],
        "description": "Si el RUC figura en los padrones de agentes de retención, de percepción y de buenos contribuyentes."
      },
      "TipoCambio": {
        "type": "object",
        "properties": {
          "fecha": {
            "description": "El día que pediste.",
            "$ref": "#/components/schemas/Fecha"
          },
          "publicado_el": {
            "description": "Día de la publicación usada; en feriados y fines de semana, la última anterior.",
            "$ref": "#/components/schemas/Fecha"
          },
          "moneda": {
            "type": "string",
            "const": "USD"
          },
          "compra": {
            "$ref": "#/components/schemas/TipoCambioValor"
          },
          "venta": {
            "$ref": "#/components/schemas/TipoCambioValor"
          },
          "fuente": {
            "type": "string",
            "enum": [
              "BCRP"
            ],
            "description": "Fuente oficial del dato."
          }
        },
        "required": [
          "fecha",
          "publicado_el",
          "moneda",
          "compra",
          "venta",
          "fuente"
        ],
        "description": "Tipo de cambio oficial del dólar en soles."
      },
      "CredencialesEmision": {
        "type": "object",
        "properties": {
          "certificado": {
            "type": "object",
            "properties": {
              "pfx_base64": {
                "type": "string",
                "minLength": 1,
                "maxLength": 100000,
                "format": "base64",
                "contentEncoding": "base64",
                "pattern": "^$|^(?:[0-9a-zA-Z+/]{4})*(?:(?:[0-9a-zA-Z+/]{2}==)|(?:[0-9a-zA-Z+/]{3}=))?$",
                "description": "Archivo .pfx o .p12 del certificado digital, en base64."
              },
              "clave": {
                "type": "string",
                "minLength": 1,
                "maxLength": 100,
                "format": "password",
                "description": "Contraseña del archivo .pfx."
              }
            },
            "required": [
              "pfx_base64",
              "clave"
            ],
            "additionalProperties": false,
            "writeOnly": true,
            "description": "Certificado digital del emisor. Nunca se guarda en registros ni se devuelve."
          },
          "sol": {
            "type": "object",
            "properties": {
              "usuario": {
                "type": "string",
                "pattern": "^[A-Za-z0-9]{1,20}$",
                "description": "Usuario secundario SOL, sin el RUC (lo agregamos con el RUC del emisor)."
              },
              "clave": {
                "type": "string",
                "minLength": 1,
                "maxLength": 100,
                "format": "password",
                "description": "Clave SOL del usuario secundario."
              }
            },
            "required": [
              "usuario",
              "clave"
            ],
            "additionalProperties": false,
            "writeOnly": true,
            "description": "Usuario secundario SOL del emisor. Nunca se guarda en registros ni se devuelve."
          }
        },
        "required": [
          "certificado",
          "sol"
        ],
        "additionalProperties": false,
        "writeOnly": true,
        "description": "Credenciales por llamada: se usan solo en esta petición y no se guardan. Requiere el permiso `credenciales:por_llamada`. Si tu RUC usa la bóveda, no las envíes. Para emitir, dar de baja y resúmenes."
      },
      "CredencialesGuia": {
        "type": "object",
        "properties": {
          "certificado": {
            "type": "object",
            "properties": {
              "pfx_base64": {
                "type": "string",
                "minLength": 1,
                "maxLength": 100000,
                "format": "base64",
                "contentEncoding": "base64",
                "pattern": "^$|^(?:[0-9a-zA-Z+/]{4})*(?:(?:[0-9a-zA-Z+/]{2}==)|(?:[0-9a-zA-Z+/]{3}=))?$",
                "description": "Archivo .pfx o .p12 del certificado digital, en base64."
              },
              "clave": {
                "type": "string",
                "minLength": 1,
                "maxLength": 100,
                "format": "password",
                "description": "Contraseña del archivo .pfx."
              }
            },
            "required": [
              "pfx_base64",
              "clave"
            ],
            "additionalProperties": false,
            "writeOnly": true,
            "description": "Certificado digital del emisor. Nunca se guarda en registros ni se devuelve."
          },
          "sol": {
            "type": "object",
            "properties": {
              "usuario": {
                "type": "string",
                "pattern": "^[A-Za-z0-9]{1,20}$",
                "description": "Usuario secundario SOL, sin el RUC (lo agregamos con el RUC del emisor)."
              },
              "clave": {
                "type": "string",
                "minLength": 1,
                "maxLength": 100,
                "format": "password",
                "description": "Clave SOL del usuario secundario."
              }
            },
            "required": [
              "usuario",
              "clave"
            ],
            "additionalProperties": false,
            "writeOnly": true,
            "description": "Usuario secundario SOL del emisor. Nunca se guarda en registros ni se devuelve."
          },
          "api_sunat": {
            "type": "object",
            "properties": {
              "client_id": {
                "type": "string",
                "minLength": 1,
                "maxLength": 100
              },
              "client_secret": {
                "type": "string",
                "minLength": 1,
                "maxLength": 200,
                "format": "password"
              }
            },
            "required": [
              "client_id",
              "client_secret"
            ],
            "additionalProperties": false,
            "writeOnly": true,
            "description": "Credenciales de la API de SUNAT (guías y SIRE), generadas en SOL. Nunca se guarda en registros ni se devuelve."
          }
        },
        "required": [
          "certificado",
          "sol",
          "api_sunat"
        ],
        "additionalProperties": false,
        "writeOnly": true,
        "description": "Credenciales por llamada: se usan solo en esta petición y no se guardan. Requiere el permiso `credenciales:por_llamada`. Si tu RUC usa la bóveda, no las envíes. Para guías de remisión."
      },
      "CredencialesSire": {
        "type": "object",
        "properties": {
          "sol": {
            "type": "object",
            "properties": {
              "usuario": {
                "type": "string",
                "pattern": "^[A-Za-z0-9]{1,20}$",
                "description": "Usuario secundario SOL, sin el RUC (lo agregamos con el RUC del emisor)."
              },
              "clave": {
                "type": "string",
                "minLength": 1,
                "maxLength": 100,
                "format": "password",
                "description": "Clave SOL del usuario secundario."
              }
            },
            "required": [
              "usuario",
              "clave"
            ],
            "additionalProperties": false,
            "writeOnly": true,
            "description": "Usuario secundario SOL del emisor. Nunca se guarda en registros ni se devuelve."
          },
          "api_sunat": {
            "type": "object",
            "properties": {
              "client_id": {
                "type": "string",
                "minLength": 1,
                "maxLength": 100
              },
              "client_secret": {
                "type": "string",
                "minLength": 1,
                "maxLength": 200,
                "format": "password"
              }
            },
            "required": [
              "client_id",
              "client_secret"
            ],
            "additionalProperties": false,
            "writeOnly": true,
            "description": "Credenciales de la API de SUNAT (guías y SIRE), generadas en SOL. Nunca se guarda en registros ni se devuelve."
          }
        },
        "required": [
          "sol",
          "api_sunat"
        ],
        "additionalProperties": false,
        "writeOnly": true,
        "description": "Credenciales por llamada: se usan solo en esta petición y no se guardan. Requiere el permiso `credenciales:por_llamada`. Si tu RUC usa la bóveda, no las envíes. Para el SIRE."
      },
      "CredencialesConsulta": {
        "type": "object",
        "properties": {
          "sol": {
            "type": "object",
            "properties": {
              "usuario": {
                "type": "string",
                "pattern": "^[A-Za-z0-9]{1,20}$",
                "description": "Usuario secundario SOL, sin el RUC (lo agregamos con el RUC del emisor)."
              },
              "clave": {
                "type": "string",
                "minLength": 1,
                "maxLength": 100,
                "format": "password",
                "description": "Clave SOL del usuario secundario."
              }
            },
            "required": [
              "usuario",
              "clave"
            ],
            "additionalProperties": false,
            "writeOnly": true,
            "description": "Usuario secundario SOL del emisor. Nunca se guarda en registros ni se devuelve."
          }
        },
        "required": [
          "sol"
        ],
        "additionalProperties": false,
        "writeOnly": true,
        "description": "Credenciales por llamada: se usan solo en esta petición y no se guardan. Requiere el permiso `credenciales:por_llamada`. Si tu RUC usa la bóveda, no las envíes. Para consultar el estado en SUNAT."
      },
      "GuardarCredenciales": {
        "type": "object",
        "properties": {
          "certificado": {
            "type": "object",
            "properties": {
              "pfx_base64": {
                "type": "string",
                "minLength": 1,
                "maxLength": 100000,
                "format": "base64",
                "contentEncoding": "base64",
                "pattern": "^$|^(?:[0-9a-zA-Z+/]{4})*(?:(?:[0-9a-zA-Z+/]{2}==)|(?:[0-9a-zA-Z+/]{3}=))?$",
                "description": "Archivo .pfx o .p12 del certificado digital, en base64."
              },
              "clave": {
                "type": "string",
                "minLength": 1,
                "maxLength": 100,
                "format": "password",
                "description": "Contraseña del archivo .pfx."
              }
            },
            "required": [
              "pfx_base64",
              "clave"
            ],
            "additionalProperties": false,
            "writeOnly": true,
            "description": "Certificado digital del emisor. Nunca se guarda en registros ni se devuelve."
          },
          "sol": {
            "type": "object",
            "properties": {
              "usuario": {
                "type": "string",
                "pattern": "^[A-Za-z0-9]{1,20}$",
                "description": "Usuario secundario SOL, sin el RUC (lo agregamos con el RUC del emisor)."
              },
              "clave": {
                "type": "string",
                "minLength": 1,
                "maxLength": 100,
                "format": "password",
                "description": "Clave SOL del usuario secundario."
              }
            },
            "required": [
              "usuario",
              "clave"
            ],
            "additionalProperties": false,
            "writeOnly": true,
            "description": "Usuario secundario SOL del emisor. Nunca se guarda en registros ni se devuelve."
          },
          "api_sunat": {
            "type": "object",
            "properties": {
              "client_id": {
                "type": "string",
                "minLength": 1,
                "maxLength": 100
              },
              "client_secret": {
                "type": "string",
                "minLength": 1,
                "maxLength": 200,
                "format": "password"
              }
            },
            "required": [
              "client_id",
              "client_secret"
            ],
            "additionalProperties": false,
            "writeOnly": true,
            "description": "Credenciales de la API de SUNAT (guías y SIRE), generadas en SOL. Nunca se guarda en registros ni se devuelve."
          }
        },
        "required": [
          "certificado",
          "sol"
        ],
        "additionalProperties": false,
        "writeOnly": true,
        "description": "Guarda las credenciales en la bóveda cifrada. Solo funciona cuando la bóveda está activa; si no, responde `boveda_inactiva`. El certificado debe ser del mismo RUC."
      },
      "EstadoCredenciales": {
        "type": "object",
        "properties": {
          "ruc": {
            "$ref": "#/components/schemas/Ruc"
          },
          "modo": {
            "type": "string",
            "const": "boveda"
          },
          "certificado": {
            "type": "object",
            "properties": {
              "titular_ruc": {
                "$ref": "#/components/schemas/Ruc"
              },
              "vence_el": {
                "$ref": "#/components/schemas/Fecha"
              },
              "huella_sha256": {
                "type": "string",
                "pattern": "^[0-9a-f]{64}$",
                "description": "Huella del certificado, para reconocerlo."
              }
            },
            "required": [
              "titular_ruc",
              "vence_el",
              "huella_sha256"
            ]
          },
          "sol": {
            "type": "object",
            "properties": {
              "usuario": {
                "type": "string",
                "minLength": 1
              }
            },
            "required": [
              "usuario"
            ]
          },
          "api_sunat": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "client_id": {
                    "type": "string",
                    "minLength": 1
                  }
                },
                "required": [
                  "client_id"
                ]
              },
              {
                "type": "null"
              }
            ]
          },
          "actualizadas_en": {
            "$ref": "#/components/schemas/FechaHoraLima"
          },
          "version": {
            "type": "integer",
            "exclusiveMinimum": 0,
            "maximum": 9007199254740991,
            "description": "Sube con cada cambio de credenciales."
          }
        },
        "required": [
          "ruc",
          "modo",
          "certificado",
          "sol",
          "api_sunat",
          "actualizadas_en",
          "version"
        ],
        "description": "Lo que queda a la vista de las credenciales guardadas. Nunca incluye contraseñas ni el certificado."
      },
      "CrearEmisor": {
        "type": "object",
        "properties": {
          "ruc": {
            "$ref": "#/components/schemas/Ruc"
          },
          "nombre_comercial": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200
          },
          "direccion_fiscal": {
            "description": "Si no la envías, usamos la del padrón de SUNAT.",
            "type": "object",
            "properties": {
              "ubigeo": {
                "$ref": "#/components/schemas/Ubigeo"
              },
              "direccion": {
                "type": "string",
                "minLength": 1,
                "maxLength": 200
              },
              "codigo_establecimiento": {
                "description": "Código de establecimiento anexo en SUNAT; 0000 es el domicilio fiscal.",
                "type": "string",
                "pattern": "^\\d{4}$"
              }
            },
            "required": [
              "ubigeo",
              "direccion"
            ],
            "additionalProperties": false
          }
        },
        "required": [
          "ruc"
        ],
        "additionalProperties": false,
        "description": "Registra un RUC emisor en tu cuenta. La razón social sale del padrón de SUNAT. Un RUC vive en una sola cuenta por entorno; los obligados a OSE no se aceptan en la v1."
      },
      "Emisor": {
        "type": "object",
        "properties": {
          "ruc": {
            "$ref": "#/components/schemas/Ruc"
          },
          "razon_social": {
            "type": "string",
            "minLength": 1
          },
          "nombre_comercial": {
            "type": [
              "string",
              "null"
            ]
          },
          "direccion_fiscal": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "ubigeo": {
                    "$ref": "#/components/schemas/Ubigeo"
                  },
                  "direccion": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 200
                  },
                  "codigo_establecimiento": {
                    "description": "Código de establecimiento anexo en SUNAT; 0000 es el domicilio fiscal.",
                    "type": "string",
                    "pattern": "^\\d{4}$"
                  }
                },
                "required": [
                  "ubigeo",
                  "direccion"
                ],
                "additionalProperties": false
              },
              {
                "type": "null"
              }
            ]
          },
          "entorno": {
            "type": "string",
            "enum": [
              "beta",
              "produccion"
            ],
            "description": "`beta` en sandbox (SUNAT beta); `produccion` en producción."
          },
          "modo_credenciales": {
            "type": "string",
            "enum": [
              "por_llamada",
              "boveda"
            ],
            "description": "`por_llamada`: envías `credenciales` en cada emisión. `boveda`: las guardamos cifradas."
          },
          "credenciales_guardadas": {
            "type": "boolean"
          },
          "creado_en": {
            "$ref": "#/components/schemas/FechaHoraLima"
          }
        },
        "required": [
          "ruc",
          "razon_social",
          "nombre_comercial",
          "direccion_fiscal",
          "entorno",
          "modo_credenciales",
          "credenciales_guardadas",
          "creado_en"
        ],
        "description": "RUC emisor registrado en tu cuenta."
      },
      "ListaEmisores": {
        "type": "object",
        "properties": {
          "elementos": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Emisor"
            }
          },
          "siguiente_cursor": {
            "description": "Pásalo como `cursor` para la página siguiente; `null` si ya no hay más.",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "elementos",
          "siguiente_cursor"
        ],
        "description": "Página de resultados, del más reciente al más antiguo."
      },
      "CrearSerie": {
        "type": "object",
        "properties": {
          "tipo": {
            "type": "string",
            "enum": [
              "01",
              "03",
              "07",
              "08",
              "09"
            ],
            "description": "01 factura, 03 boleta, 07 nota de crédito, 08 nota de débito, 09 guía de remisión remitente."
          },
          "serie": {
            "type": "string",
            "pattern": "^[FBT][A-Z0-9]{3}$"
          },
          "ultimo_numero": {
            "description": "Si vienes de otro sistema, el último número que usaste; seguimos desde el siguiente.",
            "type": "integer",
            "minimum": 0,
            "maximum": 99999999
          }
        },
        "required": [
          "tipo",
          "serie"
        ],
        "additionalProperties": false,
        "description": "Crea una serie. La numeración la asigna el servidor, sin saltos ni duplicados."
      },
      "Serie": {
        "type": "object",
        "properties": {
          "tipo": {
            "type": "string",
            "enum": [
              "01",
              "03",
              "07",
              "08",
              "09"
            ],
            "description": "01 factura, 03 boleta, 07 nota de crédito, 08 nota de débito, 09 guía de remisión remitente."
          },
          "serie": {
            "type": "string",
            "pattern": "^[FBT][A-Z0-9]{3}$"
          },
          "ultimo_numero": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991,
            "description": "Último número asignado; el próximo será este + 1."
          },
          "creada_en": {
            "$ref": "#/components/schemas/FechaHoraLima"
          }
        },
        "required": [
          "tipo",
          "serie",
          "ultimo_numero",
          "creada_en"
        ],
        "description": "Serie de un emisor."
      },
      "ListaSeries": {
        "type": "object",
        "properties": {
          "elementos": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Serie"
            }
          },
          "siguiente_cursor": {
            "description": "Pásalo como `cursor` para la página siguiente; `null` si ya no hay más.",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "elementos",
          "siguiente_cursor"
        ],
        "description": "Página de resultados, del más reciente al más antiguo."
      },
      "Cliente": {
        "type": "object",
        "properties": {
          "tipo_documento": {
            "type": "string",
            "enum": [
              "0",
              "1",
              "4",
              "6",
              "7"
            ],
            "description": "Catálogo 06: 0 sin documento, 1 DNI, 4 carné de extranjería, 6 RUC, 7 pasaporte."
          },
          "numero_documento": {
            "type": "string",
            "minLength": 1,
            "maxLength": 15,
            "description": "Número del documento; en tipo 0 puede ir «-»."
          },
          "nombre": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200,
            "description": "Razón social o nombre completo."
          },
          "direccion": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200
          },
          "correo": {
            "description": "Si lo envías, le mandamos el PDF y el XML.",
            "type": "string",
            "maxLength": 254,
            "format": "email",
            "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
          }
        },
        "required": [
          "tipo_documento",
          "numero_documento",
          "nombre"
        ],
        "additionalProperties": false,
        "description": "A quién se le emite."
      },
      "ItemComprobante": {
        "type": "object",
        "properties": {
          "descripcion": {
            "type": "string",
            "minLength": 1,
            "maxLength": 500
          },
          "cantidad": {
            "$ref": "#/components/schemas/Cantidad"
          },
          "unidad": {
            "description": "Unidad del catálogo 03, por ejemplo NIU (bienes) o ZZ (servicios). Por defecto NIU.",
            "type": "string",
            "pattern": "^[A-Z0-9]{1,3}$"
          },
          "codigo": {
            "description": "Tu código interno del producto.",
            "type": "string",
            "minLength": 1,
            "maxLength": 30
          },
          "codigo_sunat": {
            "description": "Código de producto SUNAT (catálogo 25).",
            "type": "string",
            "pattern": "^\\d{8}$"
          },
          "precio_unitario": {
            "type": "string",
            "pattern": "^(0|[1-9]\\d{0,11})\\.\\d{2,6}$",
            "description": "Precio por unidad con IGV incluido, el que paga tu cliente. En exonerado e inafecto es el valor por unidad; en gratuitas, el valor referencial (mayor que cero).",
            "examples": [
              "1250.50"
            ],
            "$ref": "#/components/schemas/PrecioUnitario"
          },
          "afectacion_igv": {
            "type": "string",
            "enum": [
              "10",
              "11",
              "12",
              "13",
              "14",
              "15",
              "16",
              "20",
              "30",
              "31",
              "32",
              "33",
              "34",
              "35",
              "36",
              "37"
            ],
            "description": "Catálogo 07: 10 gravado, 20 exonerado, 30 inafecto; 11–16 y 31–37 son transferencias gratuitas."
          },
          "icbper": {
            "description": "`true` si la línea son bolsas plásticas: se suma el ICBPER por bolsa.",
            "type": "boolean"
          }
        },
        "required": [
          "descripcion",
          "cantidad",
          "precio_unitario",
          "afectacion_igv"
        ],
        "additionalProperties": false,
        "description": "Línea del comprobante. Los totales los calculamos nosotros."
      },
      "FormaPago": {
        "oneOf": [
          {
            "type": "object",
            "properties": {
              "tipo": {
                "type": "string",
                "const": "contado"
              }
            },
            "required": [
              "tipo"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "tipo": {
                "type": "string",
                "const": "credito"
              },
              "cuotas": {
                "minItems": 1,
                "maxItems": 60,
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "monto": {
                      "$ref": "#/components/schemas/Monto"
                    },
                    "fecha_vencimiento": {
                      "$ref": "#/components/schemas/Fecha"
                    }
                  },
                  "required": [
                    "monto",
                    "fecha_vencimiento"
                  ],
                  "additionalProperties": false
                }
              }
            },
            "required": [
              "tipo",
              "cuotas"
            ],
            "additionalProperties": false
          }
        ],
        "description": "Contado o crédito con cuotas. Si no la envías, es al contado."
      },
      "Detraccion": {
        "type": "object",
        "properties": {
          "codigo_bien_servicio": {
            "type": "string",
            "pattern": "^\\d{3}$",
            "description": "Catálogo 54, por ejemplo 022 (otros servicios)."
          },
          "porcentaje": {
            "type": "string",
            "pattern": "^\\d{1,2}\\.\\d{2}$",
            "description": "Porcentaje con dos decimales, por ejemplo \"12.00\"."
          },
          "monto": {
            "description": "Monto de la detracción en soles.",
            "$ref": "#/components/schemas/Monto"
          },
          "cuenta_banco_nacion": {
            "type": "string",
            "pattern": "^\\d{8,20}$",
            "description": "Cuenta de detracciones del Banco de la Nación."
          },
          "medio_pago": {
            "description": "Catálogo 59; por defecto 001 (depósito en cuenta).",
            "type": "string",
            "pattern": "^\\d{3}$"
          }
        },
        "required": [
          "codigo_bien_servicio",
          "porcentaje",
          "monto",
          "cuenta_banco_nacion"
        ],
        "additionalProperties": false,
        "description": "Detracción (SPOT). Solo en facturas."
      },
      "EmitirComprobante": {
        "type": "object",
        "properties": {
          "tipo": {
            "type": "string",
            "enum": [
              "01",
              "03",
              "07",
              "08"
            ],
            "description": "01 factura, 03 boleta, 07 nota de crédito, 08 nota de débito."
          },
          "serie": {
            "type": "string",
            "pattern": "^[FB][A-Z0-9]{3}$",
            "description": "Serie registrada del emisor. El número lo asigna el servidor."
          },
          "fecha_emision": {
            "description": "Por defecto, hoy en Lima. SUNAT acepta pocos días hacia atrás.",
            "$ref": "#/components/schemas/Fecha"
          },
          "fecha_vencimiento": {
            "$ref": "#/components/schemas/Fecha"
          },
          "moneda": {
            "type": "string",
            "enum": [
              "PEN",
              "USD"
            ],
            "description": "Código ISO 4217: PEN (soles) o USD (dólares)."
          },
          "tipo_cambio": {
            "description": "Obligatorio en dólares; no va en soles.",
            "$ref": "#/components/schemas/TipoCambioValor"
          },
          "cliente": {
            "$ref": "#/components/schemas/Cliente"
          },
          "items": {
            "minItems": 1,
            "maxItems": 500,
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ItemComprobante"
            }
          },
          "forma_pago": {
            "$ref": "#/components/schemas/FormaPago"
          },
          "detraccion": {
            "$ref": "#/components/schemas/Detraccion"
          },
          "referencia": {
            "description": "Solo notas: el comprobante que modificas.",
            "type": "object",
            "properties": {
              "tipo": {
                "type": "string",
                "enum": [
                  "01",
                  "03"
                ]
              },
              "serie": {
                "type": "string",
                "pattern": "^[FB][A-Z0-9]{3}$"
              },
              "numero": {
                "type": "integer",
                "minimum": 1,
                "maximum": 99999999
              }
            },
            "required": [
              "tipo",
              "serie",
              "numero"
            ],
            "additionalProperties": false
          },
          "motivo": {
            "description": "Solo notas: el motivo con su código de catálogo.",
            "type": "object",
            "properties": {
              "codigo": {
                "type": "string",
                "pattern": "^\\d{2}$",
                "description": "Catálogo 09 (crédito) o 10 (débito), por ejemplo 01."
              },
              "descripcion": {
                "type": "string",
                "minLength": 1,
                "maxLength": 250
              }
            },
            "required": [
              "codigo",
              "descripcion"
            ],
            "additionalProperties": false
          },
          "observacion": {
            "type": "string",
            "maxLength": 500
          },
          "orden_compra": {
            "type": "string",
            "maxLength": 20
          },
          "credenciales": {
            "$ref": "#/components/schemas/CredencialesEmision"
          }
        },
        "required": [
          "tipo",
          "serie",
          "moneda",
          "cliente",
          "items"
        ],
        "additionalProperties": false,
        "description": "Comprobante a emitir: factura (01), boleta (03), nota de crédito (07) o nota de débito (08). No envíes `numero`: lo asigna el servidor sin saltos ni duplicados."
      },
      "Totales": {
        "type": "object",
        "properties": {
          "gravado": {
            "$ref": "#/components/schemas/Monto"
          },
          "exonerado": {
            "$ref": "#/components/schemas/Monto"
          },
          "inafecto": {
            "$ref": "#/components/schemas/Monto"
          },
          "gratuito": {
            "$ref": "#/components/schemas/Monto"
          },
          "igv": {
            "$ref": "#/components/schemas/Monto"
          },
          "icbper": {
            "$ref": "#/components/schemas/Monto"
          },
          "total": {
            "description": "Importe total que paga el cliente.",
            "$ref": "#/components/schemas/Monto"
          }
        },
        "required": [
          "gravado",
          "exonerado",
          "inafecto",
          "gratuito",
          "igv",
          "icbper",
          "total"
        ],
        "description": "Totales calculados por el servidor."
      },
      "ResultadoValidacion": {
        "type": "object",
        "properties": {
          "valido": {
            "type": "boolean"
          },
          "totales": {
            "$ref": "#/components/schemas/Totales"
          },
          "problemas": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "campo": {
                  "type": "string"
                },
                "mensaje": {
                  "type": "string"
                }
              },
              "required": [
                "campo",
                "mensaje"
              ]
            },
            "description": "Reglas de negocio o de SUNAT que fallarían al emitir."
          }
        },
        "required": [
          "valido",
          "totales",
          "problemas"
        ],
        "description": "Resultado del ensayo: calcula totales y revisa reglas sin emitir, sin numerar y sin cobrar."
      },
      "Comprobante": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^cmp_[A-Za-z0-9]{8,64}$",
            "description": "Identificador que empieza con `cmp_`.",
            "examples": [
              "cmp_8f2c1a7d9e"
            ]
          },
          "emisor_ruc": {
            "$ref": "#/components/schemas/Ruc"
          },
          "tipo": {
            "type": "string",
            "enum": [
              "01",
              "03",
              "07",
              "08"
            ],
            "description": "01 factura, 03 boleta, 07 nota de crédito, 08 nota de débito."
          },
          "serie": {
            "type": "string",
            "pattern": "^[FB][A-Z0-9]{3}$"
          },
          "numero": {
            "type": "integer",
            "exclusiveMinimum": 0,
            "maximum": 9007199254740991,
            "description": "Asignado por el servidor."
          },
          "numero_completo": {
            "type": "string",
            "pattern": "^[FB][A-Z0-9]{3}-\\d{1,8}$",
            "description": "Serie y número, por ejemplo F001-124."
          },
          "fecha_emision": {
            "$ref": "#/components/schemas/Fecha"
          },
          "moneda": {
            "type": "string",
            "enum": [
              "PEN",
              "USD"
            ],
            "description": "Código ISO 4217: PEN (soles) o USD (dólares)."
          },
          "tipo_cambio": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/TipoCambioValor"
              },
              {
                "type": "null"
              }
            ]
          },
          "cliente": {
            "$ref": "#/components/schemas/Cliente"
          },
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ItemComprobante"
            }
          },
          "forma_pago": {
            "$ref": "#/components/schemas/FormaPago"
          },
          "totales": {
            "$ref": "#/components/schemas/Totales"
          },
          "referencia": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "tipo": {
                    "type": "string",
                    "enum": [
                      "01",
                      "03"
                    ]
                  },
                  "serie": {
                    "type": "string",
                    "pattern": "^[FB][A-Z0-9]{3}$"
                  },
                  "numero": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 99999999
                  }
                },
                "required": [
                  "tipo",
                  "serie",
                  "numero"
                ],
                "additionalProperties": false
              },
              {
                "type": "null"
              }
            ]
          },
          "motivo": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "codigo": {
                    "type": "string",
                    "pattern": "^\\d{2}$",
                    "description": "Catálogo 09 (crédito) o 10 (débito), por ejemplo 01."
                  },
                  "descripcion": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 250
                  }
                },
                "required": [
                  "codigo",
                  "descripcion"
                ],
                "additionalProperties": false
              },
              {
                "type": "null"
              }
            ]
          },
          "estado": {
            "type": "string",
            "enum": [
              "en_cola",
              "aceptado",
              "observado",
              "rechazado",
              "en_baja",
              "anulado"
            ],
            "description": "`en_cola`: guardado y esperando a SUNAT. `observado`: aceptado con observaciones. `en_baja`: anulación en curso."
          },
          "sunat": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "codigo": {
                    "type": "string",
                    "minLength": 1,
                    "description": "Código de respuesta de SUNAT; 0 es aceptado."
                  },
                  "descripcion": {
                    "type": "string"
                  },
                  "observaciones": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  }
                },
                "required": [
                  "codigo",
                  "descripcion",
                  "observaciones"
                ],
                "description": "Lo que respondió SUNAT en el CDR."
              },
              {
                "type": "null"
              }
            ]
          },
          "hash": {
            "description": "Valor del resumen (DigestValue) de la firma, el que va en el QR.",
            "type": [
              "string",
              "null"
            ]
          },
          "enlaces": {
            "type": "object",
            "properties": {
              "xml": {
                "type": "string",
                "format": "starts_with",
                "pattern": "^\\/v1\\/.*"
              },
              "cdr": {
                "anyOf": [
                  {
                    "type": "string",
                    "format": "starts_with",
                    "pattern": "^\\/v1\\/.*"
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "`null` mientras SUNAT no responde."
              },
              "pdf": {
                "type": "string",
                "format": "starts_with",
                "pattern": "^\\/v1\\/.*"
              }
            },
            "required": [
              "xml",
              "cdr",
              "pdf"
            ]
          },
          "creado_en": {
            "$ref": "#/components/schemas/FechaHoraLima"
          },
          "actualizado_en": {
            "$ref": "#/components/schemas/FechaHoraLima"
          }
        },
        "required": [
          "id",
          "emisor_ruc",
          "tipo",
          "serie",
          "numero",
          "numero_completo",
          "fecha_emision",
          "moneda",
          "tipo_cambio",
          "cliente",
          "items",
          "forma_pago",
          "totales",
          "referencia",
          "motivo",
          "estado",
          "sunat",
          "hash",
          "enlaces",
          "creado_en",
          "actualizado_en"
        ],
        "description": "Comprobante emitido."
      },
      "ListaComprobantes": {
        "type": "object",
        "properties": {
          "elementos": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Comprobante"
            }
          },
          "siguiente_cursor": {
            "description": "Pásalo como `cursor` para la página siguiente; `null` si ya no hay más.",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "elementos",
          "siguiente_cursor"
        ],
        "description": "Página de resultados, del más reciente al más antiguo."
      },
      "AnularComprobante": {
        "type": "object",
        "properties": {
          "motivo": {
            "type": "string",
            "minLength": 1,
            "maxLength": 100,
            "description": "Motivo de la baja que verá SUNAT."
          },
          "credenciales": {
            "$ref": "#/components/schemas/CredencialesEmision"
          }
        },
        "required": [
          "motivo"
        ],
        "additionalProperties": false,
        "description": "Da de baja el comprobante: comunicación de baja para facturas y resumen diario para boletas, dentro del plazo de SUNAT. Fuera de plazo, emite una nota de crédito."
      },
      "ConsultarSunat": {
        "type": "object",
        "properties": {
          "credenciales": {
            "$ref": "#/components/schemas/CredencialesConsulta"
          }
        },
        "additionalProperties": false,
        "description": "Pregunta a SUNAT el estado actual del comprobante y guarda el CDR si llega."
      },
      "CrearResumen": {
        "type": "object",
        "properties": {
          "fecha": {
            "description": "Día de emisión de las boletas a informar.",
            "$ref": "#/components/schemas/Fecha"
          },
          "credenciales": {
            "$ref": "#/components/schemas/CredencialesEmision"
          }
        },
        "required": [
          "fecha"
        ],
        "additionalProperties": false,
        "description": "Arma y envía el resumen diario de las boletas de ese día que aún no se informaron."
      },
      "Resumen": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^res_[A-Za-z0-9]{8,64}$",
            "description": "Identificador que empieza con `res_`.",
            "examples": [
              "res_8f2c1a7d9e"
            ]
          },
          "emisor_ruc": {
            "$ref": "#/components/schemas/Ruc"
          },
          "tipo": {
            "type": "string",
            "enum": [
              "RC",
              "RA"
            ],
            "description": "RC resumen diario; RA comunicación de baja."
          },
          "fecha_referencia": {
            "$ref": "#/components/schemas/Fecha"
          },
          "estado": {
            "type": "string",
            "enum": [
              "en_cola",
              "enviado",
              "aceptado",
              "rechazado"
            ]
          },
          "ticket": {
            "description": "Ticket que dio SUNAT al recibirlo.",
            "type": [
              "string",
              "null"
            ]
          },
          "cantidad_comprobantes": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991
          },
          "sunat": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "codigo": {
                    "type": "string",
                    "minLength": 1,
                    "description": "Código de respuesta de SUNAT; 0 es aceptado."
                  },
                  "descripcion": {
                    "type": "string"
                  },
                  "observaciones": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  }
                },
                "required": [
                  "codigo",
                  "descripcion",
                  "observaciones"
                ],
                "description": "Lo que respondió SUNAT en el CDR."
              },
              {
                "type": "null"
              }
            ]
          },
          "creado_en": {
            "$ref": "#/components/schemas/FechaHoraLima"
          },
          "actualizado_en": {
            "$ref": "#/components/schemas/FechaHoraLima"
          }
        },
        "required": [
          "id",
          "emisor_ruc",
          "tipo",
          "fecha_referencia",
          "estado",
          "ticket",
          "cantidad_comprobantes",
          "sunat",
          "creado_en",
          "actualizado_en"
        ],
        "description": "Resumen diario o comunicación de baja enviado a SUNAT."
      },
      "ListaResumenes": {
        "type": "object",
        "properties": {
          "elementos": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Resumen"
            }
          },
          "siguiente_cursor": {
            "description": "Pásalo como `cursor` para la página siguiente; `null` si ya no hay más.",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "elementos",
          "siguiente_cursor"
        ],
        "description": "Página de resultados, del más reciente al más antiguo."
      },
      "EmitirGuia": {
        "type": "object",
        "properties": {
          "serie": {
            "type": "string",
            "pattern": "^T[A-Z0-9]{3}$"
          },
          "fecha_emision": {
            "$ref": "#/components/schemas/Fecha"
          },
          "destinatario": {
            "type": "object",
            "properties": {
              "tipo_documento": {
                "type": "string",
                "enum": [
                  "1",
                  "4",
                  "6",
                  "7"
                ]
              },
              "numero_documento": {
                "type": "string",
                "minLength": 1,
                "maxLength": 15
              },
              "nombre": {
                "type": "string",
                "minLength": 1,
                "maxLength": 200
              }
            },
            "required": [
              "tipo_documento",
              "numero_documento",
              "nombre"
            ],
            "additionalProperties": false
          },
          "motivo_traslado": {
            "type": "object",
            "properties": {
              "codigo": {
                "type": "string",
                "pattern": "^\\d{2}$",
                "description": "Catálogo 20, por ejemplo 01 venta."
              },
              "descripcion": {
                "type": "string",
                "minLength": 1,
                "maxLength": 200
              }
            },
            "required": [
              "codigo"
            ],
            "additionalProperties": false
          },
          "peso_bruto_kg": {
            "type": "string",
            "pattern": "^\\d{1,9}(\\.\\d{1,3})?$"
          },
          "numero_bultos": {
            "type": "integer",
            "exclusiveMinimum": 0,
            "maximum": 9007199254740991
          },
          "modalidad": {
            "type": "string",
            "enum": [
              "01",
              "02"
            ],
            "description": "Catálogo 18: 01 transporte público, 02 transporte privado."
          },
          "fecha_inicio_traslado": {
            "$ref": "#/components/schemas/Fecha"
          },
          "transportista": {
            "description": "Obligatorio en transporte público (01).",
            "type": "object",
            "properties": {
              "ruc": {
                "$ref": "#/components/schemas/Ruc"
              },
              "razon_social": {
                "type": "string",
                "minLength": 1,
                "maxLength": 200
              },
              "registro_mtc": {
                "type": "string",
                "minLength": 1,
                "maxLength": 20
              }
            },
            "required": [
              "ruc",
              "razon_social"
            ],
            "additionalProperties": false
          },
          "conductores": {
            "description": "Obligatorio en transporte privado (02).",
            "minItems": 1,
            "maxItems": 10,
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "tipo_documento": {
                  "type": "string",
                  "enum": [
                    "1",
                    "4",
                    "7"
                  ]
                },
                "numero_documento": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 15
                },
                "nombres": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 100
                },
                "apellidos": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 100
                },
                "licencia": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 20
                }
              },
              "required": [
                "tipo_documento",
                "numero_documento",
                "nombres",
                "apellidos",
                "licencia"
              ],
              "additionalProperties": false
            }
          },
          "vehiculos": {
            "description": "Obligatorio en transporte privado (02).",
            "minItems": 1,
            "maxItems": 10,
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "placa": {
                  "type": "string",
                  "pattern": "^[A-Z0-9]{5,8}$"
                }
              },
              "required": [
                "placa"
              ],
              "additionalProperties": false
            }
          },
          "partida": {
            "type": "object",
            "properties": {
              "ubigeo": {
                "$ref": "#/components/schemas/Ubigeo"
              },
              "direccion": {
                "type": "string",
                "minLength": 1,
                "maxLength": 200
              },
              "codigo_establecimiento": {
                "type": "string",
                "pattern": "^\\d{4}$"
              }
            },
            "required": [
              "ubigeo",
              "direccion"
            ],
            "additionalProperties": false
          },
          "llegada": {
            "type": "object",
            "properties": {
              "ubigeo": {
                "$ref": "#/components/schemas/Ubigeo"
              },
              "direccion": {
                "type": "string",
                "minLength": 1,
                "maxLength": 200
              },
              "codigo_establecimiento": {
                "type": "string",
                "pattern": "^\\d{4}$"
              }
            },
            "required": [
              "ubigeo",
              "direccion"
            ],
            "additionalProperties": false
          },
          "items": {
            "minItems": 1,
            "maxItems": 500,
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "descripcion": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 500
                },
                "cantidad": {
                  "$ref": "#/components/schemas/Cantidad"
                },
                "unidad": {
                  "type": "string",
                  "pattern": "^[A-Z0-9]{1,3}$"
                },
                "codigo": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 30
                }
              },
              "required": [
                "descripcion",
                "cantidad"
              ],
              "additionalProperties": false
            }
          },
          "documentos_relacionados": {
            "maxItems": 20,
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "tipo": {
                  "type": "string",
                  "enum": [
                    "01",
                    "03"
                  ]
                },
                "serie": {
                  "type": "string",
                  "pattern": "^[FB][A-Z0-9]{3}$"
                },
                "numero": {
                  "type": "integer",
                  "minimum": 1,
                  "maximum": 99999999
                }
              },
              "required": [
                "tipo",
                "serie",
                "numero"
              ],
              "additionalProperties": false
            }
          },
          "credenciales": {
            "$ref": "#/components/schemas/CredencialesGuia"
          }
        },
        "required": [
          "serie",
          "destinatario",
          "motivo_traslado",
          "peso_bruto_kg",
          "modalidad",
          "fecha_inicio_traslado",
          "partida",
          "llegada",
          "items"
        ],
        "additionalProperties": false,
        "description": "Guía de remisión remitente (09). La numeración la asigna el servidor."
      },
      "Guia": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^gre_[A-Za-z0-9]{8,64}$",
            "description": "Identificador que empieza con `gre_`.",
            "examples": [
              "gre_8f2c1a7d9e"
            ]
          },
          "emisor_ruc": {
            "$ref": "#/components/schemas/Ruc"
          },
          "serie": {
            "type": "string",
            "pattern": "^T[A-Z0-9]{3}$"
          },
          "numero": {
            "type": "integer",
            "exclusiveMinimum": 0,
            "maximum": 9007199254740991
          },
          "numero_completo": {
            "type": "string",
            "pattern": "^T[A-Z0-9]{3}-\\d{1,8}$"
          },
          "fecha_emision": {
            "$ref": "#/components/schemas/Fecha"
          },
          "estado": {
            "type": "string",
            "enum": [
              "en_cola",
              "aceptada",
              "rechazada"
            ]
          },
          "destinatario": {
            "type": "object",
            "properties": {
              "tipo_documento": {
                "type": "string"
              },
              "numero_documento": {
                "type": "string"
              },
              "nombre": {
                "type": "string"
              }
            },
            "required": [
              "tipo_documento",
              "numero_documento",
              "nombre"
            ]
          },
          "sunat": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "codigo": {
                    "type": "string",
                    "minLength": 1,
                    "description": "Código de respuesta de SUNAT; 0 es aceptado."
                  },
                  "descripcion": {
                    "type": "string"
                  },
                  "observaciones": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  }
                },
                "required": [
                  "codigo",
                  "descripcion",
                  "observaciones"
                ],
                "description": "Lo que respondió SUNAT en el CDR."
              },
              {
                "type": "null"
              }
            ]
          },
          "enlaces": {
            "type": "object",
            "properties": {
              "xml": {
                "type": "string",
                "format": "starts_with",
                "pattern": "^\\/v1\\/.*"
              },
              "cdr": {
                "anyOf": [
                  {
                    "type": "string",
                    "format": "starts_with",
                    "pattern": "^\\/v1\\/.*"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "pdf": {
                "type": "string",
                "format": "starts_with",
                "pattern": "^\\/v1\\/.*"
              }
            },
            "required": [
              "xml",
              "cdr",
              "pdf"
            ]
          },
          "creada_en": {
            "$ref": "#/components/schemas/FechaHoraLima"
          },
          "actualizada_en": {
            "$ref": "#/components/schemas/FechaHoraLima"
          }
        },
        "required": [
          "id",
          "emisor_ruc",
          "serie",
          "numero",
          "numero_completo",
          "fecha_emision",
          "estado",
          "destinatario",
          "sunat",
          "enlaces",
          "creada_en",
          "actualizada_en"
        ],
        "description": "Guía de remisión emitida."
      },
      "ListaGuias": {
        "type": "object",
        "properties": {
          "elementos": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Guia"
            }
          },
          "siguiente_cursor": {
            "description": "Pásalo como `cursor` para la página siguiente; `null` si ya no hay más.",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "elementos",
          "siguiente_cursor"
        ],
        "description": "Página de resultados, del más reciente al más antiguo."
      },
      "PedirPropuestaSire": {
        "type": "object",
        "properties": {
          "registro": {
            "type": "string",
            "enum": [
              "RVIE",
              "RCE"
            ],
            "description": "RVIE ventas e ingresos; RCE compras."
          },
          "periodo": {
            "$ref": "#/components/schemas/Periodo"
          },
          "credenciales": {
            "$ref": "#/components/schemas/CredencialesSire"
          }
        },
        "required": [
          "registro",
          "periodo"
        ],
        "additionalProperties": false,
        "description": "Pide a SUNAT la propuesta del periodo. Tarda: responde 202 y consultas el resultado."
      },
      "PropuestaSire": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^sire_[A-Za-z0-9]{8,64}$",
            "description": "Identificador que empieza con `sire_`.",
            "examples": [
              "sire_8f2c1a7d9e"
            ]
          },
          "emisor_ruc": {
            "$ref": "#/components/schemas/Ruc"
          },
          "registro": {
            "type": "string",
            "enum": [
              "RVIE",
              "RCE"
            ],
            "description": "RVIE ventas e ingresos; RCE compras."
          },
          "periodo": {
            "$ref": "#/components/schemas/Periodo"
          },
          "estado": {
            "type": "string",
            "enum": [
              "en_cola",
              "procesando",
              "lista",
              "sin_datos",
              "error"
            ]
          },
          "resumen": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "cantidad": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 9007199254740991
                  },
                  "base_imponible": {
                    "$ref": "#/components/schemas/MontoConSigno"
                  },
                  "igv": {
                    "$ref": "#/components/schemas/MontoConSigno"
                  },
                  "total": {
                    "$ref": "#/components/schemas/MontoConSigno"
                  }
                },
                "required": [
                  "cantidad",
                  "base_imponible",
                  "igv",
                  "total"
                ]
              },
              {
                "type": "null"
              }
            ]
          },
          "error": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "mensaje": {
                    "type": "string"
                  }
                },
                "required": [
                  "mensaje"
                ]
              },
              {
                "type": "null"
              }
            ]
          },
          "creada_en": {
            "$ref": "#/components/schemas/FechaHoraLima"
          },
          "actualizada_en": {
            "$ref": "#/components/schemas/FechaHoraLima"
          }
        },
        "required": [
          "id",
          "emisor_ruc",
          "registro",
          "periodo",
          "estado",
          "resumen",
          "error",
          "creada_en",
          "actualizada_en"
        ],
        "description": "Propuesta del SIRE descargada y normalizada."
      },
      "RegistroSire": {
        "type": "object",
        "properties": {
          "tipo_comprobante": {
            "type": "string",
            "pattern": "^\\d{2}$"
          },
          "serie": {
            "type": "string",
            "minLength": 1
          },
          "numero": {
            "type": "string",
            "minLength": 1
          },
          "fecha_emision": {
            "$ref": "#/components/schemas/Fecha"
          },
          "contraparte": {
            "type": "object",
            "properties": {
              "tipo_documento": {
                "type": "string"
              },
              "numero_documento": {
                "type": "string"
              },
              "nombre": {
                "type": "string"
              }
            },
            "required": [
              "tipo_documento",
              "numero_documento",
              "nombre"
            ]
          },
          "moneda": {
            "type": "string",
            "minLength": 3,
            "maxLength": 3
          },
          "tipo_cambio": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/TipoCambioValor"
              },
              {
                "type": "null"
              }
            ]
          },
          "base_imponible": {
            "$ref": "#/components/schemas/MontoConSigno"
          },
          "igv": {
            "$ref": "#/components/schemas/MontoConSigno"
          },
          "no_gravado": {
            "$ref": "#/components/schemas/MontoConSigno"
          },
          "total": {
            "$ref": "#/components/schemas/MontoConSigno"
          }
        },
        "required": [
          "tipo_comprobante",
          "serie",
          "numero",
          "fecha_emision",
          "contraparte",
          "moneda",
          "tipo_cambio",
          "base_imponible",
          "igv",
          "no_gravado",
          "total"
        ],
        "description": "Una línea de la propuesta. En notas de crédito los montos van en negativo."
      },
      "ListaRegistrosSire": {
        "type": "object",
        "properties": {
          "elementos": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/RegistroSire"
            }
          },
          "siguiente_cursor": {
            "description": "Pásalo como `cursor` para la página siguiente; `null` si ya no hay más.",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "elementos",
          "siguiente_cursor"
        ],
        "description": "Página de resultados, del más reciente al más antiguo."
      },
      "CrearConexion": {
        "type": "object",
        "properties": {
          "proveedor": {
            "type": "string",
            "enum": [
              "zernio",
              "ycloud",
              "meta"
            ],
            "description": "Por dónde sale la conexión. Puedes pasar un número de un proveedor a otro sin cambiar tu integración."
          },
          "canal": {
            "type": "string",
            "enum": [
              "whatsapp",
              "instagram",
              "messenger"
            ]
          },
          "nombre": {
            "type": "string",
            "minLength": 1,
            "maxLength": 80,
            "description": "Para reconocerla, por ejemplo «WhatsApp de ventas»."
          },
          "telefono": {
            "description": "Solo WhatsApp: el número a conectar, si ya lo sabes.",
            "$ref": "#/components/schemas/Telefono"
          }
        },
        "required": [
          "proveedor",
          "canal",
          "nombre"
        ],
        "additionalProperties": false,
        "description": "Crea una conexión. Una persona termina el alta en `alta_url` (por ejemplo, el registro de Meta); nunca nos pases tokens de terceros por la API."
      },
      "Conexion": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^con_[A-Za-z0-9]{8,64}$",
            "description": "Identificador que empieza con `con_`.",
            "examples": [
              "con_8f2c1a7d9e"
            ]
          },
          "proveedor": {
            "type": "string",
            "enum": [
              "zernio",
              "ycloud",
              "meta"
            ],
            "description": "Por dónde sale la conexión. Puedes pasar un número de un proveedor a otro sin cambiar tu integración."
          },
          "canal": {
            "type": "string",
            "enum": [
              "whatsapp",
              "instagram",
              "messenger"
            ]
          },
          "nombre": {
            "type": "string",
            "minLength": 1
          },
          "estado": {
            "type": "string",
            "enum": [
              "pendiente",
              "activa",
              "desconectada",
              "error"
            ]
          },
          "telefono": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/Telefono"
              },
              {
                "type": "null"
              }
            ]
          },
          "cuenta": {
            "description": "Usuario de Instagram o página de Facebook, si aplica.",
            "type": [
              "string",
              "null"
            ]
          },
          "alta_url": {
            "anyOf": [
              {
                "type": "string",
                "maxLength": 2048,
                "format": "uri",
                "description": "URL pública con https (sin IP literal, localhost, dominios internos ni usuario y clave)."
              },
              {
                "type": "null"
              }
            ],
            "description": "Mientras está `pendiente`: dónde termina el alta una persona."
          },
          "creada_en": {
            "$ref": "#/components/schemas/FechaHoraLima"
          },
          "ultima_prueba_en": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/FechaHoraLima"
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "id",
          "proveedor",
          "canal",
          "nombre",
          "estado",
          "telefono",
          "cuenta",
          "alta_url",
          "creada_en",
          "ultima_prueba_en"
        ],
        "description": "Conexión de un número de WhatsApp, una cuenta de Instagram o una página de Messenger."
      },
      "ListaConexiones": {
        "type": "object",
        "properties": {
          "elementos": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Conexion"
            }
          },
          "siguiente_cursor": {
            "description": "Pásalo como `cursor` para la página siguiente; `null` si ya no hay más.",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "elementos",
          "siguiente_cursor"
        ],
        "description": "Página de resultados, del más reciente al más antiguo."
      },
      "ResultadoPrueba": {
        "type": "object",
        "properties": {
          "conexion_id": {
            "type": "string",
            "pattern": "^con_[A-Za-z0-9]{8,64}$",
            "description": "Identificador que empieza con `con_`.",
            "examples": [
              "con_8f2c1a7d9e"
            ]
          },
          "ok": {
            "type": "boolean"
          },
          "estado": {
            "type": "string",
            "enum": [
              "pendiente",
              "activa",
              "desconectada",
              "error"
            ]
          },
          "detalle": {
            "type": "string",
            "minLength": 1
          },
          "probado_en": {
            "$ref": "#/components/schemas/FechaHoraLima"
          }
        },
        "required": [
          "conexion_id",
          "ok",
          "estado",
          "detalle",
          "probado_en"
        ],
        "description": "Resultado de probar la conexión con el proveedor. No envía mensajes."
      },
      "EnviarMensaje": {
        "oneOf": [
          {
            "type": "object",
            "properties": {
              "conexion_id": {
                "type": "string",
                "pattern": "^con_[A-Za-z0-9]{8,64}$",
                "description": "Identificador que empieza con `con_`.",
                "examples": [
                  "con_8f2c1a7d9e"
                ]
              },
              "conversacion_id": {
                "description": "Responder en una conversación existente (cualquier canal).",
                "type": "string",
                "pattern": "^cnv_[A-Za-z0-9]{8,64}$",
                "examples": [
                  "cnv_8f2c1a7d9e"
                ]
              },
              "telefono": {
                "description": "Solo WhatsApp: escribir a un número.",
                "$ref": "#/components/schemas/Telefono"
              },
              "tipo": {
                "type": "string",
                "const": "texto"
              },
              "texto": {
                "type": "string",
                "minLength": 1,
                "maxLength": 4096
              }
            },
            "required": [
              "conexion_id",
              "tipo",
              "texto"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "conexion_id": {
                "type": "string",
                "pattern": "^con_[A-Za-z0-9]{8,64}$",
                "description": "Identificador que empieza con `con_`.",
                "examples": [
                  "con_8f2c1a7d9e"
                ]
              },
              "conversacion_id": {
                "description": "Responder en una conversación existente (cualquier canal).",
                "type": "string",
                "pattern": "^cnv_[A-Za-z0-9]{8,64}$",
                "examples": [
                  "cnv_8f2c1a7d9e"
                ]
              },
              "telefono": {
                "description": "Solo WhatsApp: escribir a un número.",
                "$ref": "#/components/schemas/Telefono"
              },
              "tipo": {
                "type": "string",
                "const": "media"
              },
              "media": {
                "type": "object",
                "properties": {
                  "tipo": {
                    "type": "string",
                    "enum": [
                      "imagen",
                      "video",
                      "audio",
                      "documento"
                    ]
                  },
                  "url": {
                    "type": "string",
                    "maxLength": 2048,
                    "format": "uri",
                    "description": "Archivo público por https; lo descargamos y lo enviamos."
                  },
                  "nombre_archivo": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 240
                  },
                  "leyenda": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 1024
                  }
                },
                "required": [
                  "tipo",
                  "url"
                ],
                "additionalProperties": false
              }
            },
            "required": [
              "conexion_id",
              "tipo",
              "media"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "conexion_id": {
                "type": "string",
                "pattern": "^con_[A-Za-z0-9]{8,64}$",
                "description": "Identificador que empieza con `con_`.",
                "examples": [
                  "con_8f2c1a7d9e"
                ]
              },
              "conversacion_id": {
                "description": "Responder en una conversación existente (cualquier canal).",
                "type": "string",
                "pattern": "^cnv_[A-Za-z0-9]{8,64}$",
                "examples": [
                  "cnv_8f2c1a7d9e"
                ]
              },
              "telefono": {
                "description": "Solo WhatsApp: escribir a un número.",
                "$ref": "#/components/schemas/Telefono"
              },
              "tipo": {
                "type": "string",
                "const": "plantilla"
              },
              "plantilla": {
                "type": "object",
                "properties": {
                  "nombre": {
                    "type": "string",
                    "pattern": "^[a-z0-9_]{1,512}$"
                  },
                  "idioma": {
                    "type": "string",
                    "pattern": "^[a-z]{2}(_[A-Z]{2})?$",
                    "description": "Código de idioma, por ejemplo es o es_PE."
                  },
                  "parametros": {
                    "type": "object",
                    "properties": {
                      "encabezado": {
                        "anyOf": [
                          {
                            "type": "string",
                            "minLength": 1,
                            "maxLength": 60
                          },
                          {
                            "type": "object",
                            "properties": {
                              "tipo": {
                                "type": "string",
                                "enum": [
                                  "imagen",
                                  "video",
                                  "audio",
                                  "documento"
                                ]
                              },
                              "url": {
                                "type": "string",
                                "maxLength": 2048,
                                "format": "uri",
                                "description": "Archivo público por https; lo descargamos y lo enviamos."
                              },
                              "nombre_archivo": {
                                "type": "string",
                                "minLength": 1,
                                "maxLength": 240
                              },
                              "leyenda": {
                                "type": "string",
                                "minLength": 1,
                                "maxLength": 1024
                              }
                            },
                            "required": [
                              "tipo",
                              "url"
                            ],
                            "additionalProperties": false
                          }
                        ]
                      },
                      "cuerpo": {
                        "description": "Valores de {{1}}, {{2}}… en orden.",
                        "maxItems": 20,
                        "type": "array",
                        "items": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 1024
                        }
                      },
                      "botones": {
                        "maxItems": 10,
                        "type": "array",
                        "items": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 2000
                        }
                      }
                    },
                    "additionalProperties": false
                  }
                },
                "required": [
                  "nombre",
                  "idioma"
                ],
                "additionalProperties": false
              }
            },
            "required": [
              "conexion_id",
              "tipo",
              "plantilla"
            ],
            "additionalProperties": false
          }
        ],
        "description": "Envía texto, un archivo o una plantilla aprobada. Fuera de la ventana de atención solo se permite plantilla (si no, `ventana_cerrada`). Exige `Idempotency-Key`: un mensaje con resultado incierto no se reenvía solo."
      },
      "Mensaje": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^msg_[A-Za-z0-9]{8,64}$",
            "description": "Identificador que empieza con `msg_`.",
            "examples": [
              "msg_8f2c1a7d9e"
            ]
          },
          "conexion_id": {
            "type": "string",
            "pattern": "^con_[A-Za-z0-9]{8,64}$",
            "description": "Identificador que empieza con `con_`.",
            "examples": [
              "con_8f2c1a7d9e"
            ]
          },
          "conversacion_id": {
            "type": "string",
            "pattern": "^cnv_[A-Za-z0-9]{8,64}$",
            "description": "Identificador que empieza con `cnv_`.",
            "examples": [
              "cnv_8f2c1a7d9e"
            ]
          },
          "canal": {
            "type": "string",
            "enum": [
              "whatsapp",
              "instagram",
              "messenger"
            ]
          },
          "direccion": {
            "type": "string",
            "enum": [
              "saliente",
              "entrante"
            ]
          },
          "tipo": {
            "type": "string",
            "enum": [
              "texto",
              "media",
              "plantilla",
              "interactivo",
              "otro"
            ]
          },
          "texto": {
            "type": [
              "string",
              "null"
            ]
          },
          "media": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "tipo": {
                    "type": "string",
                    "enum": [
                      "imagen",
                      "video",
                      "audio",
                      "documento"
                    ]
                  },
                  "url": {
                    "type": "string",
                    "format": "uri"
                  },
                  "nombre_archivo": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "leyenda": {
                    "type": [
                      "string",
                      "null"
                    ]
                  }
                },
                "required": [
                  "tipo",
                  "url",
                  "nombre_archivo",
                  "leyenda"
                ]
              },
              {
                "type": "null"
              }
            ],
            "description": "En mensajes entrantes, la URL es nuestra y vence en unas horas."
          },
          "plantilla": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "nombre": {
                    "type": "string"
                  },
                  "idioma": {
                    "type": "string"
                  }
                },
                "required": [
                  "nombre",
                  "idioma"
                ]
              },
              {
                "type": "null"
              }
            ]
          },
          "estado": {
            "type": "string",
            "enum": [
              "en_cola",
              "enviado",
              "entregado",
              "leido",
              "fallido",
              "incierto",
              "recibido"
            ],
            "description": "`incierto`: el proveedor no confirmó; revisa antes de reenviar. `recibido`: mensaje entrante."
          },
          "error": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "codigo": {
                    "type": "string"
                  },
                  "mensaje": {
                    "type": "string"
                  }
                },
                "required": [
                  "codigo",
                  "mensaje"
                ]
              },
              {
                "type": "null"
              }
            ]
          },
          "creado_en": {
            "$ref": "#/components/schemas/FechaHoraLima"
          },
          "actualizado_en": {
            "$ref": "#/components/schemas/FechaHoraLima"
          }
        },
        "required": [
          "id",
          "conexion_id",
          "conversacion_id",
          "canal",
          "direccion",
          "tipo",
          "texto",
          "media",
          "plantilla",
          "estado",
          "error",
          "creado_en",
          "actualizado_en"
        ],
        "description": "Mensaje enviado o recibido."
      },
      "ListaMensajes": {
        "type": "object",
        "properties": {
          "elementos": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Mensaje"
            }
          },
          "siguiente_cursor": {
            "description": "Pásalo como `cursor` para la página siguiente; `null` si ya no hay más.",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "elementos",
          "siguiente_cursor"
        ],
        "description": "Página de resultados, del más reciente al más antiguo."
      },
      "Conversacion": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^cnv_[A-Za-z0-9]{8,64}$",
            "description": "Identificador que empieza con `cnv_`.",
            "examples": [
              "cnv_8f2c1a7d9e"
            ]
          },
          "conexion_id": {
            "type": "string",
            "pattern": "^con_[A-Za-z0-9]{8,64}$",
            "description": "Identificador que empieza con `con_`.",
            "examples": [
              "con_8f2c1a7d9e"
            ]
          },
          "canal": {
            "type": "string",
            "enum": [
              "whatsapp",
              "instagram",
              "messenger"
            ]
          },
          "contacto": {
            "type": "object",
            "properties": {
              "nombre": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "telefono": {
                "anyOf": [
                  {
                    "$ref": "#/components/schemas/Telefono"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "usuario": {
                "description": "Usuario de Instagram, si aplica.",
                "type": [
                  "string",
                  "null"
                ]
              }
            },
            "required": [
              "nombre",
              "telefono",
              "usuario"
            ]
          },
          "ventana": {
            "type": "object",
            "properties": {
              "abierta": {
                "type": "boolean"
              },
              "cierra_en": {
                "anyOf": [
                  {
                    "$ref": "#/components/schemas/FechaHoraLima"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "tipo": {
                "anyOf": [
                  {
                    "type": "string",
                    "enum": [
                      "24h",
                      "72h"
                    ]
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "72h cuando el contacto llegó por un anuncio."
              }
            },
            "required": [
              "abierta",
              "cierra_en",
              "tipo"
            ],
            "description": "Ventana de atención: mientras está abierta puedes escribir libre; si no, solo plantillas."
          },
          "no_leidos": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991
          },
          "ultimo_mensaje_en": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/FechaHoraLima"
              },
              {
                "type": "null"
              }
            ]
          },
          "creada_en": {
            "$ref": "#/components/schemas/FechaHoraLima"
          }
        },
        "required": [
          "id",
          "conexion_id",
          "canal",
          "contacto",
          "ventana",
          "no_leidos",
          "ultimo_mensaje_en",
          "creada_en"
        ],
        "description": "Conversación con un contacto en un canal."
      },
      "ListaConversaciones": {
        "type": "object",
        "properties": {
          "elementos": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Conversacion"
            }
          },
          "siguiente_cursor": {
            "description": "Pásalo como `cursor` para la página siguiente; `null` si ya no hay más.",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "elementos",
          "siguiente_cursor"
        ],
        "description": "Página de resultados, del más reciente al más antiguo."
      },
      "CrearPlantilla": {
        "type": "object",
        "properties": {
          "conexion_id": {
            "type": "string",
            "pattern": "^con_[A-Za-z0-9]{8,64}$",
            "description": "Identificador que empieza con `con_`.",
            "examples": [
              "con_8f2c1a7d9e"
            ]
          },
          "nombre": {
            "type": "string",
            "pattern": "^[a-z0-9_]{1,512}$"
          },
          "idioma": {
            "type": "string",
            "pattern": "^[a-z]{2}(_[A-Z]{2})?$",
            "description": "Código de idioma, por ejemplo es o es_PE."
          },
          "categoria": {
            "type": "string",
            "enum": [
              "utilidad",
              "marketing",
              "autenticacion"
            ],
            "description": "Nunca uses plantillas para cobro de deudas: Meta no lo permite."
          },
          "cuerpo": {
            "type": "string",
            "minLength": 1,
            "maxLength": 1024,
            "description": "Texto con variables {{1}}, {{2}}…"
          },
          "encabezado": {
            "type": "string",
            "minLength": 1,
            "maxLength": 60
          },
          "pie": {
            "type": "string",
            "minLength": 1,
            "maxLength": 60
          },
          "botones": {
            "maxItems": 10,
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "tipo": {
                  "type": "string",
                  "enum": [
                    "respuesta_rapida",
                    "url",
                    "telefono"
                  ]
                },
                "texto": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 25
                },
                "url": {
                  "type": "string",
                  "maxLength": 2048,
                  "format": "uri",
                  "description": "URL pública con https (sin IP literal, localhost, dominios internos ni usuario y clave)."
                },
                "telefono": {
                  "$ref": "#/components/schemas/Telefono"
                }
              },
              "required": [
                "tipo",
                "texto"
              ],
              "additionalProperties": false
            }
          },
          "ejemplos": {
            "description": "Valores de ejemplo para la revisión de Meta.",
            "maxItems": 20,
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 200
            }
          }
        },
        "required": [
          "conexion_id",
          "nombre",
          "idioma",
          "categoria",
          "cuerpo"
        ],
        "additionalProperties": false,
        "description": "Crea una plantilla y la manda a revisión. Queda `pendiente` hasta que la aprueben."
      },
      "Plantilla": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^plt_[A-Za-z0-9]{8,64}$",
            "description": "Identificador que empieza con `plt_`.",
            "examples": [
              "plt_8f2c1a7d9e"
            ]
          },
          "conexion_id": {
            "type": "string",
            "pattern": "^con_[A-Za-z0-9]{8,64}$",
            "description": "Identificador que empieza con `con_`.",
            "examples": [
              "con_8f2c1a7d9e"
            ]
          },
          "nombre": {
            "type": "string"
          },
          "idioma": {
            "type": "string"
          },
          "categoria": {
            "type": "string",
            "enum": [
              "utilidad",
              "marketing",
              "autenticacion"
            ]
          },
          "estado": {
            "type": "string",
            "enum": [
              "pendiente",
              "aprobada",
              "rechazada",
              "pausada",
              "deshabilitada"
            ]
          },
          "encabezado": {
            "type": [
              "string",
              "null"
            ]
          },
          "cuerpo": {
            "type": "string"
          },
          "pie": {
            "type": [
              "string",
              "null"
            ]
          },
          "botones": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "tipo": {
                  "type": "string",
                  "enum": [
                    "respuesta_rapida",
                    "url",
                    "telefono"
                  ]
                },
                "texto": {
                  "type": "string"
                }
              },
              "required": [
                "tipo",
                "texto"
              ]
            }
          },
          "variables": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991,
            "description": "Cuántas variables espera el cuerpo."
          },
          "motivo_rechazo": {
            "type": [
              "string",
              "null"
            ]
          },
          "creada_en": {
            "$ref": "#/components/schemas/FechaHoraLima"
          },
          "actualizada_en": {
            "$ref": "#/components/schemas/FechaHoraLima"
          }
        },
        "required": [
          "id",
          "conexion_id",
          "nombre",
          "idioma",
          "categoria",
          "estado",
          "encabezado",
          "cuerpo",
          "pie",
          "botones",
          "variables",
          "motivo_rechazo",
          "creada_en",
          "actualizada_en"
        ],
        "description": "Plantilla de mensaje."
      },
      "ListaPlantillas": {
        "type": "object",
        "properties": {
          "elementos": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Plantilla"
            }
          },
          "siguiente_cursor": {
            "description": "Pásalo como `cursor` para la página siguiente; `null` si ya no hay más.",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "elementos",
          "siguiente_cursor"
        ],
        "description": "Página de resultados, del más reciente al más antiguo."
      },
      "EnviarComprobante": {
        "type": "object",
        "properties": {
          "conexion_id": {
            "type": "string",
            "pattern": "^con_[A-Za-z0-9]{8,64}$",
            "description": "Identificador que empieza con `con_`.",
            "examples": [
              "con_8f2c1a7d9e"
            ]
          },
          "conversacion_id": {
            "description": "Responder en una conversación existente (cualquier canal).",
            "type": "string",
            "pattern": "^cnv_[A-Za-z0-9]{8,64}$",
            "examples": [
              "cnv_8f2c1a7d9e"
            ]
          },
          "telefono": {
            "description": "Solo WhatsApp: escribir a un número.",
            "$ref": "#/components/schemas/Telefono"
          },
          "comprobante": {
            "type": "object",
            "properties": {
              "ruc": {
                "$ref": "#/components/schemas/Ruc"
              },
              "id": {
                "type": "string",
                "pattern": "^cmp_[A-Za-z0-9]{8,64}$",
                "description": "Identificador que empieza con `cmp_`.",
                "examples": [
                  "cmp_8f2c1a7d9e"
                ]
              }
            },
            "required": [
              "ruc",
              "id"
            ],
            "additionalProperties": false,
            "description": "Comprobante de un emisor de tu cuenta."
          },
          "mensaje": {
            "description": "Texto que acompaña al PDF dentro de la ventana de atención.",
            "type": "string",
            "minLength": 1,
            "maxLength": 1024
          },
          "plantilla": {
            "description": "Plantilla de utilidad aprobada, con un documento en el encabezado y hasta dos variables, para enviar fuera de la ventana. Si no la indicas, elegimos una de la conexión.",
            "type": "object",
            "properties": {
              "nombre": {
                "type": "string",
                "pattern": "^[a-z0-9_]{1,512}$"
              },
              "idioma": {
                "type": "string",
                "pattern": "^[a-z]{2}(_[A-Z]{2})?$",
                "description": "Código de idioma, por ejemplo es o es_PE."
              }
            },
            "required": [
              "nombre",
              "idioma"
            ],
            "additionalProperties": false
          },
          "formato_pdf": {
            "type": "string",
            "enum": [
              "a4",
              "ticket80"
            ]
          }
        },
        "required": [
          "conexion_id",
          "comprobante"
        ],
        "additionalProperties": false,
        "description": "Envía el PDF de un comprobante por WhatsApp, Instagram o Messenger."
      },
      "CrearWebhook": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string",
            "maxLength": 2048,
            "format": "uri",
            "description": "Tu endpoint. Debe responder 2xx en menos de 10 segundos."
          },
          "eventos": {
            "minItems": 1,
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "mensaje.recibido",
                "mensaje.estado",
                "conexion.estado",
                "plantilla.estado"
              ]
            }
          },
          "descripcion": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200
          }
        },
        "required": [
          "url",
          "eventos"
        ],
        "additionalProperties": false,
        "description": "Registra tu endpoint para recibir eventos normalizados y firmados."
      },
      "Webhook": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^whk_[A-Za-z0-9]{8,64}$",
            "description": "Identificador que empieza con `whk_`.",
            "examples": [
              "whk_8f2c1a7d9e"
            ]
          },
          "url": {
            "type": "string",
            "maxLength": 2048,
            "format": "uri",
            "description": "URL pública con https (sin IP literal, localhost, dominios internos ni usuario y clave)."
          },
          "eventos": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "mensaje.recibido",
                "mensaje.estado",
                "conexion.estado",
                "plantilla.estado"
              ]
            }
          },
          "descripcion": {
            "type": [
              "string",
              "null"
            ]
          },
          "estado": {
            "type": "string",
            "enum": [
              "activo",
              "pausado"
            ],
            "description": "Se pausa solo si tu endpoint falla muchas veces seguidas."
          },
          "creado_en": {
            "$ref": "#/components/schemas/FechaHoraLima"
          },
          "secreto_rotado_en": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/FechaHoraLima"
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "id",
          "url",
          "eventos",
          "descripcion",
          "estado",
          "creado_en",
          "secreto_rotado_en"
        ],
        "description": "Webhook de tu sistema."
      },
      "WebhookCreado": {
        "type": "object",
        "properties": {
          "webhook": {
            "$ref": "#/components/schemas/Webhook"
          },
          "secreto": {
            "type": "string",
            "pattern": "^whsec_[A-Za-z0-9]{32,64}$",
            "description": "Secreto para verificar `X-Nexum-Signature`. Se muestra solo esta vez."
          }
        },
        "required": [
          "webhook",
          "secreto"
        ],
        "description": "Webhook recién creado con su secreto."
      },
      "ListaWebhooks": {
        "type": "object",
        "properties": {
          "elementos": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Webhook"
            }
          },
          "siguiente_cursor": {
            "description": "Pásalo como `cursor` para la página siguiente; `null` si ya no hay más.",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "elementos",
          "siguiente_cursor"
        ],
        "description": "Página de resultados, del más reciente al más antiguo."
      },
      "SecretoRotado": {
        "type": "object",
        "properties": {
          "webhook": {
            "$ref": "#/components/schemas/Webhook"
          },
          "secreto": {
            "type": "string",
            "pattern": "^whsec_[A-Za-z0-9]{32,64}$",
            "description": "Secreto para verificar `X-Nexum-Signature`. Se muestra solo esta vez."
          },
          "secreto_anterior_vence_en": {
            "description": "Hasta entonces firmamos con los dos secretos.",
            "$ref": "#/components/schemas/FechaHoraLima"
          }
        },
        "required": [
          "webhook",
          "secreto",
          "secreto_anterior_vence_en"
        ],
        "description": "Secreto nuevo. Durante el cambio, cada entrega lleva una firma `v1` por cada secreto."
      },
      "Entrega": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^ent_[A-Za-z0-9]{8,64}$",
            "description": "Identificador que empieza con `ent_`.",
            "examples": [
              "ent_8f2c1a7d9e"
            ]
          },
          "webhook_id": {
            "type": "string",
            "pattern": "^whk_[A-Za-z0-9]{8,64}$",
            "description": "Identificador que empieza con `whk_`.",
            "examples": [
              "whk_8f2c1a7d9e"
            ]
          },
          "evento_id": {
            "type": "string",
            "pattern": "^evt_[A-Za-z0-9]{8,64}$",
            "description": "Identificador que empieza con `evt_`.",
            "examples": [
              "evt_8f2c1a7d9e"
            ]
          },
          "tipo_evento": {
            "type": "string",
            "enum": [
              "mensaje.recibido",
              "mensaje.estado",
              "conexion.estado",
              "plantilla.estado",
              "webhook.prueba"
            ]
          },
          "estado": {
            "type": "string",
            "enum": [
              "pendiente",
              "entregada",
              "fallida",
              "pausada"
            ]
          },
          "intentos": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991
          },
          "ultimo_codigo_http": {
            "anyOf": [
              {
                "type": "integer",
                "minimum": 100,
                "maximum": 599
              },
              {
                "type": "null"
              }
            ]
          },
          "ultimo_error": {
            "type": [
              "string",
              "null"
            ]
          },
          "proximo_intento_en": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/FechaHoraLima"
              },
              {
                "type": "null"
              }
            ],
            "description": "Reintentamos hasta 8 veces con espera creciente."
          },
          "creada_en": {
            "$ref": "#/components/schemas/FechaHoraLima"
          },
          "entregada_en": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/FechaHoraLima"
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "id",
          "webhook_id",
          "evento_id",
          "tipo_evento",
          "estado",
          "intentos",
          "ultimo_codigo_http",
          "ultimo_error",
          "proximo_intento_en",
          "creada_en",
          "entregada_en"
        ],
        "description": "Intento de entrega de un evento a tu webhook."
      },
      "ListaEntregas": {
        "type": "object",
        "properties": {
          "elementos": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Entrega"
            }
          },
          "siguiente_cursor": {
            "description": "Pásalo como `cursor` para la página siguiente; `null` si ya no hay más.",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "elementos",
          "siguiente_cursor"
        ],
        "description": "Página de resultados, del más reciente al más antiguo."
      },
      "EventoMensajeRecibido": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^evt_[A-Za-z0-9]{8,64}$",
            "description": "Único por evento: úsalo para no procesar dos veces el mismo.",
            "examples": [
              "evt_8f2c1a7d9e"
            ]
          },
          "creado_en": {
            "$ref": "#/components/schemas/FechaHoraLima"
          },
          "version": {
            "type": "string",
            "const": "v1"
          },
          "conexion_id": {
            "anyOf": [
              {
                "type": "string",
                "pattern": "^con_[A-Za-z0-9]{8,64}$",
                "description": "Identificador que empieza con `con_`.",
                "examples": [
                  "con_8f2c1a7d9e"
                ]
              },
              {
                "type": "null"
              }
            ]
          },
          "tipo": {
            "type": "string",
            "const": "mensaje.recibido"
          },
          "datos": {
            "type": "object",
            "properties": {
              "mensaje": {
                "$ref": "#/components/schemas/Mensaje"
              },
              "conversacion": {
                "$ref": "#/components/schemas/Conversacion"
              }
            },
            "required": [
              "mensaje",
              "conversacion"
            ]
          }
        },
        "required": [
          "id",
          "creado_en",
          "version",
          "conexion_id",
          "tipo",
          "datos"
        ],
        "description": "Llegó un mensaje de un contacto."
      },
      "EventoMensajeEstado": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^evt_[A-Za-z0-9]{8,64}$",
            "description": "Único por evento: úsalo para no procesar dos veces el mismo.",
            "examples": [
              "evt_8f2c1a7d9e"
            ]
          },
          "creado_en": {
            "$ref": "#/components/schemas/FechaHoraLima"
          },
          "version": {
            "type": "string",
            "const": "v1"
          },
          "conexion_id": {
            "anyOf": [
              {
                "type": "string",
                "pattern": "^con_[A-Za-z0-9]{8,64}$",
                "description": "Identificador que empieza con `con_`.",
                "examples": [
                  "con_8f2c1a7d9e"
                ]
              },
              {
                "type": "null"
              }
            ]
          },
          "tipo": {
            "type": "string",
            "const": "mensaje.estado"
          },
          "datos": {
            "type": "object",
            "properties": {
              "mensaje_id": {
                "type": "string",
                "pattern": "^msg_[A-Za-z0-9]{8,64}$",
                "description": "Identificador que empieza con `msg_`.",
                "examples": [
                  "msg_8f2c1a7d9e"
                ]
              },
              "conversacion_id": {
                "type": "string",
                "pattern": "^cnv_[A-Za-z0-9]{8,64}$",
                "description": "Identificador que empieza con `cnv_`.",
                "examples": [
                  "cnv_8f2c1a7d9e"
                ]
              },
              "estado": {
                "type": "string",
                "enum": [
                  "en_cola",
                  "enviado",
                  "entregado",
                  "leido",
                  "fallido",
                  "incierto",
                  "recibido"
                ],
                "description": "`incierto`: el proveedor no confirmó; revisa antes de reenviar. `recibido`: mensaje entrante."
              },
              "error": {
                "anyOf": [
                  {
                    "type": "object",
                    "properties": {
                      "codigo": {
                        "type": "string"
                      },
                      "mensaje": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "codigo",
                      "mensaje"
                    ]
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "actualizado_en": {
                "$ref": "#/components/schemas/FechaHoraLima"
              }
            },
            "required": [
              "mensaje_id",
              "conversacion_id",
              "estado",
              "error",
              "actualizado_en"
            ]
          }
        },
        "required": [
          "id",
          "creado_en",
          "version",
          "conexion_id",
          "tipo",
          "datos"
        ],
        "description": "Cambió el estado de un mensaje enviado (entregado, leído, fallido)."
      },
      "EventoConexionEstado": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^evt_[A-Za-z0-9]{8,64}$",
            "description": "Único por evento: úsalo para no procesar dos veces el mismo.",
            "examples": [
              "evt_8f2c1a7d9e"
            ]
          },
          "creado_en": {
            "$ref": "#/components/schemas/FechaHoraLima"
          },
          "version": {
            "type": "string",
            "const": "v1"
          },
          "conexion_id": {
            "anyOf": [
              {
                "type": "string",
                "pattern": "^con_[A-Za-z0-9]{8,64}$",
                "description": "Identificador que empieza con `con_`.",
                "examples": [
                  "con_8f2c1a7d9e"
                ]
              },
              {
                "type": "null"
              }
            ]
          },
          "tipo": {
            "type": "string",
            "const": "conexion.estado"
          },
          "datos": {
            "type": "object",
            "properties": {
              "conexion": {
                "$ref": "#/components/schemas/Conexion"
              }
            },
            "required": [
              "conexion"
            ]
          }
        },
        "required": [
          "id",
          "creado_en",
          "version",
          "conexion_id",
          "tipo",
          "datos"
        ],
        "description": "Una conexión cambió de estado (por ejemplo, se desconectó)."
      },
      "EventoPlantillaEstado": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^evt_[A-Za-z0-9]{8,64}$",
            "description": "Único por evento: úsalo para no procesar dos veces el mismo.",
            "examples": [
              "evt_8f2c1a7d9e"
            ]
          },
          "creado_en": {
            "$ref": "#/components/schemas/FechaHoraLima"
          },
          "version": {
            "type": "string",
            "const": "v1"
          },
          "conexion_id": {
            "anyOf": [
              {
                "type": "string",
                "pattern": "^con_[A-Za-z0-9]{8,64}$",
                "description": "Identificador que empieza con `con_`.",
                "examples": [
                  "con_8f2c1a7d9e"
                ]
              },
              {
                "type": "null"
              }
            ]
          },
          "tipo": {
            "type": "string",
            "const": "plantilla.estado"
          },
          "datos": {
            "type": "object",
            "properties": {
              "plantilla": {
                "$ref": "#/components/schemas/Plantilla"
              }
            },
            "required": [
              "plantilla"
            ]
          }
        },
        "required": [
          "id",
          "creado_en",
          "version",
          "conexion_id",
          "tipo",
          "datos"
        ],
        "description": "Una plantilla fue aprobada, rechazada o pausada."
      },
      "EventoPrueba": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^evt_[A-Za-z0-9]{8,64}$",
            "description": "Único por evento: úsalo para no procesar dos veces el mismo.",
            "examples": [
              "evt_8f2c1a7d9e"
            ]
          },
          "creado_en": {
            "$ref": "#/components/schemas/FechaHoraLima"
          },
          "version": {
            "type": "string",
            "const": "v1"
          },
          "conexion_id": {
            "anyOf": [
              {
                "type": "string",
                "pattern": "^con_[A-Za-z0-9]{8,64}$",
                "description": "Identificador que empieza con `con_`.",
                "examples": [
                  "con_8f2c1a7d9e"
                ]
              },
              {
                "type": "null"
              }
            ]
          },
          "tipo": {
            "type": "string",
            "const": "webhook.prueba"
          },
          "datos": {
            "type": "object",
            "properties": {
              "webhook_id": {
                "type": "string",
                "pattern": "^whk_[A-Za-z0-9]{8,64}$",
                "description": "Identificador que empieza con `whk_`.",
                "examples": [
                  "whk_8f2c1a7d9e"
                ]
              },
              "mensaje": {
                "type": "string"
              }
            },
            "required": [
              "webhook_id",
              "mensaje"
            ]
          }
        },
        "required": [
          "id",
          "creado_en",
          "version",
          "conexion_id",
          "tipo",
          "datos"
        ],
        "description": "Evento de prueba enviado con `POST /v1/conecta/webhooks/{id}/probar`."
      },
      "EventoConecta": {
        "oneOf": [
          {
            "$ref": "#/components/schemas/EventoMensajeRecibido"
          },
          {
            "$ref": "#/components/schemas/EventoMensajeEstado"
          },
          {
            "$ref": "#/components/schemas/EventoConexionEstado"
          },
          {
            "$ref": "#/components/schemas/EventoPlantillaEstado"
          },
          {
            "$ref": "#/components/schemas/EventoPrueba"
          }
        ],
        "description": "Evento normalizado que enviamos a tu webhook, igual para WhatsApp, Instagram y Messenger y para cualquier proveedor. Viene firmado en `X-Nexum-Signature`."
      }
    },
    "securitySchemes": {
      "claveApi": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "onx_live_… / onx_test_…",
        "description": "Clave de API en `Authorization: Bearer …`. Se crea en el panel y se muestra una sola vez."
      }
    },
    "parameters": {
      "IdempotencyKey": {
        "name": "Idempotency-Key",
        "in": "header",
        "required": true,
        "description": "Identifica una operación para que repetirla no la duplique. Si repites la petición con la misma clave y el mismo cuerpo, recibes la misma respuesta; con otro cuerpo, `idempotencia_en_conflicto`. Se guarda 24 horas.",
        "schema": {
          "type": "string",
          "pattern": "^[A-Za-z0-9._:-]{8,255}$",
          "examples": [
            "3f1c2a9e-8b7d-4c6e-9f0a-1b2c3d4e5f60"
          ]
        }
      },
      "IdempotencyKeyOpcional": {
        "name": "Idempotency-Key",
        "in": "header",
        "required": false,
        "description": "Identifica una operación para que repetirla no la duplique. Si repites la petición con la misma clave y el mismo cuerpo, recibes la misma respuesta; con otro cuerpo, `idempotencia_en_conflicto`. Se guarda 24 horas.",
        "schema": {
          "type": "string",
          "pattern": "^[A-Za-z0-9._:-]{8,255}$",
          "examples": [
            "3f1c2a9e-8b7d-4c6e-9f0a-1b2c3d4e5f60"
          ]
        }
      },
      "RequestId": {
        "name": "X-Request-Id",
        "in": "header",
        "required": false,
        "description": "Identificador de la petición. Va en cada respuesta; menciónalo al escribir a soporte.",
        "schema": {
          "type": "string",
          "pattern": "^[A-Za-z0-9._:-]{8,128}$",
          "examples": [
            "req_8f2c1a7d"
          ]
        }
      }
    },
    "headers": {
      "XRequestId": {
        "description": "Identificador de la petición; menciónalo a soporte.",
        "schema": {
          "type": "string"
        }
      },
      "RetryAfter": {
        "description": "Segundos que debes esperar antes de reintentar.",
        "schema": {
          "type": "integer",
          "minimum": 1
        }
      }
    },
    "examples": {
      "validacion": {
        "summary": "validacion",
        "description": "Algún dato no cumple el formato. En `detalle` va cada campo con su problema.",
        "value": {
          "error": {
            "codigo": "validacion",
            "mensaje": "Algún dato no cumple el formato. En `detalle` va cada campo con su problema.",
            "request_id": "req_8f2c1a7d",
            "docs": "https://docs.opennexum.com/errores#validacion"
          }
        }
      },
      "clave_invalida": {
        "summary": "clave_invalida",
        "description": "Falta la clave de API, está mal escrita, venció o fue revocada. Envíala como `Authorization: Bearer onx_live_…`.",
        "value": {
          "error": {
            "codigo": "clave_invalida",
            "mensaje": "Falta la clave de API, está mal escrita, venció o fue revocada. Envíala como `Authorization: Bearer onx_live_…`.",
            "request_id": "req_8f2c1a7d",
            "docs": "https://docs.opennexum.com/errores#clave_invalida"
          }
        }
      },
      "saldo_insuficiente": {
        "summary": "saldo_insuficiente",
        "description": "No te alcanza el saldo para esta operación. Pásale `recarga_url` a una persona de tu cuenta para que recargue.",
        "value": {
          "error": {
            "codigo": "saldo_insuficiente",
            "mensaje": "No te alcanza el saldo para esta operación. Pásale `recarga_url` a una persona de tu cuenta para que recargue.",
            "request_id": "req_8f2c1a7d",
            "docs": "https://docs.opennexum.com/errores#saldo_insuficiente",
            "recarga_url": "https://app.opennexum.com/recargar"
          }
        }
      },
      "tope_alcanzado": {
        "summary": "tope_alcanzado",
        "description": "La clave llegó a su tope de gasto del periodo. Una persona de tu cuenta puede subirlo desde el panel.",
        "value": {
          "error": {
            "codigo": "tope_alcanzado",
            "mensaje": "La clave llegó a su tope de gasto del periodo. Una persona de tu cuenta puede subirlo desde el panel.",
            "request_id": "req_8f2c1a7d",
            "docs": "https://docs.opennexum.com/errores#tope_alcanzado",
            "recarga_url": "https://app.opennexum.com/recargar"
          }
        }
      },
      "permiso_faltante": {
        "summary": "permiso_faltante",
        "description": "La clave no tiene el permiso que pide esta ruta o no tiene acceso a ese RUC.",
        "value": {
          "error": {
            "codigo": "permiso_faltante",
            "mensaje": "La clave no tiene el permiso que pide esta ruta o no tiene acceso a ese RUC.",
            "request_id": "req_8f2c1a7d",
            "docs": "https://docs.opennexum.com/errores#permiso_faltante"
          }
        }
      },
      "emisor_obligado_ose": {
        "summary": "emisor_obligado_ose",
        "description": "Ese RUC figura en el padrón de obligados a emitir mediante un OSE; por ahora no podemos emitir por él.",
        "value": {
          "error": {
            "codigo": "emisor_obligado_ose",
            "mensaje": "Ese RUC figura en el padrón de obligados a emitir mediante un OSE; por ahora no podemos emitir por él.",
            "request_id": "req_8f2c1a7d",
            "docs": "https://docs.opennexum.com/errores#emisor_obligado_ose"
          }
        }
      },
      "no_encontrado": {
        "summary": "no_encontrado",
        "description": "No existe o no pertenece a tu cuenta.",
        "value": {
          "error": {
            "codigo": "no_encontrado",
            "mensaje": "No existe o no pertenece a tu cuenta.",
            "request_id": "req_8f2c1a7d",
            "docs": "https://docs.opennexum.com/errores#no_encontrado"
          }
        }
      },
      "idempotencia_en_conflicto": {
        "summary": "idempotencia_en_conflicto",
        "description": "Usaste la misma `Idempotency-Key` con otro cuerpo. Genera una clave nueva para cada operación distinta.",
        "value": {
          "error": {
            "codigo": "idempotencia_en_conflicto",
            "mensaje": "Usaste la misma `Idempotency-Key` con otro cuerpo. Genera una clave nueva para cada operación distinta.",
            "request_id": "req_8f2c1a7d",
            "docs": "https://docs.opennexum.com/errores#idempotencia_en_conflicto"
          }
        }
      },
      "solicitud_en_curso": {
        "summary": "solicitud_en_curso",
        "description": "Ya estamos procesando una petición con esa `Idempotency-Key`. Espera unos segundos y vuelve a consultar.",
        "value": {
          "error": {
            "codigo": "solicitud_en_curso",
            "mensaje": "Ya estamos procesando una petición con esa `Idempotency-Key`. Espera unos segundos y vuelve a consultar.",
            "request_id": "req_8f2c1a7d",
            "docs": "https://docs.opennexum.com/errores#solicitud_en_curso"
          }
        }
      },
      "ya_registrado": {
        "summary": "ya_registrado",
        "description": "Eso ya está registrado: por ejemplo, el RUC ya está en otra cuenta o la serie ya existe.",
        "value": {
          "error": {
            "codigo": "ya_registrado",
            "mensaje": "Eso ya está registrado: por ejemplo, el RUC ya está en otra cuenta o la serie ya existe.",
            "request_id": "req_8f2c1a7d",
            "docs": "https://docs.opennexum.com/errores#ya_registrado"
          }
        }
      },
      "ventana_cerrada": {
        "summary": "ventana_cerrada",
        "description": "La conversación está fuera de la ventana de atención: solo puedes escribir con una plantilla aprobada. `detalle.plantillas_sugeridas` trae opciones.",
        "value": {
          "error": {
            "codigo": "ventana_cerrada",
            "mensaje": "La conversación está fuera de la ventana de atención: solo puedes escribir con una plantilla aprobada. `detalle.plantillas_sugeridas` trae opciones.",
            "request_id": "req_8f2c1a7d",
            "docs": "https://docs.opennexum.com/errores#ventana_cerrada"
          }
        }
      },
      "boveda_inactiva": {
        "summary": "boveda_inactiva",
        "description": "La bóveda de credenciales todavía no está activa. Envía `credenciales` en cada llamada.",
        "value": {
          "error": {
            "codigo": "boveda_inactiva",
            "mensaje": "La bóveda de credenciales todavía no está activa. Envía `credenciales` en cada llamada.",
            "request_id": "req_8f2c1a7d",
            "docs": "https://docs.opennexum.com/errores#boveda_inactiva"
          }
        }
      },
      "estado_no_permite": {
        "summary": "estado_no_permite",
        "description": "El recurso está en un estado que no permite esta operación, por ejemplo anular un comprobante rechazado.",
        "value": {
          "error": {
            "codigo": "estado_no_permite",
            "mensaje": "El recurso está en un estado que no permite esta operación, por ejemplo anular un comprobante rechazado.",
            "request_id": "req_8f2c1a7d",
            "docs": "https://docs.opennexum.com/errores#estado_no_permite"
          }
        }
      },
      "plazo_vencido": {
        "summary": "plazo_vencido",
        "description": "Pasó el plazo que da SUNAT para esta operación. Para anular una factura fuera de plazo, emite una nota de crédito.",
        "value": {
          "error": {
            "codigo": "plazo_vencido",
            "mensaje": "Pasó el plazo que da SUNAT para esta operación. Para anular una factura fuera de plazo, emite una nota de crédito.",
            "request_id": "req_8f2c1a7d",
            "docs": "https://docs.opennexum.com/errores#plazo_vencido"
          }
        }
      },
      "sunat_rechazo": {
        "summary": "sunat_rechazo",
        "description": "SUNAT rechazó el comprobante. En `detalle` van el código y la descripción que dio SUNAT.",
        "value": {
          "error": {
            "codigo": "sunat_rechazo",
            "mensaje": "SUNAT rechazó el comprobante. En `detalle` van el código y la descripción que dio SUNAT.",
            "request_id": "req_8f2c1a7d",
            "docs": "https://docs.opennexum.com/errores#sunat_rechazo"
          }
        }
      },
      "credenciales_sunat": {
        "summary": "credenciales_sunat",
        "description": "SUNAT no aceptó el certificado o el usuario SOL, o el certificado es de otro RUC.",
        "value": {
          "error": {
            "codigo": "credenciales_sunat",
            "mensaje": "SUNAT no aceptó el certificado o el usuario SOL, o el certificado es de otro RUC.",
            "request_id": "req_8f2c1a7d",
            "docs": "https://docs.opennexum.com/errores#credenciales_sunat"
          }
        }
      },
      "limite_uso": {
        "summary": "limite_uso",
        "description": "Hiciste demasiadas peticiones seguidas. Espera los segundos que indica `Retry-After` y vuelve a intentar.",
        "value": {
          "error": {
            "codigo": "limite_uso",
            "mensaje": "Hiciste demasiadas peticiones seguidas. Espera los segundos que indica `Retry-After` y vuelve a intentar.",
            "request_id": "req_8f2c1a7d",
            "docs": "https://docs.opennexum.com/errores#limite_uso"
          }
        }
      },
      "error_interno": {
        "summary": "error_interno",
        "description": "Algo falló de nuestro lado. Repite la petición con la misma `Idempotency-Key`: no se duplica nada.",
        "value": {
          "error": {
            "codigo": "error_interno",
            "mensaje": "Algo falló de nuestro lado. Repite la petición con la misma `Idempotency-Key`: no se duplica nada.",
            "request_id": "req_8f2c1a7d",
            "docs": "https://docs.opennexum.com/errores#error_interno"
          }
        }
      },
      "servicio_externo_no_disponible": {
        "summary": "servicio_externo_no_disponible",
        "description": "SUNAT, el BCRP o el proveedor de mensajería no respondió. Revisa el estado antes de reenviar.",
        "value": {
          "error": {
            "codigo": "servicio_externo_no_disponible",
            "mensaje": "SUNAT, el BCRP o el proveedor de mensajería no respondió. Revisa el estado antes de reenviar.",
            "request_id": "req_8f2c1a7d",
            "docs": "https://docs.opennexum.com/errores#servicio_externo_no_disponible"
          }
        }
      },
      "no_disponible": {
        "summary": "no_disponible",
        "description": "El dato todavía se está cargando o actualizando de nuestro lado. Vuelve a intentar después de los segundos que indica `Retry-After`.",
        "value": {
          "error": {
            "codigo": "no_disponible",
            "mensaje": "El dato todavía se está cargando o actualizando de nuestro lado. Vuelve a intentar después de los segundos que indica `Retry-After`.",
            "request_id": "req_8f2c1a7d",
            "docs": "https://docs.opennexum.com/errores#no_disponible"
          }
        }
      },
      "operacion_no_disponible": {
        "summary": "operacion_no_disponible",
        "description": "Esta operación existe en el contrato, pero todavía no está habilitada. Revisa en la documentación qué rutas ya puedes usar; no se cobró nada.",
        "value": {
          "error": {
            "codigo": "operacion_no_disponible",
            "mensaje": "Esta operación existe en el contrato, pero todavía no está habilitada. Revisa en la documentación qué rutas ya puedes usar; no se cobró nada.",
            "request_id": "req_8f2c1a7d",
            "docs": "https://docs.opennexum.com/errores#operacion_no_disponible"
          }
        }
      }
    }
  }
}
