{
  "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}`; cuando diga `aprobada`, repite la misma petición con la misma `Idempotency-Key` y el mismo cuerpo antes de `expira_en` (con otro cuerpo no vale). Nada se cobra ni se envía mientras espera. 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ó, y consultarla no la cambia. Cuando está `aprobada`, repite la misma petición (misma `Idempotency-Key` y mismo cuerpo) antes de `expira_en` para hacerla; entonces queda `usada`.\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": "Antes de esta hora hay que aprobarla Y repetir la petición; si no, 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ó ni se envió todavía. El «sí» se da en el panel, nunca como argumento de la API. Aprobada, repite la misma petición con la misma Idempotency-Key y el mismo cuerpo antes de `expira_en`."
      },
      "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",
              "usada"
            ],
            "description": "`aprobada`: repite la misma petición (misma Idempotency-Key y mismo cuerpo) antes de `expira_en`. `usada`: ya corrió con esa aprobación. `rechazada` y `vencida` no se hacen."
          },
          "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."
          },
          "motivo_rechazo": {
            "description": "Lo que escribió la persona al rechazarla, si escribió algo.",
            "type": [
              "string",
              "null"
            ]
          },
          "siguiente_paso": {
            "type": "string",
            "minLength": 1,
            "description": "Qué hacer ahora, en palabras para el agente."
          },
          "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"
              }
            ]
          },
          "usada_en": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/FechaHoraLima"
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "id",
          "estado",
          "operacion",
          "resumen",
          "motivo_rechazo",
          "siguiente_paso",
          "confirmacion_url",
          "creada_en",
          "expira_en",
          "decidida_en",
          "usada_en"
        ],
        "description": "Estado de una operación que pidió aprobación humana. Solo la ve la clave que la pidió; consultarla no la cambia. El «sí» lo da una persona en el panel, nunca la API."
      },
      "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 (07)."
              },
              "bajas": {
                "type": "boolean",
                "description": "Bajas: comunicación de baja (RA) y resumen diario de anulación (RC)."
              },
              "mensajes": {
                "type": "boolean",
                "description": "Envío de mensajes y comprobantes por Conecta."
              },
              "agentes": {
                "type": "boolean",
                "description": "Toda emisión o baja que pida un agente con un token OAuth o por MCP, sea cual sea su tipo o monto."
              },
              "monto_mayor_a": {
                "anyOf": [
                  {
                    "$ref": "#/components/schemas/Monto"
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "Comprobantes cuyo total pasa de este monto (por omisión, \"5000.00\"); `null` para no pedirla por monto."
              }
            },
            "required": [
              "notas",
              "bajas",
              "mensajes",
              "agentes",
              "monto_mayor_a"
            ],
            "additionalProperties": false,
            "description": "Qué operaciones de esta clave esperan la aprobación de una persona en el panel. Por omisión: notas de crédito, bajas, montos mayores a S/ 5,000.00 y todo lo que pida un agente (token OAuth o MCP)."
          },
          "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 (07)."
              },
              "bajas": {
                "type": "boolean",
                "description": "Bajas: comunicación de baja (RA) y resumen diario de anulación (RC)."
              },
              "mensajes": {
                "type": "boolean",
                "description": "Envío de mensajes y comprobantes por Conecta."
              },
              "agentes": {
                "type": "boolean",
                "description": "Toda emisión o baja que pida un agente con un token OAuth o por MCP, sea cual sea su tipo o monto."
              },
              "monto_mayor_a": {
                "anyOf": [
                  {
                    "$ref": "#/components/schemas/Monto"
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "Comprobantes cuyo total pasa de este monto (por omisión, \"5000.00\"); `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"
          }
        }
      }
    }
  }
}
