# OpenNexum: documentación completa > La API peruana para agentes de IA y programadores: una sola clave para comprobantes SUNAT (Nexum Comprobantes) y mensajería de Meta (Nexum Conecta), con saldo prepagado en soles. Solo fuentes oficiales y legales. --- Fuente: https://docs.opennexum.com/ # Documentación de OpenNexum > Una sola clave para comprobantes SUNAT y mensajería, con saldo en soles. Solo fuentes oficiales y legales. OpenNexum™ tiene dos productos, con la misma clave y el mismo saldo prepagado: - **Nexum Comprobantes**: emite facturas, boletas y notas electrónicas a SUNAT, y consulta RUC y tipo de cambio. Mira la [guía de Nexum Comprobantes](https://docs.opennexum.com/comprobantes/). - **Nexum Conecta**: WhatsApp, Instagram y Messenger como funciones de tu API. Mira la [guía de Nexum Conecta](https://docs.opennexum.com/conecta/). Solo usamos fuentes oficiales y legales: el RUC sale del padrón público de SUNAT, el tipo de cambio sale del BCRP, y la emisión usa tu propio certificado y tu usuario SOL secundario. ## Por dónde empezar 1. [Inicio rápido](https://docs.opennexum.com/inicio-rapido/): una clave `onx_test_`, tu primera consulta de RUC y de tipo de cambio en el sandbox. 2. [Autenticación](https://docs.opennexum.com/autenticacion/) y [Permisos](https://docs.opennexum.com/permisos/): cómo enviar la clave y qué puede hacer cada una. 3. [Idempotencia](https://docs.opennexum.com/idempotencia/), [Saldo y error 402](https://docs.opennexum.com/saldo-y-402/) y [Límites y error 429](https://docs.opennexum.com/limites-y-429/): lo que debes saber antes de pasar a producción. 4. [Errores](https://docs.opennexum.com/errores/): cada código, con su estado HTTP y qué hacer. ## Si eres un agente de IA Lee [Para agentes de IA](https://docs.opennexum.com/agentes/). Todo el sitio está disponible en texto plano: [llms.txt](https://docs.opennexum.com/llms.txt) es el índice, [llms-full.txt](https://docs.opennexum.com/llms-full.txt) trae todo el contenido, cada página tiene su versión `.md` y el contrato completo está en [openapi.json](https://docs.opennexum.com/openapi.json). --- Fuente: https://docs.opennexum.com/inicio-rapido/ # Inicio rápido > Con una clave onx_test_ haces tu primera consulta de RUC y de tipo de cambio en el sandbox, en minutos. En esta guía usas el sandbox (`https://api-sandbox.opennexum.com`) con una clave `onx_test_…`. Consultas un RUC, el tipo de cambio y tu saldo. No necesitas certificado ni usuario SOL. > **Próximamente:** Crear claves desde el panel y la clave de prueba anónima todavía no están abiertas. Esta guía sigue el contrato v1, que ya está fijado: puedes leerlo completo en [openapi.json](https://docs.opennexum.com/openapi.json). ## 1. Guarda tu clave Una clave de prueba empieza con `onx_test_`. Guárdala en una variable de entorno; no la escribas en el código ni la pegues en un chat. ```bash export ONX_CLAVE="onx_test_…" ``` ## 2. Consulta un RUC `GET /v1/ruc/{ruc}` devuelve los datos públicos del padrón reducido de SUNAT. Pide el permiso `datos:leer`. ```bash curl "https://api-sandbox.opennexum.com/v1/ruc/20000000001" \ -H "Authorization: Bearer $ONX_CLAVE" ``` Ejemplo ilustrativo de la respuesta: ```json { "ruc": "20000000001", "razon_social": "EMPRESA DE EJEMPLO S.A.C.", "estado": "ACTIVO", "condicion": "HABIDO", "ubigeo": "150101", "direccion": "AV. EJEMPLO 123", "departamento": "LIMA", "provincia": "LIMA", "distrito": "LIMA", "padron_actualizado_al": "2026-11-14" } ``` Validamos el dígito verificador: un RUC mal escrito responde [`validacion`](https://docs.opennexum.com/errores#validacion) y uno que no existe, [`no_encontrado`](https://docs.opennexum.com/errores#no_encontrado). Todos los campos están en la [referencia de `ruc_consultar`](https://docs.opennexum.com/referencia/datos/ruc_consultar/). ## 3. Consulta el tipo de cambio `GET /v1/tipo-cambio` devuelve el tipo de cambio oficial del BCRP. Si no envías `fecha`, usa hoy en Lima. ```bash curl "https://api-sandbox.opennexum.com/v1/tipo-cambio?fecha=2026-11-15" \ -H "Authorization: Bearer $ONX_CLAVE" ``` Ejemplo ilustrativo: ```json { "fecha": "2026-11-15", "publicado_el": "2026-11-13", "moneda": "USD", "compra": "3.748", "venta": "3.752", "fuente": "BCRP" } ``` En feriados y fines de semana, `publicado_el` es la última publicación anterior. Los valores son texto con tres decimales: no los conviertas a número flotante para sumar dinero. ## 4. Mira tu saldo ```bash curl "https://api-sandbox.opennexum.com/v1/cuenta/saldo" \ -H "Authorization: Bearer $ONX_CLAVE" ``` Las consultas de datos son lecturas medidas: cuentan contra tu cupo gratis o tu saldo. Los precios están por confirmar. Si te quedas sin saldo, la API responde [`saldo_insuficiente`](https://docs.opennexum.com/errores#saldo_insuficiente); mira [Saldo y error 402](https://docs.opennexum.com/saldo-y-402/). ## Qué sigue - [Autenticación](https://docs.opennexum.com/autenticacion/): permisos, topes y alcance por RUC. - [Idempotencia](https://docs.opennexum.com/idempotencia/): obligatoria en todo lo que cobra. - [Nexum Comprobantes](https://docs.opennexum.com/comprobantes/): emite tu primera boleta en SUNAT beta. - [Para agentes de IA](https://docs.opennexum.com/agentes/): cómo conectar a Claude Code, Codex u otro agente. --- Fuente: https://docs.opennexum.com/autenticacion/ # Autenticación > Cómo enviar tu clave onx_live_ u onx_test_, y qué son los permisos, el tope y el alcance por RUC. Toda la API usa una clave de API en la cabecera `Authorization`: ```http Authorization: Bearer onx_live_… ``` ## Producción y sandbox | Clave | Entorno | Dirección | |---|---|---| | `onx_live_…` | Producción | `https://api.opennexum.com` | | `onx_test_…` | Sandbox, con SUNAT beta | `https://api-sandbox.opennexum.com` | Una clave solo funciona en su entorno. Empieza siempre por el sandbox. ## Cómo es una clave - Se crea en el panel y se muestra **una sola vez**. Después solo verás su inicio (por ejemplo `onx_live_a1b2`) para reconocerla. - Si se pierde o se filtra, revócala en el panel y crea otra: cada clave se puede revocar sin afectar a las demás. - Guárdala en una variable de entorno o en un gestor de secretos. Nunca en el código, en un repositorio ni en un chat. - Una clave nunca ve datos de otra cuenta. ## Lo que configura cada clave Una persona de tu cuenta elige estos límites para cada clave, de modo que cada agente tenga la suya: - **Permisos**: qué familias de rutas puede usar. Mira la lista en [Permisos](https://docs.opennexum.com/permisos/). Si falta uno, la API responde [`permiso_faltante`](https://docs.opennexum.com/errores#permiso_faltante). - **Tope de gasto**: un máximo diario o mensual en soles. Al llegar a él, la API responde [`tope_alcanzado`](https://docs.opennexum.com/errores#tope_alcanzado) (HTTP 402). Mira [Saldo y error 402](https://docs.opennexum.com/saldo-y-402/). - **Alcance por RUC**: a qué RUC emisores puede acceder; sin alcance, a todos los de tu cuenta. - **Aprobación humana**: qué operaciones esperan el visto bueno de una persona (notas, bajas, mensajes o comprobantes desde cierto monto). Mira [Para agentes de IA](https://docs.opennexum.com/agentes/). ## Si la clave falla - Sin clave, mal escrita, vencida o revocada: [`clave_invalida`](https://docs.opennexum.com/errores#clave_invalida) (HTTP 401). - Clave válida sin el permiso de la ruta, o sin acceso a ese RUC: [`permiso_faltante`](https://docs.opennexum.com/errores#permiso_faltante) (HTTP 403). Los datos de otra cuenta responden [`no_encontrado`](https://docs.opennexum.com/errores#no_encontrado): no revelamos que existen. > **Cuidado:** El certificado digital y el usuario SOL no viajan por el chat de un agente. Mira cómo se entregan en [Nexum Comprobantes](https://docs.opennexum.com/comprobantes/). --- Fuente: https://docs.opennexum.com/permisos/ # Permisos > Qué puede hacer cada clave y qué rutas exigen cada permiso. Cada clave nace con un conjunto de permisos que una persona elige en el panel. Cada ruta exige uno; si la clave no lo tiene, responde [`permiso_faltante`](https://docs.opennexum.com/errores#permiso_faltante). Dale a cada agente solo los permisos que necesita. | Permiso | Qué permite | Rutas que lo exigen | |---|---|---| | `datos:leer` | Consultar RUC, padrones y tipo de cambio. | [`ruc_consultar`](https://docs.opennexum.com/referencia/datos/ruc_consultar/), [`ruc_padrones`](https://docs.opennexum.com/referencia/datos/ruc_padrones/), [`tipo_cambio_consultar`](https://docs.opennexum.com/referencia/datos/tipo_cambio_consultar/) | | `emisores:administrar` | Registrar RUC emisores, sus series y sus credenciales en la bóveda. | [`emisor_crear`](https://docs.opennexum.com/referencia/emisores/emisor_crear/), [`credenciales_guardar`](https://docs.opennexum.com/referencia/emisores/credenciales_guardar/), [`serie_crear`](https://docs.opennexum.com/referencia/emisores/serie_crear/) | | `comprobantes:emitir` | Emitir comprobantes y resúmenes diarios. | [`resumen_crear`](https://docs.opennexum.com/referencia/resumenes/resumen_crear/), [`comprobante_validar`](https://docs.opennexum.com/referencia/comprobantes/comprobante_validar/), [`comprobante_emitir`](https://docs.opennexum.com/referencia/comprobantes/comprobante_emitir/) | | `comprobantes:leer` | Ver emisores, series, comprobantes, guías y descargar XML, CDR y PDF. | [`emisor_listar`](https://docs.opennexum.com/referencia/emisores/emisor_listar/), [`emisor_ver`](https://docs.opennexum.com/referencia/emisores/emisor_ver/), [`serie_listar`](https://docs.opennexum.com/referencia/emisores/serie_listar/), [`resumen_listar`](https://docs.opennexum.com/referencia/resumenes/resumen_listar/), [`resumen_ver`](https://docs.opennexum.com/referencia/resumenes/resumen_ver/), [`guia_listar`](https://docs.opennexum.com/referencia/guias/guia_listar/), [`guia_ver`](https://docs.opennexum.com/referencia/guias/guia_ver/), [`comprobante_listar`](https://docs.opennexum.com/referencia/comprobantes/comprobante_listar/), [`comprobante_ver`](https://docs.opennexum.com/referencia/comprobantes/comprobante_ver/), [`comprobante_xml`](https://docs.opennexum.com/referencia/comprobantes/comprobante_xml/), [`comprobante_cdr`](https://docs.opennexum.com/referencia/comprobantes/comprobante_cdr/), [`comprobante_pdf`](https://docs.opennexum.com/referencia/comprobantes/comprobante_pdf/), [`comprobante_consultar_sunat`](https://docs.opennexum.com/referencia/comprobantes/comprobante_consultar_sunat/) | | `comprobantes:anular` | Dar de baja comprobantes. | [`comprobante_anular`](https://docs.opennexum.com/referencia/comprobantes/comprobante_anular/) | | `guias:emitir` | Emitir guías de remisión. | [`guia_emitir`](https://docs.opennexum.com/referencia/guias/guia_emitir/) | | `sire:leer` | Pedir y leer las propuestas del SIRE. | [`sire_propuesta_pedir`](https://docs.opennexum.com/referencia/sire/sire_propuesta_pedir/), [`sire_propuesta_ver`](https://docs.opennexum.com/referencia/sire/sire_propuesta_ver/), [`sire_registros_listar`](https://docs.opennexum.com/referencia/sire/sire_registros_listar/) | | `conecta:leer` | Ver conexiones, conversaciones, mensajes, plantillas, webhooks y entregas. | [`conexion_listar`](https://docs.opennexum.com/referencia/conexiones/conexion_listar/), [`conexion_ver`](https://docs.opennexum.com/referencia/conexiones/conexion_ver/), [`conexion_probar`](https://docs.opennexum.com/referencia/conexiones/conexion_probar/), [`mensaje_ver`](https://docs.opennexum.com/referencia/mensajes/mensaje_ver/), [`conversacion_listar`](https://docs.opennexum.com/referencia/mensajes/conversacion_listar/), [`conversacion_ver`](https://docs.opennexum.com/referencia/mensajes/conversacion_ver/), [`conversacion_mensajes`](https://docs.opennexum.com/referencia/mensajes/conversacion_mensajes/), [`plantilla_listar`](https://docs.opennexum.com/referencia/plantillas/plantilla_listar/), [`webhook_listar`](https://docs.opennexum.com/referencia/webhooks/webhook_listar/), [`entrega_listar`](https://docs.opennexum.com/referencia/webhooks/entrega_listar/) | | `conecta:enviar` | Enviar mensajes y comprobantes por WhatsApp, Instagram o Messenger. | [`mensaje_enviar`](https://docs.opennexum.com/referencia/mensajes/mensaje_enviar/), [`comprobante_enviar`](https://docs.opennexum.com/referencia/mensajes/comprobante_enviar/) | | `conecta:administrar` | Crear y borrar conexiones y crear plantillas. | [`conexion_crear`](https://docs.opennexum.com/referencia/conexiones/conexion_crear/), [`conexion_borrar`](https://docs.opennexum.com/referencia/conexiones/conexion_borrar/), [`plantilla_crear`](https://docs.opennexum.com/referencia/plantillas/plantilla_crear/) | | `webhooks:administrar` | Registrar, borrar, probar y rotar webhooks y reintentar entregas. Registrar uno siempre pide aprobación humana. | [`webhook_crear`](https://docs.opennexum.com/referencia/webhooks/webhook_crear/), [`webhook_borrar`](https://docs.opennexum.com/referencia/webhooks/webhook_borrar/), [`webhook_probar`](https://docs.opennexum.com/referencia/webhooks/webhook_probar/), [`webhook_rotar_secreto`](https://docs.opennexum.com/referencia/webhooks/webhook_rotar_secreto/), [`entrega_reintentar`](https://docs.opennexum.com/referencia/webhooks/entrega_reintentar/) | | `cuenta:leer` | Ver saldo y consumo. | [`cuenta_saldo`](https://docs.opennexum.com/referencia/cuenta/cuenta_saldo/), [`cuenta_consumo`](https://docs.opennexum.com/referencia/cuenta/cuenta_consumo/) | | `cuenta:recargar` | Pedir una recarga de saldo (la paga una persona). | [`recarga_crear`](https://docs.opennexum.com/referencia/cuenta/recarga_crear/) | | `claves:administrar` | Listar, crear y revocar claves. Crear una clave siempre puede pedir aprobación humana. | [`clave_listar`](https://docs.opennexum.com/referencia/claves/clave_listar/), [`clave_crear`](https://docs.opennexum.com/referencia/claves/clave_crear/), [`clave_revocar`](https://docs.opennexum.com/referencia/claves/clave_revocar/) | | `credenciales:por_llamada` | Enviar certificado y usuario SOL dentro de la llamada (no se guardan). | Ninguna ruta lo pide por sí solo. | Las rutas que no piden un permiso concreto solo exigen una clave activa y solo ven lo de su propia cuenta. --- Fuente: https://docs.opennexum.com/idempotencia/ # Idempotencia > Con la cabecera Idempotency-Key puedes repetir una petición sin cobrar ni emitir dos veces. Si una petición se corta por la red, no sabes si llegó. Con `Idempotency-Key` puedes repetirla sin riesgo: si ya la procesamos, te devolvemos la misma respuesta y **no se cobra dos veces ni se emite un segundo comprobante**. ## Cómo usarla Envía un identificador único por operación, por ejemplo un UUID: ```bash curl -X POST "https://api-sandbox.opennexum.com/v1/emisores/20000000001/comprobantes" \ -H "Authorization: Bearer $ONX_CLAVE" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d @boleta.json ``` - Formato: de 8 a 255 caracteres entre letras, números y `.` `_` `:` `-`. - **Obligatoria** en toda operación que cobra (comprobantes, guías, SIRE, comprobante por WhatsApp) y en las que crean claves, recargas, resúmenes o webhooks. Sin ella, la API rechaza la petición. - **Opcional** en otras creaciones (emisores, series, conexiones, plantillas). Úsala igual. - No aplica a las lecturas. - Cada página de la [referencia](https://docs.opennexum.com/referencia/) dice en su ficha si la cabecera es obligatoria. ## Qué pasa al repetir | Repites con | Resultado | |---|---| | La misma clave y el mismo cuerpo | La misma respuesta de la primera vez. No se cobra de nuevo. | | La misma clave y otro cuerpo | [`idempotencia_en_conflicto`](https://docs.opennexum.com/errores#idempotencia_en_conflicto) (HTTP 409). | | La misma clave mientras la primera sigue en curso | [`solicitud_en_curso`](https://docs.opennexum.com/errores#solicitud_en_curso) (HTTP 409). Espera unos segundos y consulta. | La clave se guarda 24 horas. ## Reglas para reintentar 1. Genera la clave **antes** de la primera llamada y guárdala junto a la operación. 2. Si hay un corte, un tiempo agotado o un [`error_interno`](https://docs.opennexum.com/errores#error_interno), repite con la **misma** clave y el **mismo** cuerpo. 3. Si quieres hacer una operación distinta, genera una clave nueva. 4. Un `202` no se repite: `en_cola` se completa solo y `requiere_confirmacion` espera a una persona. Mira [Para agentes de IA](https://docs.opennexum.com/agentes/). --- Fuente: https://docs.opennexum.com/saldo-y-402/ # Saldo y error 402 > Cómo funciona el saldo prepagado en soles y qué hacer cuando la API responde 402 con recarga_url. OpenNexum funciona con **saldo prepagado en soles**. Tú recargas, y cada operación que cobra descuenta de ese saldo. Los precios están por confirmar; consulta siempre tu consumo en lugar de suponerlo. ## Cómo se cobra - Al empezar una operación que cobra, **reservamos** su precio de tu saldo. - Lo **cobramos solo si el servicio confirma**. Por ejemplo, un comprobante se cobra cuando SUNAT lo acepta; si SUNAT lo rechaza, la reserva se libera. - Las consultas de datos (RUC, tipo de cambio) son lecturas medidas: cuentan contra tu cupo gratis o tu saldo. Consulta tu saldo con `GET /v1/cuenta/saldo`: trae lo `disponible`, lo `reservado`, el tope de la clave que pregunta y `recarga_url`. El consumo detallado está en `GET /v1/cuenta/consumo`. En la API los montos son texto con dos decimales: `"1250.50"` es S/ 1,250.50. ## El error 402 Cuando no hay con qué pagar la operación, la API responde **402** con `recarga_url`: ```json { "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.", "detalle": { "disponible": "12.40", "requerido": "15.00" }, "request_id": "req_8f2c1a7d", "docs": "https://docs.opennexum.com/errores#saldo_insuficiente", "recarga_url": "https://app.opennexum.com/recargar" } } ``` Hay dos códigos, los dos con HTTP 402: - [`saldo_insuficiente`](https://docs.opennexum.com/errores#saldo_insuficiente): el saldo de la cuenta no alcanza. En `detalle`, `disponible` es lo que queda y `requerido` lo que costaría la operación. - [`tope_alcanzado`](https://docs.opennexum.com/errores#tope_alcanzado): la clave llegó a su tope de gasto del periodo (diario o mensual), aunque la cuenta tenga saldo. Una persona sube el tope desde el panel. En `detalle`, `disponible` es lo que queda del tope. ## Qué hacer al recibir un 402 1. **No reintentes en bucle**: el resultado no va a cambiar hasta que alguien recargue o suba el tope. 2. Dile a una persona de tu cuenta lo que pasó y pásale `recarga_url` tal cual. 3. Cuando te avise que recargó, repite la operación con la **misma** `Idempotency-Key`: mira [Idempotencia](https://docs.opennexum.com/idempotencia/). Un agente nunca recarga por su cuenta ni sube su propio tope: esa decisión es de una persona. > **Próximamente:** Pedir una recarga desde la API (`recarga_crear`) y la recarga con Yape todavía no están disponibles. Por ahora la recarga se hace desde `recarga_url`. --- Fuente: https://docs.opennexum.com/limites-y-429/ # Límites y error 429 > Qué pasa si haces demasiadas peticiones seguidas y cómo usar la cabecera Retry-After. Para que la API responda bien a todos, limitamos cuántas peticiones puedes hacer seguidas. Los límites numéricos por clave están por confirmar; programa tu cliente para respetar la señal de la API en lugar de depender de una cifra. ## El error 429 Si te pasas, la API responde **429** con el código [`limite_uso`](https://docs.opennexum.com/errores#limite_uso) y la cabecera `Retry-After`: ```http HTTP/1.1 429 Too Many Requests Retry-After: 12 X-Request-Id: req_8f2c1a7d ``` ```json { "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" } } ``` `Retry-After` son los **segundos** que debes esperar antes de volver a intentar. ## Cómo reintentar 1. Espera al menos `Retry-After` segundos. No reintentes antes. 2. Repite la misma petición. Si lleva `Idempotency-Key`, usa la **misma** clave: mira [Idempotencia](https://docs.opennexum.com/idempotencia/). 3. Si vuelves a recibir 429, espera más cada vez (espera exponencial con un poco de azar) y pon un máximo de intentos. 4. Reparte tus llamadas en el tiempo en lugar de lanzarlas todas juntas. También usan `Retry-After` los errores [`no_disponible`](https://docs.opennexum.com/errores#no_disponible) (HTTP 503), cuando un dato todavía se está cargando de nuestro lado. ## Cómo reducir las peticiones - Pide listas con `limite` y `cursor` en lugar de consultar uno por uno. - Guarda lo que cambia poco, como un RUC o el tipo de cambio del día. - En Nexum Conecta, recibe los eventos por [webhook](https://docs.opennexum.com/referencia/eventos-webhook/) en lugar de consultar la bandeja cada pocos segundos. --- Fuente: https://docs.opennexum.com/errores/ # Errores > Cada código de error de la API con su estado HTTP y lo que debes hacer. Todos los errores tienen la misma forma. El `codigo` no cambia entre versiones: programa contra él, no contra el `mensaje`. ```json { "error": { "codigo": "saldo_insuficiente", "mensaje": "No te alcanza el saldo para esta operación.", "detalle": { "disponible": "12.40", "requerido": "15.00" }, "request_id": "req_8f2c1a7d", "docs": "https://docs.opennexum.com/errores#saldo_insuficiente", "recarga_url": "https://app.opennexum.com/recargar" } } ``` - `mensaje` explica en español qué pasó y cómo se arregla. - `detalle` trae los datos para corregirlo (por ejemplo, cada campo con su problema). - `request_id` también viaja en la cabecera `X-Request-Id`; menciónalo si escribes a soporte. - `docs` apunta a la sección de esta página; `recarga_url` aparece solo en errores de saldo. | Código | HTTP | |---|---| | [`validacion`](#validacion) | 400 | | [`clave_invalida`](#clave_invalida) | 401 | | [`saldo_insuficiente`](#saldo_insuficiente) | 402 | | [`tope_alcanzado`](#tope_alcanzado) | 402 | | [`permiso_faltante`](#permiso_faltante) | 403 | | [`emisor_obligado_ose`](#emisor_obligado_ose) | 403 | | [`no_encontrado`](#no_encontrado) | 404 | | [`idempotencia_en_conflicto`](#idempotencia_en_conflicto) | 409 | | [`solicitud_en_curso`](#solicitud_en_curso) | 409 | | [`ya_registrado`](#ya_registrado) | 409 | | [`ventana_cerrada`](#ventana_cerrada) | 409 | | [`boveda_inactiva`](#boveda_inactiva) | 409 | | [`estado_no_permite`](#estado_no_permite) | 409 | | [`plazo_vencido`](#plazo_vencido) | 409 | | [`sunat_rechazo`](#sunat_rechazo) | 422 | | [`credenciales_sunat`](#credenciales_sunat) | 422 | | [`limite_uso`](#limite_uso) | 429 | | [`error_interno`](#error_interno) | 500 | | [`servicio_externo_no_disponible`](#servicio_externo_no_disponible) | 502 | | [`no_disponible`](#no_disponible) | 503 | | [`operacion_no_disponible`](#operacion_no_disponible) | 501 | ## validacion **HTTP 400** · Solicitud incorrecta Algún dato no cumple el formato. En `detalle` va cada campo con su problema. ## clave_invalida **HTTP 401** · No autorizado Falta la clave de API, está mal escrita, venció o fue revocada. Envíala como `Authorization: Bearer onx_live_…`. ## saldo_insuficiente **HTTP 402** · Pago requerido No te alcanza el saldo para esta operación. Pásale `recarga_url` a una persona de tu cuenta para que recargue. La respuesta trae `recarga_url` y, en `detalle`, el saldo `disponible` y lo `requerido`. Un agente no recarga: le pasa el enlace a una persona y espera. Más en [Saldo y error 402](https://docs.opennexum.com/saldo-y-402/). ## tope_alcanzado **HTTP 402** · Pago requerido La clave llegó a su tope de gasto del periodo. Una persona de tu cuenta puede subirlo desde el panel. También responde 402 con `recarga_url`; en el panel una persona sube el tope de la clave. Más en [Saldo y error 402](https://docs.opennexum.com/saldo-y-402/). ## permiso_faltante **HTTP 403** · Prohibido La clave no tiene el permiso que pide esta ruta o no tiene acceso a ese RUC. ## emisor_obligado_ose **HTTP 403** · Prohibido Ese RUC figura en el padrón de obligados a emitir mediante un OSE; por ahora no podemos emitir por él. ## no_encontrado **HTTP 404** · No encontrado No existe o no pertenece a tu cuenta. ## idempotencia_en_conflicto **HTTP 409** · Conflicto Usaste la misma `Idempotency-Key` con otro cuerpo. Genera una clave nueva para cada operación distinta. Más en [Idempotencia](https://docs.opennexum.com/idempotencia/). ## solicitud_en_curso **HTTP 409** · Conflicto Ya estamos procesando una petición con esa `Idempotency-Key`. Espera unos segundos y vuelve a consultar. Más en [Idempotencia](https://docs.opennexum.com/idempotencia/). ## ya_registrado **HTTP 409** · Conflicto Eso ya está registrado: por ejemplo, el RUC ya está en otra cuenta o la serie ya existe. ## ventana_cerrada **HTTP 409** · Conflicto La conversación está fuera de la ventana de atención: solo puedes escribir con una plantilla aprobada. `detalle.plantillas_sugeridas` trae opciones. ## boveda_inactiva **HTTP 409** · Conflicto La bóveda de credenciales todavía no está activa. Envía `credenciales` en cada llamada. ## estado_no_permite **HTTP 409** · Conflicto El recurso está en un estado que no permite esta operación, por ejemplo anular un comprobante rechazado. ## plazo_vencido **HTTP 409** · Conflicto Pasó el plazo que da SUNAT para esta operación. Para anular una factura fuera de plazo, emite una nota de crédito. ## sunat_rechazo **HTTP 422** · No procesable SUNAT rechazó el comprobante. En `detalle` van el código y la descripción que dio SUNAT. ## credenciales_sunat **HTTP 422** · No procesable SUNAT no aceptó el certificado o el usuario SOL, o el certificado es de otro RUC. ## limite_uso **HTTP 429** · Demasiadas peticiones Hiciste demasiadas peticiones seguidas. Espera los segundos que indica `Retry-After` y vuelve a intentar. La respuesta trae la cabecera `Retry-After` con los segundos de espera. Más en [Límites y error 429](https://docs.opennexum.com/limites-y-429/). ## error_interno **HTTP 500** · Error interno Algo falló de nuestro lado. Repite la petición con la misma `Idempotency-Key`: no se duplica nada. Menciona el `request_id` si escribes a soporte. ## servicio_externo_no_disponible **HTTP 502** · Mala puerta de enlace SUNAT, el BCRP o el proveedor de mensajería no respondió. Revisa el estado antes de reenviar. ## no_disponible **HTTP 503** · Servicio 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`. La respuesta trae la cabecera `Retry-After` con los segundos de espera. ## operacion_no_disponible **HTTP 501** · 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. --- Fuente: https://docs.opennexum.com/comprobantes/ # Nexum Comprobantes > Emite facturas, boletas y notas electrónicas a SUNAT, y consulta RUC, tipo de cambio y padrones, con tu propio certificado. Nexum Comprobantes conecta SUNAT a tu sistema o a tu agente de IA. Emite factura (01), boleta (03), nota de crédito (07) y nota de débito (08), y además resúmenes diarios, comunicaciones de baja, guías de remisión remitente y propuestas del SIRE. Cada comprobante sale con su XML, su CDR y su PDF. Usa tu propio certificado digital y tu usuario SOL secundario. En el sandbox, las pruebas van contra SUNAT beta. ## El camino de una boleta 1. **Registra el emisor** con [`emisor_crear`](https://docs.opennexum.com/referencia/emisores/emisor_crear/). Si el RUC figura en el padrón de obligados a emitir mediante un OSE, no podemos emitir por él y la API responde [`emisor_obligado_ose`](https://docs.opennexum.com/errores#emisor_obligado_ose). 2. **Entrega las credenciales**: certificado y usuario SOL. Mira la nota de abajo. 3. **Crea una serie** con [`serie_crear`](https://docs.opennexum.com/referencia/emisores/serie_crear/). 4. **Valida sin cobrar** con [`comprobante_validar`](https://docs.opennexum.com/referencia/comprobantes/comprobante_validar/): revisa el cuerpo y calcula los totales sin enviar nada. 5. **Emite** con [`comprobante_emitir`](https://docs.opennexum.com/referencia/comprobantes/comprobante_emitir/), con `Idempotency-Key`. El número lo asigna el servidor. 6. **Descarga** el [XML](https://docs.opennexum.com/referencia/comprobantes/comprobante_xml/), el [CDR](https://docs.opennexum.com/referencia/comprobantes/comprobante_cdr/) o el [PDF](https://docs.opennexum.com/referencia/comprobantes/comprobante_pdf/). ## Qué responde al emitir | Estado | Qué significa | |---|---| | `201` | SUNAT lo aceptó (o lo aceptó con observaciones). Se cobra. | | `202` `en_cola` | SUNAT no respondió. Lo enviamos solo cuando vuelva; no lo repitas y consulta `consulta_url`. | | `202` `requiere_confirmacion` | Según tu clave, una persona debe aprobarlo en el panel. Nada se cobró todavía. | | `422` [`sunat_rechazo`](https://docs.opennexum.com/errores#sunat_rechazo) | SUNAT lo rechazó. En `detalle` van el código y la descripción de SUNAT. Se libera la reserva. | | `422` [`credenciales_sunat`](https://docs.opennexum.com/errores#credenciales_sunat) | SUNAT no aceptó el certificado o el usuario SOL. | Se cobra solo si SUNAT acepta: mira [Saldo y error 402](https://docs.opennexum.com/saldo-y-402/). La emisión exige `Idempotency-Key`: mira [Idempotencia](https://docs.opennexum.com/idempotencia/). ## Credenciales El certificado y el usuario SOL **nunca pasan por el chat de un agente**. Hay dos caminos: - **Guardarlas una vez** con [`credenciales_guardar`](https://docs.opennexum.com/referencia/emisores/credenciales_guardar/), a cargo de una persona. Esa ruta no se ofrece a agentes. - **Enviarlas en la llamada**, en el campo `credenciales` de cada cuerpo. No se guardan, y la clave necesita el permiso `credenciales:por_llamada`. Mientras la bóveda no esté activa, la API responde [`boveda_inactiva`](https://docs.opennexum.com/errores#boveda_inactiva) y debes usar el segundo camino. > **Próximamente:** La bóveda de credenciales todavía no está activa. ## Anular y corregir - Para dar de baja usa [`comprobante_anular`](https://docs.opennexum.com/referencia/comprobantes/comprobante_anular/). Según tu clave, una persona debe aprobarlo. - Si pasó el plazo de SUNAT, responde [`plazo_vencido`](https://docs.opennexum.com/errores#plazo_vencido): para una factura, emite una nota de crédito. - Un comprobante en un estado que no admite la operación (por ejemplo, uno rechazado) responde [`estado_no_permite`](https://docs.opennexum.com/errores#estado_no_permite). - Las boletas se informan con [resúmenes diarios](https://docs.opennexum.com/referencia/resumenes/resumen_crear/). ## Datos oficiales Con el permiso `datos:leer` también tienes [`ruc_consultar`](https://docs.opennexum.com/referencia/datos/ruc_consultar/), [`ruc_padrones`](https://docs.opennexum.com/referencia/datos/ruc_padrones/) y [`tipo_cambio_consultar`](https://docs.opennexum.com/referencia/datos/tipo_cambio_consultar/). El RUC sale del padrón público de SUNAT y el tipo de cambio del BCRP. ## Referencia Todas las rutas están en la [referencia de la API](https://docs.opennexum.com/referencia/), generada desde el contrato. --- Fuente: https://docs.opennexum.com/conecta/ # Nexum Conecta > WhatsApp, Instagram y Messenger como funciones de tu API: bandeja, mensajes, plantillas, comprobante por WhatsApp y webhooks firmados. Nexum Conecta pone tres canales de Meta detrás de la misma clave que usas para comprobantes: una bandeja unificada, envío de mensajes, plantillas, el envío del comprobante por WhatsApp y eventos firmados hacia tu sistema. No es una copia de la API de Meta: es un conjunto de funciones con nombres de mostrador. > **Próximamente:** La conexión en vivo con Meta todavía no está abierta. Esta guía describe el contrato v1, que ya está fijado y ya aparece en la [referencia](https://docs.opennexum.com/referencia/). ## Conexiones Una conexión es un número de WhatsApp, una cuenta de Instagram o una página de Messenger. La creas con [`conexion_crear`](https://docs.opennexum.com/referencia/conexiones/conexion_crear/), la verificas con [`conexion_probar`](https://docs.opennexum.com/referencia/conexiones/conexion_probar/) y la ves o borras con [`conexion_ver`](https://docs.opennexum.com/referencia/conexiones/conexion_ver/) y [`conexion_borrar`](https://docs.opennexum.com/referencia/conexiones/conexion_borrar/). Borrar una conexión puede pedir la aprobación de una persona. ## Enviar mensajes [`mensaje_enviar`](https://docs.opennexum.com/referencia/mensajes/mensaje_enviar/) escribe por cualquiera de los tres canales y exige `Idempotency-Key`. Según tu clave, el envío espera la aprobación de una persona (`202` `requiere_confirmacion`): mira [Para agentes de IA](https://docs.opennexum.com/agentes/). ### La ventana de 24 horas WhatsApp solo deja escribir texto libre dentro de las 24 horas siguientes al último mensaje del cliente. Fuera de esa ventana debes usar una plantilla aprobada. Si no lo haces, la API responde [`ventana_cerrada`](https://docs.opennexum.com/errores#ventana_cerrada) y en `detalle.plantillas_sugeridas` trae opciones. Crea y consulta plantillas con [`plantilla_crear`](https://docs.opennexum.com/referencia/plantillas/plantilla_crear/) y [`plantilla_listar`](https://docs.opennexum.com/referencia/plantillas/plantilla_listar/). En los recordatorios de pago usa un lenguaje neutro: fecha, monto y cómo pagar. ## Leer la bandeja - [`conversacion_listar`](https://docs.opennexum.com/referencia/mensajes/conversacion_listar/) lista las conversaciones de los tres canales. - [`conversacion_mensajes`](https://docs.opennexum.com/referencia/mensajes/conversacion_mensajes/) trae los mensajes de una conversación, con cursor. - [`mensaje_ver`](https://docs.opennexum.com/referencia/mensajes/mensaje_ver/) consulta el estado de un mensaje enviado. ## Comprobante por WhatsApp [`comprobante_enviar`](https://docs.opennexum.com/referencia/mensajes/comprobante_enviar/) manda un comprobante emitido con Nexum Comprobantes al cliente por WhatsApp. Reserva el precio y lo cobra solo si el envío se confirma: mira [Saldo y error 402](https://docs.opennexum.com/saldo-y-402/). ## Webhooks En lugar de consultar la bandeja, recibe los eventos en tu sistema. Cada evento llega firmado con `X-Nexum-Signature`; verifícala siempre y responde en menos de 10 segundos. Los pasos y los campos están en [Eventos de webhook](https://docs.opennexum.com/referencia/eventos-webhook/). - Registrar un webhook ([`webhook_crear`](https://docs.opennexum.com/referencia/webhooks/webhook_crear/)) siempre espera la aprobación de una persona. - Un mismo evento puede llegar más de una vez: usa su `id` para no procesarlo dos veces. - Si fallas, reintentamos con espera creciente; luego el webhook se pausa y puedes reenviar con [`entrega_reintentar`](https://docs.opennexum.com/referencia/webhooks/entrega_reintentar/). --- Fuente: https://docs.opennexum.com/agentes/ # Para agentes de IA > Cómo conectar a Claude Code, Codex u otro agente: documentación en texto plano, skill, confirmación humana y lo que llega próximamente (MCP, OAuth, login). OpenNexum está hecho para que un agente de IA lo use con seguridad: cada agente tiene su propia clave con tope, el dinero y lo irreversible los decide una persona, y toda la documentación se puede leer en texto plano. ## Lo que ya puedes usar ### La API HTTP Un agente llama a la API con una clave `onx_test_…` o `onx_live_…`, como cualquier cliente. Empieza por [Inicio rápido](https://docs.opennexum.com/inicio-rapido/) y [Autenticación](https://docs.opennexum.com/autenticacion/). Dale a cada agente su propia clave, con los [permisos](https://docs.opennexum.com/permisos/) mínimos y un tope de gasto. ### Documentación para agentes | Recurso | Qué es | |---|---| | [llms.txt](https://docs.opennexum.com/llms.txt) | Índice de todo el sitio, con un enlace por página. | | [llms-full.txt](https://docs.opennexum.com/llms-full.txt) | Todo el contenido en un solo archivo de texto. | | Versión `.md` de cada página | Añade `.md` a la dirección: `/errores.md`, `/inicio-rapido.md`. | | [openapi.json](https://docs.opennexum.com/openapi.json) | El contrato completo de la API (OpenAPI 3.1). | ### Skill instalable (borrador) Hay un borrador de skill con cuándo usar OpenNexum, la autenticación, los errores y cómo pedir confirmación humana. Descárgalo a la carpeta de skills de tu agente; en Claude Code: ```bash mkdir -p ~/.claude/skills/opennexum curl -o ~/.claude/skills/opennexum/SKILL.md https://docs.opennexum.com/skill/opennexum/SKILL.md ``` ## Próximamente > **Próximamente:** Lo siguiente todavía no está construido. No lo asumas en tus flujos: > > - **Servidor MCP remoto con OAuth**: `claude mcp add --transport http opennexum https://mcp.opennexum.com/mcp`. > - **Alta con código de dispositivo**: `npx opennexum login`, que abre el navegador para que una persona apruebe al agente. > - **Clave de prueba anónima** y creación de claves desde el panel. Cuando existan, cada herramienta MCP se llamará como el `operationId` de la [referencia](https://docs.opennexum.com/referencia/): por ejemplo, `ruc_consultar` o `comprobante_emitir`. Las rutas que no conviene exponer a un agente (crear claves, guardar credenciales, crear webhooks) no tendrán herramienta. ## Confirmación humana Lo irreversible o delicado espera a una persona. Según la configuración de la clave, notas, bajas, mensajes y comprobantes desde cierto monto responden `202` con `estado: requiere_confirmacion` (ejemplo ilustrativo): ```json { "estado": "requiere_confirmacion", "operacion_id": "op_8f2c1a7d9e", "confirmacion_url": "https://app.opennexum.com/confirmar/op_8f2c1a7d9e", "consulta_url": "/v1/confirmaciones/op_8f2c1a7d9e", "expira_en": "2026-11-15T17:30:00-05:00", "mensaje": "Falta que una persona apruebe esta nota de crédito." } ``` Lo que debe hacer el agente: 1. **No repetir la operación** ni intentar aprobarla: el «sí» nunca viaja como argumento de la API. Nada se cobró todavía. 2. **Decirle a la persona** qué se va a hacer (con el campo `mensaje`) y pasarle `confirmacion_url` tal cual. 3. **Consultar** [`confirmacion_ver`](https://docs.opennexum.com/referencia/confirmaciones/confirmacion_ver/) con el `operacion_id` hasta que el estado sea `ejecutada`, `rechazada` o `vencida`. 4. Si se rechazó o venció, **no insistir** sin que la persona lo pida. Algunas rutas siempre piden aprobación, sin importar la clave: crear una clave y registrar un webhook. ## Reglas de oro - **Saldo**: ante un [402](https://docs.opennexum.com/saldo-y-402/), el agente le pasa `recarga_url` a una persona y espera. No recarga ni sube su propio tope. - **Límites**: ante un [429](https://docs.opennexum.com/limites-y-429/), espera `Retry-After`. - **Idempotencia**: guarda la `Idempotency-Key` de cada operación y reutilízala al reintentar. Mira [Idempotencia](https://docs.opennexum.com/idempotencia/). - **Secretos**: la clave, el certificado y el usuario SOL no se escriben en el chat, en archivos del repositorio ni en registros. - **Errores**: programa contra el `codigo`, no contra el `mensaje`. Cada código está en [Errores](https://docs.opennexum.com/errores/). --- Fuente: https://docs.opennexum.com/referencia/ # Referencia de la API > Todas las rutas de la API v1, generadas desde openapi.json. Esta referencia se genera desde el contrato de la API (`openapi.json`, versión 1.0.0), así que no se desfasa. Puedes descargar el contrato en [openapi.json](https://docs.opennexum.com/openapi.json). - `https://api.opennexum.com`: Producción (claves onx_live_) - `https://api-sandbox.opennexum.com`: Sandbox con SUNAT beta (claves onx_test_) Todas las rutas piden `Authorization: Bearer …`; mira [Autenticación](https://docs.opennexum.com/autenticacion/). Los eventos que enviamos a tu sistema están en [Eventos de webhook](https://docs.opennexum.com/referencia/eventos-webhook/). ## Cuenta Saldo, consumo y recargas en soles. | Operación | Ruta | |---|---| | [Dice quién eres](https://docs.opennexum.com/referencia/cuenta/yo_ver/) | `GET /v1/yo` | | [Consulta tu saldo](https://docs.opennexum.com/referencia/cuenta/cuenta_saldo/) | `GET /v1/cuenta/saldo` | | [Lista tu consumo](https://docs.opennexum.com/referencia/cuenta/cuenta_consumo/) | `GET /v1/cuenta/consumo` | | [Declara una recarga por Yape o Plin](https://docs.opennexum.com/referencia/cuenta/recarga_crear/) | `POST /v1/cuenta/recargas` | | [Abre un ticket de soporte](https://docs.opennexum.com/referencia/cuenta/ticket_crear/) | `POST /v1/soporte/tickets` | | [Lista tus tickets de soporte](https://docs.opennexum.com/referencia/cuenta/ticket_listar/) | `GET /v1/soporte/tickets` | | [Consulta un ticket de soporte](https://docs.opennexum.com/referencia/cuenta/ticket_ver/) | `GET /v1/soporte/tickets/{id}` | | [Responde en un ticket de soporte](https://docs.opennexum.com/referencia/cuenta/ticket_responder/) | `POST /v1/soporte/tickets/{id}/mensajes` | | [Cierra un ticket de soporte](https://docs.opennexum.com/referencia/cuenta/ticket_cerrar/) | `POST /v1/soporte/tickets/{id}/cerrar` | ## Claves Claves de API por agente, con permisos, tope y alcance por RUC. | Operación | Ruta | |---|---| | [Lista las claves de tu cuenta](https://docs.opennexum.com/referencia/claves/clave_listar/) | `GET /v1/claves` | | [Crea una clave con tope y permisos](https://docs.opennexum.com/referencia/claves/clave_crear/) | `POST /v1/claves` | | [Revoca una clave](https://docs.opennexum.com/referencia/claves/clave_revocar/) | `DELETE /v1/claves/{id}` | ## Confirmaciones Operaciones que esperan la aprobación de una persona. | Operación | Ruta | |---|---| | [Consulta una aprobación pendiente](https://docs.opennexum.com/referencia/confirmaciones/confirmacion_ver/) | `GET /v1/confirmaciones/{id}` | ## Datos RUC, padrones y tipo de cambio desde fuentes oficiales. | Operación | Ruta | |---|---| | [Consulta un RUC](https://docs.opennexum.com/referencia/datos/ruc_consultar/) | `GET /v1/ruc/{ruc}` | | [Consulta los padrones de un RUC](https://docs.opennexum.com/referencia/datos/ruc_padrones/) | `GET /v1/ruc/{ruc}/padrones` | | [Consulta el tipo de cambio](https://docs.opennexum.com/referencia/datos/tipo_cambio_consultar/) | `GET /v1/tipo-cambio` | ## Emisores RUC emisores, series y credenciales. | Operación | Ruta | |---|---| | [Registra un RUC emisor](https://docs.opennexum.com/referencia/emisores/emisor_crear/) | `POST /v1/emisores` | | [Lista tus RUC emisores](https://docs.opennexum.com/referencia/emisores/emisor_listar/) | `GET /v1/emisores` | | [Consulta un RUC emisor](https://docs.opennexum.com/referencia/emisores/emisor_ver/) | `GET /v1/emisores/{ruc}` | | [Guarda credenciales en la bóveda](https://docs.opennexum.com/referencia/emisores/credenciales_guardar/) | `PUT /v1/emisores/{ruc}/credenciales` | | [Lista las series de un emisor](https://docs.opennexum.com/referencia/emisores/serie_listar/) | `GET /v1/emisores/{ruc}/series` | | [Crea una serie](https://docs.opennexum.com/referencia/emisores/serie_crear/) | `POST /v1/emisores/{ruc}/series` | ## Comprobantes Facturas, boletas y notas: emitir, consultar, descargar y dar de baja. | Operación | Ruta | |---|---| | [Ensaya un comprobante sin emitirlo](https://docs.opennexum.com/referencia/comprobantes/comprobante_validar/) | `POST /v1/emisores/{ruc}/comprobantes/validar` | | [Emite una factura, boleta o nota](https://docs.opennexum.com/referencia/comprobantes/comprobante_emitir/) | `POST /v1/emisores/{ruc}/comprobantes` | | [Lista comprobantes de un emisor](https://docs.opennexum.com/referencia/comprobantes/comprobante_listar/) | `GET /v1/emisores/{ruc}/comprobantes` | | [Consulta un comprobante](https://docs.opennexum.com/referencia/comprobantes/comprobante_ver/) | `GET /v1/emisores/{ruc}/comprobantes/{id}` | | [Descarga el XML firmado](https://docs.opennexum.com/referencia/comprobantes/comprobante_xml/) | `GET /v1/emisores/{ruc}/comprobantes/{id}/xml` | | [Descarga el CDR](https://docs.opennexum.com/referencia/comprobantes/comprobante_cdr/) | `GET /v1/emisores/{ruc}/comprobantes/{id}/cdr` | | [Descarga el PDF](https://docs.opennexum.com/referencia/comprobantes/comprobante_pdf/) | `GET /v1/emisores/{ruc}/comprobantes/{id}/pdf` | | [Da de baja un comprobante](https://docs.opennexum.com/referencia/comprobantes/comprobante_anular/) | `POST /v1/emisores/{ruc}/comprobantes/{id}/anular` | | [Pregunta a SUNAT el estado de un comprobante](https://docs.opennexum.com/referencia/comprobantes/comprobante_consultar_sunat/) | `POST /v1/emisores/{ruc}/comprobantes/{id}/consultar-sunat` | ## Resúmenes Resúmenes diarios de boletas y comunicaciones de baja. | Operación | Ruta | |---|---| | [Envía el resumen diario de boletas](https://docs.opennexum.com/referencia/resumenes/resumen_crear/) | `POST /v1/emisores/{ruc}/resumenes` | | [Lista resúmenes y comunicaciones de baja](https://docs.opennexum.com/referencia/resumenes/resumen_listar/) | `GET /v1/emisores/{ruc}/resumenes` | | [Consulta un resumen](https://docs.opennexum.com/referencia/resumenes/resumen_ver/) | `GET /v1/emisores/{ruc}/resumenes/{id}` | ## Guías Guías de remisión remitente. | Operación | Ruta | |---|---| | [Emite una guía de remisión remitente](https://docs.opennexum.com/referencia/guias/guia_emitir/) | `POST /v1/emisores/{ruc}/guias` | | [Lista guías de un emisor](https://docs.opennexum.com/referencia/guias/guia_listar/) | `GET /v1/emisores/{ruc}/guias` | | [Consulta una guía](https://docs.opennexum.com/referencia/guias/guia_ver/) | `GET /v1/emisores/{ruc}/guias/{id}` | ## SIRE Propuestas de ventas (RVIE) y compras (RCE). | Operación | Ruta | |---|---| | [Pide la propuesta del SIRE de un periodo](https://docs.opennexum.com/referencia/sire/sire_propuesta_pedir/) | `POST /v1/emisores/{ruc}/sire/propuestas` | | [Consulta una propuesta del SIRE](https://docs.opennexum.com/referencia/sire/sire_propuesta_ver/) | `GET /v1/emisores/{ruc}/sire/propuestas/{id}` | | [Lista las líneas de una propuesta del SIRE](https://docs.opennexum.com/referencia/sire/sire_registros_listar/) | `GET /v1/emisores/{ruc}/sire/propuestas/{id}/registros` | ## Conexiones Números de WhatsApp, cuentas de Instagram y páginas de Messenger conectadas. | Operación | Ruta | |---|---| | [Crea una conexión de WhatsApp, Instagram o Messenger](https://docs.opennexum.com/referencia/conexiones/conexion_crear/) | `POST /v1/conecta/conexiones` | | [Lista tus conexiones](https://docs.opennexum.com/referencia/conexiones/conexion_listar/) | `GET /v1/conecta/conexiones` | | [Consulta una conexión](https://docs.opennexum.com/referencia/conexiones/conexion_ver/) | `GET /v1/conecta/conexiones/{id}` | | [Borra una conexión](https://docs.opennexum.com/referencia/conexiones/conexion_borrar/) | `DELETE /v1/conecta/conexiones/{id}` | | [Prueba una conexión](https://docs.opennexum.com/referencia/conexiones/conexion_probar/) | `POST /v1/conecta/conexiones/{id}/probar` | ## Mensajes Bandeja, envío de mensajes y de comprobantes. | Operación | Ruta | |---|---| | [Envía un mensaje](https://docs.opennexum.com/referencia/mensajes/mensaje_enviar/) | `POST /v1/conecta/mensajes` | | [Consulta un mensaje](https://docs.opennexum.com/referencia/mensajes/mensaje_ver/) | `GET /v1/conecta/mensajes/{id}` | | [Lista conversaciones](https://docs.opennexum.com/referencia/mensajes/conversacion_listar/) | `GET /v1/conecta/conversaciones` | | [Consulta una conversación](https://docs.opennexum.com/referencia/mensajes/conversacion_ver/) | `GET /v1/conecta/conversaciones/{id}` | | [Lista los mensajes de una conversación](https://docs.opennexum.com/referencia/mensajes/conversacion_mensajes/) | `GET /v1/conecta/conversaciones/{id}/mensajes` | | [Envía un comprobante por mensaje](https://docs.opennexum.com/referencia/mensajes/comprobante_enviar/) | `POST /v1/conecta/comprobantes/enviar` | ## Plantillas Plantillas de mensaje para escribir fuera de la ventana de atención. | Operación | Ruta | |---|---| | [Lista plantillas](https://docs.opennexum.com/referencia/plantillas/plantilla_listar/) | `GET /v1/conecta/plantillas` | | [Crea una plantilla](https://docs.opennexum.com/referencia/plantillas/plantilla_crear/) | `POST /v1/conecta/plantillas` | ## Webhooks Eventos normalizados y firmados hacia tu sistema. | Operación | Ruta | |---|---| | [Registra un webhook](https://docs.opennexum.com/referencia/webhooks/webhook_crear/) | `POST /v1/conecta/webhooks` | | [Lista tus webhooks](https://docs.opennexum.com/referencia/webhooks/webhook_listar/) | `GET /v1/conecta/webhooks` | | [Borra un webhook](https://docs.opennexum.com/referencia/webhooks/webhook_borrar/) | `DELETE /v1/conecta/webhooks/{id}` | | [Envía un evento de prueba](https://docs.opennexum.com/referencia/webhooks/webhook_probar/) | `POST /v1/conecta/webhooks/{id}/probar` | | [Rota el secreto de un webhook](https://docs.opennexum.com/referencia/webhooks/webhook_rotar_secreto/) | `POST /v1/conecta/webhooks/{id}/rotar-secreto` | | [Lista entregas de eventos](https://docs.opennexum.com/referencia/webhooks/entrega_listar/) | `GET /v1/conecta/entregas` | | [Reintenta una entrega](https://docs.opennexum.com/referencia/webhooks/entrega_reintentar/) | `POST /v1/conecta/entregas/{id}/reintentar` | --- Fuente: https://docs.opennexum.com/referencia/cuenta/yo_ver/ # Dice quién eres > 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. `GET /v1/yo` 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. ## Ficha | Dato | Valor | |---|---| | Permiso | `clave_valida` | | Cobro | No cobra. | | `Idempotency-Key` | No aplica | | Herramienta MCP | `yo_ver` (Próximamente) | ## Parámetros | Nombre | En | Requerido | Tipo | Descripción | |---|---|---|---|---| | `X-Request-Id` | header | No | string | Identificador de la petición. Va en cada respuesta; menciónalo al escribir a soporte. | ## Ejemplo Contra el sandbox, con una clave `onx_test_…`: ```bash curl "https://api-sandbox.opennexum.com/v1/yo" \ -H "Authorization: Bearer onx_test_…" ``` ## Respuestas ### 200 La cuenta y lo que puede hacer tu credencial. | Campo | Tipo | Requerido | Descripción | |---|---|---|---| | `cuenta` | object | Sí | La cuenta a la que pertenece la credencial. | | `cuenta.id` | string | Sí | Identificador público de tu cuenta. | | `cuenta.nombre` | string | Sí | Nombre de la cuenta. | | `entorno` | "live" \| "test" | Sí | `live` en producción; `test` en sandbox (SUNAT beta). | | `credencial` | "clave" \| "oauth" | Sí | Con qué preguntas: una clave `onx_live_`/`onx_test_` o el token OAuth de un agente conectado. | | `permisos` | "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"[] | Sí | Lo que puede hacer esta credencial. | | `emisores` | string[] \| null | Sí | RUC a los que llega: `null` = todos los de tu cuenta; una lista vacía = ninguno. | | `tope` | object \| null | Sí | Tope de gasto de la credencial; `null` si no tiene. Lo consumido está en `GET /v1/cuenta/saldo`. | | `tope.periodo` | "diario" \| "semanal" \| "mensual" \| "total" | Sí | | | `tope.limite` | string | Sí | Monto como texto con dos decimales y punto decimal, sin separador de miles. "1250.50" es S/ 1,250.50. | ### Errores Cada código tiene su explicación en [Errores](https://docs.opennexum.com/errores/). - **401** [`clave_invalida`](https://docs.opennexum.com/errores#clave_invalida) - **403** [`permiso_faltante`](https://docs.opennexum.com/errores#permiso_faltante) - **429** [`limite_uso`](https://docs.opennexum.com/errores#limite_uso) - **500** [`error_interno`](https://docs.opennexum.com/errores#error_interno) - **501** [`operacion_no_disponible`](https://docs.opennexum.com/errores#operacion_no_disponible) - **503** [`no_disponible`](https://docs.opennexum.com/errores#no_disponible) --- Fuente: https://docs.opennexum.com/referencia/cuenta/cuenta_saldo/ # Consulta tu saldo > Devuelve el saldo disponible y reservado en soles, el tope de la clave que pregunta y el enlace de recarga. `GET /v1/cuenta/saldo` Devuelve el saldo disponible y reservado en soles, el tope de la clave que pregunta y el enlace de recarga. ## Ficha | Dato | Valor | |---|---| | Permiso | `cuenta:leer` | | Cobro | No cobra. | | `Idempotency-Key` | No aplica | | Herramienta MCP | `cuenta_saldo` (Próximamente) | ## Parámetros | Nombre | En | Requerido | Tipo | Descripción | |---|---|---|---|---| | `X-Request-Id` | header | No | string | Identificador de la petición. Va en cada respuesta; menciónalo al escribir a soporte. | ## Ejemplo Contra el sandbox, con una clave `onx_test_…`: ```bash curl "https://api-sandbox.opennexum.com/v1/cuenta/saldo" \ -H "Authorization: Bearer onx_test_…" ``` ## Respuestas ### 200 Saldo de la cuenta. | Campo | Tipo | Requerido | Descripción | |---|---|---|---| | `moneda` | "PEN" | Sí | | | `disponible` | string | Sí | Lo que puedes gastar ahora. | | `reservado` | string | Sí | Separado para operaciones en curso; se cobra solo si se completan. | | `recarga_url` | string (uri) | Sí | Dónde recarga una persona de tu cuenta. | | `tope_clave` | object \| null | Sí | Tope de la clave con la que preguntas; `null` si no tiene. | | `tope_clave.periodo` | "diario" \| "semanal" \| "mensual" \| "total" | Sí | | | `tope_clave.limite` | string | Sí | Monto como texto con dos decimales y punto decimal, sin separador de miles. "1250.50" es S/ 1,250.50. | | `tope_clave.consumido` | string | Sí | Monto como texto con dos decimales y punto decimal, sin separador de miles. "1250.50" es S/ 1,250.50. | | `tope_clave.renueva_en` | string (date-time) \| null | Sí | Cuándo vuelve a cero lo consumido; `null` en un tope `total`. | | `actualizado_en` | string (date-time) | Sí | Fecha y hora ISO 8601 con la zona de Lima (-05:00). | ### Errores Cada código tiene su explicación en [Errores](https://docs.opennexum.com/errores/). - **401** [`clave_invalida`](https://docs.opennexum.com/errores#clave_invalida) - **403** [`permiso_faltante`](https://docs.opennexum.com/errores#permiso_faltante) - **429** [`limite_uso`](https://docs.opennexum.com/errores#limite_uso) - **500** [`error_interno`](https://docs.opennexum.com/errores#error_interno) - **501** [`operacion_no_disponible`](https://docs.opennexum.com/errores#operacion_no_disponible) - **503** [`no_disponible`](https://docs.opennexum.com/errores#no_disponible) --- Fuente: https://docs.opennexum.com/referencia/cuenta/cuenta_consumo/ # Lista tu consumo > 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. `GET /v1/cuenta/consumo` 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. ## Ficha | Dato | Valor | |---|---| | Permiso | `cuenta:leer` | | Cobro | No cobra. | | `Idempotency-Key` | No aplica | | Herramienta MCP | `cuenta_consumo` (Próximamente) | ## Parámetros | Nombre | En | Requerido | Tipo | Descripción | |---|---|---|---|---| | `cursor` | query | No | string | Cursor opaco que devolvió la página anterior en `siguiente_cursor`. | | `limite` | query | No | integer | Cuántos elementos traer (1 a 100; por defecto 20). | | `desde` | query | No | string | Desde este día (incluido). Si no lo envías, desde el día 1 del mes de `hasta`. | | `hasta` | query | No | string | Hasta este día (incluido). Si no lo envías, hoy en Lima. | | `servicio` | query | No | string | Solo el consumo de ese servicio (deja fuera las recargas). | | `clave_id` | query | No | string | Solo lo gastado con esta clave (deja fuera las recargas). | | `X-Request-Id` | header | No | string | Identificador de la petición. Va en cada respuesta; menciónalo al escribir a soporte. | ## Ejemplo Contra el sandbox, con una clave `onx_test_…`: ```bash curl "https://api-sandbox.opennexum.com/v1/cuenta/consumo" \ -H "Authorization: Bearer onx_test_…" ``` ## Respuestas ### 200 Página de movimientos con el gasto por clave. | Campo | Tipo | Requerido | Descripción | |---|---|---|---| | `elementos` | object[] | Sí | | | `elementos[].id` | string | Sí | Identificador que empieza con `mov_`. | | `elementos[].tipo` | "consumo" \| "recarga" | Sí | `consumo`: lo que gastó una clave; `recarga`: saldo que sumaste. | | `elementos[].fecha` | string (date-time) | Sí | Fecha y hora ISO 8601 con la zona de Lima (-05:00). | | `elementos[].servicio` | "datos" \| "comprobantes" \| "conecta" \| null | Sí | Servicio del consumo; `null` en una recarga. | | `elementos[].operacion` | string | Sí | operationId de la ruta, por ejemplo `comprobante_emitir` o `recarga_crear`. | | `elementos[].monto` | string | Sí | Monto como texto con dos decimales y punto decimal, sin separador de miles. "1250.50" es S/ 1,250.50. | | `elementos[].moneda` | "PEN" | Sí | | | `elementos[].estado` | "reservado" \| "cobrado" \| "liberado" \| "acreditado" | Sí | Consumo: reservado mientras se completa, cobrado al confirmarse, liberado si falló o venció. Recarga: acreditado. | | `elementos[].clave_id` | string \| null | Sí | Clave (o agente conectado) que gastó; `null` en una recarga. | | `elementos[].request_id` | string \| null | Sí | | | `elementos[].recurso` | object \| null | Sí | | | `elementos[].recurso.tipo` | "comprobante" \| "baja" \| "resumen" \| "guia" \| "sire_propuesta" \| "mensaje" \| "entrega" \| "clave" \| "conexion" \| "webhook" | Sí | | | `elementos[].recurso.id` | string | Sí | | | `siguiente_cursor` | string \| null | Sí | Pásalo como `cursor` para la página siguiente; `null` si ya no hay más. | | `periodo` | object | Sí | Días consultados, en hora de Lima. | | `periodo.desde` | string (date) | Sí | Fecha AAAA-MM-DD (día en Lima). | | `periodo.hasta` | string (date) | Sí | Fecha AAAA-MM-DD (día en Lima). | | `gasto_por_clave` | object[] | Sí | Gasto de cada clave o agente en todo el periodo (no solo en esta página), de mayor a menor. | | `gasto_por_clave[].clave_id` | string | Sí | Identificador que empieza con `clv_`. | | `gasto_por_clave[].nombre` | string | Sí | | | `gasto_por_clave[].prefijo` | string | Sí | Inicio visible de la clave; `onx__oauth` si es un agente conectado. | | `gasto_por_clave[].origen` | "clave" \| "agente_oauth" | Sí | `agente_oauth`: un agente conectado desde el panel con OAuth. | | `gasto_por_clave[].cobrado` | string | Sí | Monto como texto con dos decimales y punto decimal, sin separador de miles. "1250.50" es S/ 1,250.50. | | `gasto_por_clave[].reservado` | string | Sí | Retenido en operaciones que todavía no terminan. | | `gasto_por_clave[].operaciones` | integer | Sí | Operaciones que cobraron o reservaron saldo en el periodo. | ### Errores Cada código tiene su explicación en [Errores](https://docs.opennexum.com/errores/). - **400** [`validacion`](https://docs.opennexum.com/errores#validacion) - **401** [`clave_invalida`](https://docs.opennexum.com/errores#clave_invalida) - **403** [`permiso_faltante`](https://docs.opennexum.com/errores#permiso_faltante) - **429** [`limite_uso`](https://docs.opennexum.com/errores#limite_uso) - **500** [`error_interno`](https://docs.opennexum.com/errores#error_interno) - **501** [`operacion_no_disponible`](https://docs.opennexum.com/errores#operacion_no_disponible) - **503** [`no_disponible`](https://docs.opennexum.com/errores#no_disponible) --- Fuente: https://docs.opennexum.com/referencia/cuenta/recarga_crear/ # Declara una recarga por Yape o Plin > 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. `POST /v1/cuenta/recargas` 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. ## Ficha | Dato | Valor | |---|---| | Permiso | `cuenta:recargar` | | Cobro | No cobra. | | `Idempotency-Key` | Obligatoria | | Herramienta MCP | No se ofrece a agentes. | ## Parámetros | Nombre | En | Requerido | Tipo | Descripción | |---|---|---|---|---| | `Idempotency-Key` | header | Sí | string | 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. | | `X-Request-Id` | header | No | string | Identificador de la petición. Va en cada respuesta; menciónalo al escribir a soporte. | ## Cuerpo `application/json`, obligatorio. Los campos anidados van con punto y los de listas con `[]`. No se aceptan campos desconocidos. | Campo | Tipo | Requerido | Descripción | |---|---|---|---| | `monto` | string | Sí | Lo que pagaste. Hay un monto mínimo (S/ 20.00 por omisión). | | `metodo` | "yape" \| "plin" | Sí | | | `numero_operacion` | string | Sí | Número de operación del pago, como lo muestra la app de Yape o Plin. | | `fecha_pago` | string (date) | Sí | 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. | | `voucher` | object | Sí | Captura del pago en base64 (JPG, PNG o WEBP de hasta 5 MB). Revisamos el contenido real del archivo. | | `voucher.tipo` | "image/jpeg" \| "image/png" \| "image/webp" | Sí | Formato del archivo: JPG, PNG o WEBP. | | `voucher.contenido_base64` | string | Sí | | | `ruc_factura` | string | No | RUC para la factura de la recarga; si no lo envías, usamos el de tu cuenta. | ## Ejemplo Contra el sandbox, con una clave `onx_test_…`: ```bash curl -X POST "https://api-sandbox.opennexum.com/v1/cuenta/recargas" \ -H "Authorization: Bearer onx_test_…" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "monto": "1250.50", "metodo": "yape", "numero_operacion": "01234567", "fecha_pago": "2026-11-15", "voucher": { "tipo": "image/jpeg", "contenido_base64": "texto" } }' ``` ## Respuestas ### 201 Recarga registrada, en revisión. | Campo | Tipo | Requerido | Descripción | |---|---|---|---| | `id` | string | Sí | Identificador que empieza con `rec_`. | | `estado` | "en_revision" \| "acreditada" \| "rechazada" | Sí | `en_revision` hasta que una persona revisa el voucher; luego `acreditada` o `rechazada` (con motivo). | | `monto` | string | Sí | Monto como texto con dos decimales y punto decimal, sin separador de miles. "1250.50" es S/ 1,250.50. | | `moneda` | "PEN" | Sí | | | `metodo` | "yape" \| "plin" | Sí | | | `numero_operacion` | string | Sí | | | `fecha_pago` | string (date) | Sí | Fecha AAAA-MM-DD (día en Lima). | | `ruc_factura` | string \| null | Sí | | | `motivo_rechazo` | string \| null | Sí | Por qué se rechazó; `null` si no se rechazó. | | `creada_en` | string (date-time) | Sí | Fecha y hora ISO 8601 con la zona de Lima (-05:00). | | `revisada_en` | string (date-time) \| null | Sí | | ### Errores Cada código tiene su explicación en [Errores](https://docs.opennexum.com/errores/). - **400** [`validacion`](https://docs.opennexum.com/errores#validacion) - **401** [`clave_invalida`](https://docs.opennexum.com/errores#clave_invalida) - **403** [`permiso_faltante`](https://docs.opennexum.com/errores#permiso_faltante) - **409** [`idempotencia_en_conflicto`](https://docs.opennexum.com/errores#idempotencia_en_conflicto) - **409** [`solicitud_en_curso`](https://docs.opennexum.com/errores#solicitud_en_curso) - **409** [`ya_registrado`](https://docs.opennexum.com/errores#ya_registrado) - **409** [`estado_no_permite`](https://docs.opennexum.com/errores#estado_no_permite) - **429** [`limite_uso`](https://docs.opennexum.com/errores#limite_uso) - **500** [`error_interno`](https://docs.opennexum.com/errores#error_interno) - **501** [`operacion_no_disponible`](https://docs.opennexum.com/errores#operacion_no_disponible) - **503** [`no_disponible`](https://docs.opennexum.com/errores#no_disponible) --- Fuente: https://docs.opennexum.com/referencia/cuenta/ticket_crear/ # Abre un ticket de soporte > 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. `POST /v1/soporte/tickets` 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. ## Ficha | Dato | Valor | |---|---| | Permiso | `clave_valida` | | Cobro | No cobra. | | `Idempotency-Key` | Opcional | | Herramienta MCP | `ticket_crear` (Próximamente) | ## Parámetros | Nombre | En | Requerido | Tipo | Descripción | |---|---|---|---|---| | `Idempotency-Key` | header | No | string | 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. | | `X-Request-Id` | header | No | string | Identificador de la petición. Va en cada respuesta; menciónalo al escribir a soporte. | ## Cuerpo `application/json`, obligatorio. Los campos anidados van con punto y los de listas con `[]`. No se aceptan campos desconocidos. | Campo | Tipo | Requerido | Descripción | |---|---|---|---| | `asunto` | string | Sí | Qué pasa, en una línea. | | `texto` | string | Sí | Detalle: qué hiciste, qué esperabas y qué pasó, con el `request_id` si lo tienes. Nunca pegues claves ni contraseñas. | | `categoria` | "soporte" \| "mejora" \| "facturacion" \| "seguridad" | No | Si no la envías, `soporte`. | ## Ejemplo Contra el sandbox, con una clave `onx_test_…`: ```bash curl -X POST "https://api-sandbox.opennexum.com/v1/soporte/tickets" \ -H "Authorization: Bearer onx_test_…" \ -H "Content-Type: application/json" \ -d '{ "asunto": "texto", "texto": "texto" }' ``` ## Respuestas ### 201 Ticket abierto. | Campo | Tipo | Requerido | Descripción | |---|---|---|---| | `id` | string | Sí | Identificador que empieza con `tkt_`. | | `asunto` | string | Sí | | | `categoria` | "soporte" \| "mejora" \| "facturacion" \| "seguridad" | Sí | `soporte`: algo no funciona · `mejora`: una idea · `facturacion`: saldo o facturas · `seguridad`: un riesgo. | | `estado` | "abierto" \| "en_revision" \| "respondido" \| "escalado" \| "cerrado" | Sí | `abierto` espera respuesta; `respondido` espera la tuya; `cerrado` ya no recibe mensajes. | | `creado_en` | string (date-time) | Sí | Fecha y hora ISO 8601 con la zona de Lima (-05:00). | | `actualizado_en` | string (date-time) | Sí | Fecha y hora ISO 8601 con la zona de Lima (-05:00). | | `cerrado_en` | string (date-time) \| null | Sí | | | `mensajes` | object[] | Sí | Del más antiguo al más nuevo. | | `mensajes[].id` | string | Sí | Identificador que empieza con `tkm_`. | | `mensajes[].autor` | "cliente" \| "soporte" \| "claude" | Sí | `cliente`: tú; `soporte`: una persona de OpenNexum; `claude`: el asistente de soporte. | | `mensajes[].texto` | string | Sí | | | `mensajes[].creado_en` | string (date-time) | Sí | Fecha y hora ISO 8601 con la zona de Lima (-05:00). | ### Errores Cada código tiene su explicación en [Errores](https://docs.opennexum.com/errores/). - **400** [`validacion`](https://docs.opennexum.com/errores#validacion) - **401** [`clave_invalida`](https://docs.opennexum.com/errores#clave_invalida) - **403** [`permiso_faltante`](https://docs.opennexum.com/errores#permiso_faltante) - **409** [`idempotencia_en_conflicto`](https://docs.opennexum.com/errores#idempotencia_en_conflicto) - **409** [`solicitud_en_curso`](https://docs.opennexum.com/errores#solicitud_en_curso) - **429** [`limite_uso`](https://docs.opennexum.com/errores#limite_uso) - **500** [`error_interno`](https://docs.opennexum.com/errores#error_interno) - **501** [`operacion_no_disponible`](https://docs.opennexum.com/errores#operacion_no_disponible) - **503** [`no_disponible`](https://docs.opennexum.com/errores#no_disponible) --- Fuente: https://docs.opennexum.com/referencia/cuenta/ticket_listar/ # Lista tus tickets de soporte > Tickets que abrió esta clave, del más reciente al más antiguo, sin sus mensajes. `GET /v1/soporte/tickets` Tickets que abrió esta clave, del más reciente al más antiguo, sin sus mensajes. ## Ficha | Dato | Valor | |---|---| | Permiso | `clave_valida` | | Cobro | No cobra. | | `Idempotency-Key` | No aplica | | Herramienta MCP | No se ofrece a agentes. | ## Parámetros | Nombre | En | Requerido | Tipo | Descripción | |---|---|---|---|---| | `cursor` | query | No | string | Cursor opaco que devolvió la página anterior en `siguiente_cursor`. | | `limite` | query | No | integer | Cuántos elementos traer (1 a 100; por defecto 20). | | `estado` | query | No | string | Solo los tickets en ese estado. | | `X-Request-Id` | header | No | string | Identificador de la petición. Va en cada respuesta; menciónalo al escribir a soporte. | ## Ejemplo Contra el sandbox, con una clave `onx_test_…`: ```bash curl "https://api-sandbox.opennexum.com/v1/soporte/tickets" \ -H "Authorization: Bearer onx_test_…" ``` ## Respuestas ### 200 Página de tickets. | Campo | Tipo | Requerido | Descripción | |---|---|---|---| | `elementos` | object[] | Sí | | | `elementos[].id` | string | Sí | Identificador que empieza con `tkt_`. | | `elementos[].asunto` | string | Sí | | | `elementos[].categoria` | "soporte" \| "mejora" \| "facturacion" \| "seguridad" | Sí | `soporte`: algo no funciona · `mejora`: una idea · `facturacion`: saldo o facturas · `seguridad`: un riesgo. | | `elementos[].estado` | "abierto" \| "en_revision" \| "respondido" \| "escalado" \| "cerrado" | Sí | `abierto` espera respuesta; `respondido` espera la tuya; `cerrado` ya no recibe mensajes. | | `elementos[].creado_en` | string (date-time) | Sí | Fecha y hora ISO 8601 con la zona de Lima (-05:00). | | `elementos[].actualizado_en` | string (date-time) | Sí | Fecha y hora ISO 8601 con la zona de Lima (-05:00). | | `elementos[].cerrado_en` | string (date-time) \| null | Sí | | | `siguiente_cursor` | string \| null | Sí | Pásalo como `cursor` para la página siguiente; `null` si ya no hay más. | ### Errores Cada código tiene su explicación en [Errores](https://docs.opennexum.com/errores/). - **400** [`validacion`](https://docs.opennexum.com/errores#validacion) - **401** [`clave_invalida`](https://docs.opennexum.com/errores#clave_invalida) - **403** [`permiso_faltante`](https://docs.opennexum.com/errores#permiso_faltante) - **429** [`limite_uso`](https://docs.opennexum.com/errores#limite_uso) - **500** [`error_interno`](https://docs.opennexum.com/errores#error_interno) - **501** [`operacion_no_disponible`](https://docs.opennexum.com/errores#operacion_no_disponible) - **503** [`no_disponible`](https://docs.opennexum.com/errores#no_disponible) --- Fuente: https://docs.opennexum.com/referencia/cuenta/ticket_ver/ # Consulta un ticket de soporte > Un ticket que abrió esta clave, con todos sus mensajes y su estado. Úsalo para ver si ya te respondimos. `GET /v1/soporte/tickets/{id}` Un ticket que abrió esta clave, con todos sus mensajes y su estado. Úsalo para ver si ya te respondimos. ## Ficha | Dato | Valor | |---|---| | Permiso | `clave_valida` | | Cobro | No cobra. | | `Idempotency-Key` | No aplica | | Herramienta MCP | `ticket_ver` (Próximamente) | ## Parámetros | Nombre | En | Requerido | Tipo | Descripción | |---|---|---|---|---| | `id` | path | Sí | string | Identificador que empieza con `tkt_`. | | `X-Request-Id` | header | No | string | Identificador de la petición. Va en cada respuesta; menciónalo al escribir a soporte. | ## Ejemplo Contra el sandbox, con una clave `onx_test_…`: ```bash curl "https://api-sandbox.opennexum.com/v1/soporte/tickets/tkt_8f2c1a7d9e" \ -H "Authorization: Bearer onx_test_…" ``` ## Respuestas ### 200 Ticket con sus mensajes. | Campo | Tipo | Requerido | Descripción | |---|---|---|---| | `id` | string | Sí | Identificador que empieza con `tkt_`. | | `asunto` | string | Sí | | | `categoria` | "soporte" \| "mejora" \| "facturacion" \| "seguridad" | Sí | `soporte`: algo no funciona · `mejora`: una idea · `facturacion`: saldo o facturas · `seguridad`: un riesgo. | | `estado` | "abierto" \| "en_revision" \| "respondido" \| "escalado" \| "cerrado" | Sí | `abierto` espera respuesta; `respondido` espera la tuya; `cerrado` ya no recibe mensajes. | | `creado_en` | string (date-time) | Sí | Fecha y hora ISO 8601 con la zona de Lima (-05:00). | | `actualizado_en` | string (date-time) | Sí | Fecha y hora ISO 8601 con la zona de Lima (-05:00). | | `cerrado_en` | string (date-time) \| null | Sí | | | `mensajes` | object[] | Sí | Del más antiguo al más nuevo. | | `mensajes[].id` | string | Sí | Identificador que empieza con `tkm_`. | | `mensajes[].autor` | "cliente" \| "soporte" \| "claude" | Sí | `cliente`: tú; `soporte`: una persona de OpenNexum; `claude`: el asistente de soporte. | | `mensajes[].texto` | string | Sí | | | `mensajes[].creado_en` | string (date-time) | Sí | Fecha y hora ISO 8601 con la zona de Lima (-05:00). | ### Errores Cada código tiene su explicación en [Errores](https://docs.opennexum.com/errores/). - **400** [`validacion`](https://docs.opennexum.com/errores#validacion) - **401** [`clave_invalida`](https://docs.opennexum.com/errores#clave_invalida) - **403** [`permiso_faltante`](https://docs.opennexum.com/errores#permiso_faltante) - **404** [`no_encontrado`](https://docs.opennexum.com/errores#no_encontrado) - **429** [`limite_uso`](https://docs.opennexum.com/errores#limite_uso) - **500** [`error_interno`](https://docs.opennexum.com/errores#error_interno) - **501** [`operacion_no_disponible`](https://docs.opennexum.com/errores#operacion_no_disponible) - **503** [`no_disponible`](https://docs.opennexum.com/errores#no_disponible) --- Fuente: https://docs.opennexum.com/referencia/cuenta/ticket_responder/ # Responde en un ticket de soporte > Agrega tu mensaje a un ticket que abrió esta clave. Un ticket cerrado no recibe mensajes: abre otro. `POST /v1/soporte/tickets/{id}/mensajes` Agrega tu mensaje a un ticket que abrió esta clave. Un ticket cerrado no recibe mensajes: abre otro. ## Ficha | Dato | Valor | |---|---| | Permiso | `clave_valida` | | Cobro | No cobra. | | `Idempotency-Key` | Opcional | | Herramienta MCP | No se ofrece a agentes. | ## Parámetros | Nombre | En | Requerido | Tipo | Descripción | |---|---|---|---|---| | `id` | path | Sí | string | Identificador que empieza con `tkt_`. | | `Idempotency-Key` | header | No | string | 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. | | `X-Request-Id` | header | No | string | Identificador de la petición. Va en cada respuesta; menciónalo al escribir a soporte. | ## Cuerpo `application/json`, obligatorio. Los campos anidados van con punto y los de listas con `[]`. No se aceptan campos desconocidos. | Campo | Tipo | Requerido | Descripción | |---|---|---|---| | `texto` | string | Sí | | ## Ejemplo Contra el sandbox, con una clave `onx_test_…`: ```bash curl -X POST "https://api-sandbox.opennexum.com/v1/soporte/tickets/tkt_8f2c1a7d9e/mensajes" \ -H "Authorization: Bearer onx_test_…" \ -H "Content-Type: application/json" \ -d '{ "texto": "texto" }' ``` ## Respuestas ### 201 Mensaje agregado; el ticket vuelve a esperar nuestra respuesta. | Campo | Tipo | Requerido | Descripción | |---|---|---|---| | `id` | string | Sí | Identificador que empieza con `tkt_`. | | `asunto` | string | Sí | | | `categoria` | "soporte" \| "mejora" \| "facturacion" \| "seguridad" | Sí | `soporte`: algo no funciona · `mejora`: una idea · `facturacion`: saldo o facturas · `seguridad`: un riesgo. | | `estado` | "abierto" \| "en_revision" \| "respondido" \| "escalado" \| "cerrado" | Sí | `abierto` espera respuesta; `respondido` espera la tuya; `cerrado` ya no recibe mensajes. | | `creado_en` | string (date-time) | Sí | Fecha y hora ISO 8601 con la zona de Lima (-05:00). | | `actualizado_en` | string (date-time) | Sí | Fecha y hora ISO 8601 con la zona de Lima (-05:00). | | `cerrado_en` | string (date-time) \| null | Sí | | | `mensajes` | object[] | Sí | Del más antiguo al más nuevo. | | `mensajes[].id` | string | Sí | Identificador que empieza con `tkm_`. | | `mensajes[].autor` | "cliente" \| "soporte" \| "claude" | Sí | `cliente`: tú; `soporte`: una persona de OpenNexum; `claude`: el asistente de soporte. | | `mensajes[].texto` | string | Sí | | | `mensajes[].creado_en` | string (date-time) | Sí | Fecha y hora ISO 8601 con la zona de Lima (-05:00). | ### Errores Cada código tiene su explicación en [Errores](https://docs.opennexum.com/errores/). - **400** [`validacion`](https://docs.opennexum.com/errores#validacion) - **401** [`clave_invalida`](https://docs.opennexum.com/errores#clave_invalida) - **403** [`permiso_faltante`](https://docs.opennexum.com/errores#permiso_faltante) - **404** [`no_encontrado`](https://docs.opennexum.com/errores#no_encontrado) - **409** [`idempotencia_en_conflicto`](https://docs.opennexum.com/errores#idempotencia_en_conflicto) - **409** [`solicitud_en_curso`](https://docs.opennexum.com/errores#solicitud_en_curso) - **409** [`estado_no_permite`](https://docs.opennexum.com/errores#estado_no_permite) - **429** [`limite_uso`](https://docs.opennexum.com/errores#limite_uso) - **500** [`error_interno`](https://docs.opennexum.com/errores#error_interno) - **501** [`operacion_no_disponible`](https://docs.opennexum.com/errores#operacion_no_disponible) - **503** [`no_disponible`](https://docs.opennexum.com/errores#no_disponible) --- Fuente: https://docs.opennexum.com/referencia/cuenta/ticket_cerrar/ # Cierra un ticket de soporte > Cierra un ticket que abrió esta clave cuando ya no necesitas ayuda. Cerrar uno ya cerrado no cambia nada. `POST /v1/soporte/tickets/{id}/cerrar` Cierra un ticket que abrió esta clave cuando ya no necesitas ayuda. Cerrar uno ya cerrado no cambia nada. ## Ficha | Dato | Valor | |---|---| | Permiso | `clave_valida` | | Cobro | No cobra. | | `Idempotency-Key` | Opcional | | Herramienta MCP | No se ofrece a agentes. | ## Parámetros | Nombre | En | Requerido | Tipo | Descripción | |---|---|---|---|---| | `id` | path | Sí | string | Identificador que empieza con `tkt_`. | | `Idempotency-Key` | header | No | string | 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. | | `X-Request-Id` | header | No | string | Identificador de la petición. Va en cada respuesta; menciónalo al escribir a soporte. | ## Ejemplo Contra el sandbox, con una clave `onx_test_…`: ```bash curl -X POST "https://api-sandbox.opennexum.com/v1/soporte/tickets/tkt_8f2c1a7d9e/cerrar" \ -H "Authorization: Bearer onx_test_…" ``` ## Respuestas ### 200 Ticket cerrado. | Campo | Tipo | Requerido | Descripción | |---|---|---|---| | `id` | string | Sí | Identificador que empieza con `tkt_`. | | `asunto` | string | Sí | | | `categoria` | "soporte" \| "mejora" \| "facturacion" \| "seguridad" | Sí | `soporte`: algo no funciona · `mejora`: una idea · `facturacion`: saldo o facturas · `seguridad`: un riesgo. | | `estado` | "abierto" \| "en_revision" \| "respondido" \| "escalado" \| "cerrado" | Sí | `abierto` espera respuesta; `respondido` espera la tuya; `cerrado` ya no recibe mensajes. | | `creado_en` | string (date-time) | Sí | Fecha y hora ISO 8601 con la zona de Lima (-05:00). | | `actualizado_en` | string (date-time) | Sí | Fecha y hora ISO 8601 con la zona de Lima (-05:00). | | `cerrado_en` | string (date-time) \| null | Sí | | ### Errores Cada código tiene su explicación en [Errores](https://docs.opennexum.com/errores/). - **400** [`validacion`](https://docs.opennexum.com/errores#validacion) - **401** [`clave_invalida`](https://docs.opennexum.com/errores#clave_invalida) - **403** [`permiso_faltante`](https://docs.opennexum.com/errores#permiso_faltante) - **404** [`no_encontrado`](https://docs.opennexum.com/errores#no_encontrado) - **409** [`idempotencia_en_conflicto`](https://docs.opennexum.com/errores#idempotencia_en_conflicto) - **409** [`solicitud_en_curso`](https://docs.opennexum.com/errores#solicitud_en_curso) - **429** [`limite_uso`](https://docs.opennexum.com/errores#limite_uso) - **500** [`error_interno`](https://docs.opennexum.com/errores#error_interno) - **501** [`operacion_no_disponible`](https://docs.opennexum.com/errores#operacion_no_disponible) - **503** [`no_disponible`](https://docs.opennexum.com/errores#no_disponible) --- Fuente: https://docs.opennexum.com/referencia/claves/clave_listar/ # Lista las claves de tu cuenta > 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. `GET /v1/claves` 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. ## Ficha | Dato | Valor | |---|---| | Permiso | `claves:administrar` | | Cobro | No cobra. | | `Idempotency-Key` | No aplica | | Herramienta MCP | `clave_listar` (Próximamente) | ## Parámetros | Nombre | En | Requerido | Tipo | Descripción | |---|---|---|---|---| | `cursor` | query | No | string | Cursor opaco que devolvió la página anterior en `siguiente_cursor`. | | `limite` | query | No | integer | Cuántos elementos traer (1 a 100; por defecto 20). | | `X-Request-Id` | header | No | string | Identificador de la petición. Va en cada respuesta; menciónalo al escribir a soporte. | ## Ejemplo Contra el sandbox, con una clave `onx_test_…`: ```bash curl "https://api-sandbox.opennexum.com/v1/claves" \ -H "Authorization: Bearer onx_test_…" ``` ## Respuestas ### 200 Página de claves. | Campo | Tipo | Requerido | Descripción | |---|---|---|---| | `elementos` | object[] | Sí | | | `elementos[].id` | string | Sí | Identificador que empieza con `clv_`. | | `elementos[].nombre` | string | Sí | | | `elementos[].prefijo` | string | Sí | Inicio visible de la clave, para reconocerla. La clave completa solo se muestra al crearla. | | `elementos[].entorno` | "live" \| "test" | Sí | `live` en producción; `test` en sandbox (SUNAT beta). | | `elementos[].permisos` | "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"[] | Sí | Puede estar vacía (una clave sin permisos solo autentica). | | `elementos[].emisores` | string[] \| null | Sí | RUC a los que puede acceder; `null` = todos los de tu cuenta. | | `elementos[].tope` | object \| null | Sí | | | `elementos[].tope.periodo` | "diario" \| "semanal" \| "mensual" \| "total" | Sí | | | `elementos[].tope.limite` | string | Sí | Monto como texto con dos decimales y punto decimal, sin separador de miles. "1250.50" es S/ 1,250.50. | | `elementos[].confirmacion` | object | Sí | Qué operaciones de esta clave esperan la aprobación de una persona en el panel. | | `elementos[].confirmacion.notas` | boolean | Sí | Notas de crédito y débito. | | `elementos[].confirmacion.bajas` | boolean | Sí | Bajas y anulaciones. | | `elementos[].confirmacion.mensajes` | boolean | Sí | Envío de mensajes y comprobantes por Conecta. | | `elementos[].confirmacion.monto_desde` | string \| null | Sí | Comprobantes desde este total; `null` para no pedirla por monto. | | `elementos[].vence_el` | string (date) \| null | Sí | | | `elementos[].ultimo_uso_en` | string (date-time) \| null | Sí | | | `elementos[].creada_en` | string (date-time) | Sí | Fecha y hora ISO 8601 con la zona de Lima (-05:00). | | `elementos[].revocada_en` | string (date-time) \| null | Sí | | | `siguiente_cursor` | string \| null | Sí | Pásalo como `cursor` para la página siguiente; `null` si ya no hay más. | ### Errores Cada código tiene su explicación en [Errores](https://docs.opennexum.com/errores/). - **400** [`validacion`](https://docs.opennexum.com/errores#validacion) - **401** [`clave_invalida`](https://docs.opennexum.com/errores#clave_invalida) - **403** [`permiso_faltante`](https://docs.opennexum.com/errores#permiso_faltante) - **429** [`limite_uso`](https://docs.opennexum.com/errores#limite_uso) - **500** [`error_interno`](https://docs.opennexum.com/errores#error_interno) - **501** [`operacion_no_disponible`](https://docs.opennexum.com/errores#operacion_no_disponible) - **503** [`no_disponible`](https://docs.opennexum.com/errores#no_disponible) --- Fuente: https://docs.opennexum.com/referencia/claves/clave_crear/ # Crea una clave con tope y permisos > 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`. `POST /v1/claves` 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`. ## Ficha | Dato | Valor | |---|---| | Permiso | `claves:administrar` | | Cobro | No cobra. | | `Idempotency-Key` | Obligatoria | | Aprobación humana | Siempre: una persona la aprueba en el panel, sin importar la configuración de la clave. | | Herramienta MCP | No se ofrece a agentes. | ## Parámetros | Nombre | En | Requerido | Tipo | Descripción | |---|---|---|---|---| | `Idempotency-Key` | header | Sí | string | 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. | | `X-Request-Id` | header | No | string | Identificador de la petición. Va en cada respuesta; menciónalo al escribir a soporte. | ## Cuerpo `application/json`, obligatorio. Los campos anidados van con punto y los de listas con `[]`. No se aceptan campos desconocidos. | Campo | Tipo | Requerido | Descripción | |---|---|---|---| | `nombre` | string | Sí | Para reconocerla, por ejemplo «Agente de facturación». | | `permisos` | "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"[] | Sí | Solo puedes dar permisos que tu propia clave ya tiene. | | `emisores` | string[] | No | Limita la clave a estos RUC (dentro del alcance de tu clave); si no lo envías, hereda el de tu clave. | | `tope` | object | Sí | No puede superar el tope de la clave que la crea. | | `tope.periodo` | "diario" \| "semanal" \| "mensual" \| "total" | Sí | | | `tope.limite` | string | Sí | Monto como texto con dos decimales y punto decimal, sin separador de miles. "1250.50" es S/ 1,250.50. | | `confirmacion` | object | No | 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). | | `confirmacion.notas` | boolean | No | Notas de crédito y débito. | | `confirmacion.bajas` | boolean | No | Bajas y anulaciones. | | `confirmacion.mensajes` | boolean | No | Envío de mensajes y comprobantes por Conecta. | | `confirmacion.monto_desde` | string \| null | No | Comprobantes desde este total; `null` para no pedirla por monto. | | `vence_el` | string (date) | No | Día en que deja de funcionar; no puede ser posterior al de tu clave. | ## Ejemplo Contra el sandbox, con una clave `onx_test_…`: ```bash curl -X POST "https://api-sandbox.opennexum.com/v1/claves" \ -H "Authorization: Bearer onx_test_…" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "nombre": "texto", "permisos": [ "datos:leer" ], "tope": { "periodo": "diario", "limite": "1250.50" } }' ``` ## Respuestas ### 201 Clave creada; guarda `secreto` ahora. | Campo | Tipo | Requerido | Descripción | |---|---|---|---| | `clave` | object | Sí | Clave de API para un agente o sistema. Se guarda solo su hash. | | `clave.id` | string | Sí | Identificador que empieza con `clv_`. | | `clave.nombre` | string | Sí | | | `clave.prefijo` | string | Sí | Inicio visible de la clave, para reconocerla. La clave completa solo se muestra al crearla. | | `clave.entorno` | "live" \| "test" | Sí | `live` en producción; `test` en sandbox (SUNAT beta). | | `clave.permisos` | "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"[] | Sí | Puede estar vacía (una clave sin permisos solo autentica). | | `clave.emisores` | string[] \| null | Sí | RUC a los que puede acceder; `null` = todos los de tu cuenta. | | `clave.tope` | object \| null | Sí | | | `clave.tope.periodo` | "diario" \| "semanal" \| "mensual" \| "total" | Sí | | | `clave.tope.limite` | string | Sí | Monto como texto con dos decimales y punto decimal, sin separador de miles. "1250.50" es S/ 1,250.50. | | `clave.confirmacion` | object | Sí | Qué operaciones de esta clave esperan la aprobación de una persona en el panel. | | `clave.confirmacion.notas` | boolean | Sí | Notas de crédito y débito. | | `clave.confirmacion.bajas` | boolean | Sí | Bajas y anulaciones. | | `clave.confirmacion.mensajes` | boolean | Sí | Envío de mensajes y comprobantes por Conecta. | | `clave.confirmacion.monto_desde` | string \| null | Sí | Comprobantes desde este total; `null` para no pedirla por monto. | | `clave.vence_el` | string (date) \| null | Sí | | | `clave.ultimo_uso_en` | string (date-time) \| null | Sí | | | `clave.creada_en` | string (date-time) | Sí | Fecha y hora ISO 8601 con la zona de Lima (-05:00). | | `clave.revocada_en` | string (date-time) \| null | Sí | | | `secreto` | string | Sí | La clave completa. Se muestra solo esta vez: guárdala en un gestor de secretos. | ### 202 Espera la aprobación de una persona. | Campo | Tipo | Requerido | Descripción | |---|---|---|---| | `estado` | "requiere_confirmacion" | Sí | | | `operacion_id` | string | Sí | Úsalo en `GET /v1/confirmaciones/{id}` para saber si se aprobó. | | `confirmacion_url` | string (uri) | Sí | Enlace del panel donde una persona aprueba o rechaza. Pásaselo tal cual. | | `consulta_url` | string | Sí | Ruta para consultar el estado. | | `expira_en` | string (date-time) | Sí | Si nadie aprueba antes, la operación vence y no se hace. | | `mensaje` | string | Sí | Qué falta, en palabras para una persona. | ### Errores Cada código tiene su explicación en [Errores](https://docs.opennexum.com/errores/). - **400** [`validacion`](https://docs.opennexum.com/errores#validacion) - **401** [`clave_invalida`](https://docs.opennexum.com/errores#clave_invalida) - **403** [`permiso_faltante`](https://docs.opennexum.com/errores#permiso_faltante) - **409** [`idempotencia_en_conflicto`](https://docs.opennexum.com/errores#idempotencia_en_conflicto) - **409** [`solicitud_en_curso`](https://docs.opennexum.com/errores#solicitud_en_curso) - **409** [`ya_registrado`](https://docs.opennexum.com/errores#ya_registrado) - **409** [`estado_no_permite`](https://docs.opennexum.com/errores#estado_no_permite) - **429** [`limite_uso`](https://docs.opennexum.com/errores#limite_uso) - **500** [`error_interno`](https://docs.opennexum.com/errores#error_interno) - **501** [`operacion_no_disponible`](https://docs.opennexum.com/errores#operacion_no_disponible) - **503** [`no_disponible`](https://docs.opennexum.com/errores#no_disponible) --- Fuente: https://docs.opennexum.com/referencia/claves/clave_revocar/ # Revoca una clave > 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. `DELETE /v1/claves/{id}` 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. ## Ficha | Dato | Valor | |---|---| | Permiso | `claves:administrar` | | Cobro | No cobra. | | `Idempotency-Key` | No aplica | | Herramienta MCP | `clave_revocar` (Próximamente) | ## Parámetros | Nombre | En | Requerido | Tipo | Descripción | |---|---|---|---|---| | `id` | path | Sí | string | Identificador que empieza con `clv_`. | | `X-Request-Id` | header | No | string | Identificador de la petición. Va en cada respuesta; menciónalo al escribir a soporte. | ## Ejemplo Contra el sandbox, con una clave `onx_test_…`: ```bash curl -X DELETE "https://api-sandbox.opennexum.com/v1/claves/clv_8f2c1a7d9e" \ -H "Authorization: Bearer onx_test_…" ``` ## Respuestas ### 200 Clave revocada. | Campo | Tipo | Requerido | Descripción | |---|---|---|---| | `id` | string | Sí | Identificador que empieza con `clv_`. | | `nombre` | string | Sí | | | `prefijo` | string | Sí | Inicio visible de la clave, para reconocerla. La clave completa solo se muestra al crearla. | | `entorno` | "live" \| "test" | Sí | `live` en producción; `test` en sandbox (SUNAT beta). | | `permisos` | "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"[] | Sí | Puede estar vacía (una clave sin permisos solo autentica). | | `emisores` | string[] \| null | Sí | RUC a los que puede acceder; `null` = todos los de tu cuenta. | | `tope` | object \| null | Sí | | | `tope.periodo` | "diario" \| "semanal" \| "mensual" \| "total" | Sí | | | `tope.limite` | string | Sí | Monto como texto con dos decimales y punto decimal, sin separador de miles. "1250.50" es S/ 1,250.50. | | `confirmacion` | object | Sí | Qué operaciones de esta clave esperan la aprobación de una persona en el panel. | | `confirmacion.notas` | boolean | Sí | Notas de crédito y débito. | | `confirmacion.bajas` | boolean | Sí | Bajas y anulaciones. | | `confirmacion.mensajes` | boolean | Sí | Envío de mensajes y comprobantes por Conecta. | | `confirmacion.monto_desde` | string \| null | Sí | Comprobantes desde este total; `null` para no pedirla por monto. | | `vence_el` | string (date) \| null | Sí | | | `ultimo_uso_en` | string (date-time) \| null | Sí | | | `creada_en` | string (date-time) | Sí | Fecha y hora ISO 8601 con la zona de Lima (-05:00). | | `revocada_en` | string (date-time) \| null | Sí | | ### Errores Cada código tiene su explicación en [Errores](https://docs.opennexum.com/errores/). - **400** [`validacion`](https://docs.opennexum.com/errores#validacion) - **401** [`clave_invalida`](https://docs.opennexum.com/errores#clave_invalida) - **403** [`permiso_faltante`](https://docs.opennexum.com/errores#permiso_faltante) - **404** [`no_encontrado`](https://docs.opennexum.com/errores#no_encontrado) - **429** [`limite_uso`](https://docs.opennexum.com/errores#limite_uso) - **500** [`error_interno`](https://docs.opennexum.com/errores#error_interno) - **501** [`operacion_no_disponible`](https://docs.opennexum.com/errores#operacion_no_disponible) - **503** [`no_disponible`](https://docs.opennexum.com/errores#no_disponible) --- Fuente: https://docs.opennexum.com/referencia/confirmaciones/confirmacion_ver/ # Consulta una aprobación pendiente > Estado de una operación que respondió 202 `requiere_confirmacion`. Basta una clave válida, pero solo la ve la clave que la pidió. Cuando está `ejecutada`, `resultado` dice qué se creó. `GET /v1/confirmaciones/{id}` Estado de una operación que respondió 202 `requiere_confirmacion`. Basta una clave válida, pero solo la ve la clave que la pidió. Cuando está `ejecutada`, `resultado` dice qué se creó. ## Ficha | Dato | Valor | |---|---| | Permiso | `clave_valida` | | Cobro | No cobra. | | `Idempotency-Key` | No aplica | | Herramienta MCP | `confirmacion_ver` (Próximamente) | ## Parámetros | Nombre | En | Requerido | Tipo | Descripción | |---|---|---|---|---| | `id` | path | Sí | string | Identificador que empieza con `op_`. | | `X-Request-Id` | header | No | string | Identificador de la petición. Va en cada respuesta; menciónalo al escribir a soporte. | ## Ejemplo Contra el sandbox, con una clave `onx_test_…`: ```bash curl "https://api-sandbox.opennexum.com/v1/confirmaciones/op_8f2c1a7d9e" \ -H "Authorization: Bearer onx_test_…" ``` ## Respuestas ### 200 Estado de la aprobación. | Campo | Tipo | Requerido | Descripción | |---|---|---|---| | `id` | string | Sí | Identificador que empieza con `op_`. | | `estado` | "pendiente" \| "aprobada" \| "rechazada" \| "vencida" \| "ejecutada" \| "fallida" | Sí | `ejecutada`: se aprobó y la operación ya corrió; mira `resultado`. | | `operacion` | string | Sí | operationId de la ruta que pidió aprobación. | | `resumen` | string | Sí | Lo que se aprueba, en palabras para una persona. | | `confirmacion_url` | string (uri) | Sí | URL pública con https (sin IP literal, localhost, dominios internos ni usuario y clave). | | `creada_en` | string (date-time) | Sí | Fecha y hora ISO 8601 con la zona de Lima (-05:00). | | `expira_en` | string (date-time) | Sí | Fecha y hora ISO 8601 con la zona de Lima (-05:00). | | `decidida_en` | string (date-time) \| null | Sí | | | `resultado` | object \| null | Sí | Resultado de la operación una vez ejecutada. | | `resultado.estado_http` | integer | Sí | | | `resultado.recurso` | object \| null | Sí | | | `resultado.recurso.tipo` | "comprobante" \| "baja" \| "resumen" \| "guia" \| "sire_propuesta" \| "mensaje" \| "entrega" \| "clave" \| "conexion" \| "webhook" | Sí | | | `resultado.recurso.id` | string | Sí | | | `resultado.error` | object \| null | Sí | | | `resultado.error.codigo` | "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" | Sí | | | `resultado.error.mensaje` | string | Sí | | ### Errores Cada código tiene su explicación en [Errores](https://docs.opennexum.com/errores/). - **400** [`validacion`](https://docs.opennexum.com/errores#validacion) - **401** [`clave_invalida`](https://docs.opennexum.com/errores#clave_invalida) - **403** [`permiso_faltante`](https://docs.opennexum.com/errores#permiso_faltante) - **404** [`no_encontrado`](https://docs.opennexum.com/errores#no_encontrado) - **429** [`limite_uso`](https://docs.opennexum.com/errores#limite_uso) - **500** [`error_interno`](https://docs.opennexum.com/errores#error_interno) - **501** [`operacion_no_disponible`](https://docs.opennexum.com/errores#operacion_no_disponible) - **503** [`no_disponible`](https://docs.opennexum.com/errores#no_disponible) --- Fuente: https://docs.opennexum.com/referencia/datos/ruc_consultar/ # Consulta un RUC > 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. `GET /v1/ruc/{ruc}` 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. ## Ficha | Dato | Valor | |---|---| | Permiso | `datos:leer` | | Cobro | Lectura medida: cuenta contra tu cupo gratis o tu saldo, y puede dar `402`. | | `Idempotency-Key` | No aplica | | Herramienta MCP | `ruc_consultar` (Próximamente) | ## Parámetros | Nombre | En | Requerido | Tipo | Descripción | |---|---|---|---|---| | `ruc` | path | Sí | string | RUC del emisor o contribuyente. | | `X-Request-Id` | header | No | string | Identificador de la petición. Va en cada respuesta; menciónalo al escribir a soporte. | ## Ejemplo Contra el sandbox, con una clave `onx_test_…`: ```bash curl "https://api-sandbox.opennexum.com/v1/ruc/20000000001" \ -H "Authorization: Bearer onx_test_…" ``` ## Respuestas ### 200 Datos del contribuyente. | Campo | Tipo | Requerido | Descripción | |---|---|---|---| | `ruc` | string | Sí | RUC de 11 dígitos. Se valida el dígito verificador (módulo 11 de SUNAT). | | `razon_social` | string | Sí | | | `estado` | string \| null | Sí | Estado en SUNAT, por ejemplo ACTIVO o BAJA DE OFICIO; null si el padrón no lo trae. | | `condicion` | string \| null | Sí | Condición de domicilio, por ejemplo HABIDO o NO HABIDO; null si el padrón no la trae. | | `ubigeo` | string \| null | Sí | | | `direccion` | string \| null | Sí | | | `departamento` | string \| null | Sí | Del ubigeo, con la tabla del INEI; null si el ubigeo no está en ella. | | `provincia` | string \| null | Sí | | | `distrito` | string \| null | Sí | | | `padron_actualizado_al` | string (date) | Sí | Fecha del padrón reducido de SUNAT que respondió. | ### Errores Cada código tiene su explicación en [Errores](https://docs.opennexum.com/errores/). - **400** [`validacion`](https://docs.opennexum.com/errores#validacion) - **401** [`clave_invalida`](https://docs.opennexum.com/errores#clave_invalida) - **402** [`saldo_insuficiente`](https://docs.opennexum.com/errores#saldo_insuficiente) - **402** [`tope_alcanzado`](https://docs.opennexum.com/errores#tope_alcanzado) - **403** [`permiso_faltante`](https://docs.opennexum.com/errores#permiso_faltante) - **404** [`no_encontrado`](https://docs.opennexum.com/errores#no_encontrado) - **429** [`limite_uso`](https://docs.opennexum.com/errores#limite_uso) - **500** [`error_interno`](https://docs.opennexum.com/errores#error_interno) - **501** [`operacion_no_disponible`](https://docs.opennexum.com/errores#operacion_no_disponible) - **503** [`no_disponible`](https://docs.opennexum.com/errores#no_disponible) --- Fuente: https://docs.opennexum.com/referencia/datos/ruc_padrones/ # Consulta los padrones de un RUC > Indica si el RUC es agente de retención, agente de percepción o buen contribuyente, según SUNAT. `GET /v1/ruc/{ruc}/padrones` Indica si el RUC es agente de retención, agente de percepción o buen contribuyente, según SUNAT. ## Ficha | Dato | Valor | |---|---| | Permiso | `datos:leer` | | Cobro | Lectura medida: cuenta contra tu cupo gratis o tu saldo, y puede dar `402`. | | `Idempotency-Key` | No aplica | | Herramienta MCP | `ruc_padrones` (Próximamente) | ## Parámetros | Nombre | En | Requerido | Tipo | Descripción | |---|---|---|---|---| | `ruc` | path | Sí | string | RUC del emisor o contribuyente. | | `X-Request-Id` | header | No | string | Identificador de la petición. Va en cada respuesta; menciónalo al escribir a soporte. | ## Ejemplo Contra el sandbox, con una clave `onx_test_…`: ```bash curl "https://api-sandbox.opennexum.com/v1/ruc/20000000001/padrones" \ -H "Authorization: Bearer onx_test_…" ``` ## Respuestas ### 200 Padrones del RUC. | Campo | Tipo | Requerido | Descripción | |---|---|---|---| | `ruc` | string | Sí | RUC de 11 dígitos. Se valida el dígito verificador (módulo 11 de SUNAT). | | `agente_retencion` | object | Sí | | | `agente_retencion.incluido` | boolean | Sí | | | `agente_retencion.desde` | string (date) \| null | Sí | Desde cuándo figura, si SUNAT lo publica. | | `agente_retencion.resolucion` | string \| null | Sí | Resolución que lo incorporó, si SUNAT la publica. | | `agente_percepcion` | object | Sí | | | `agente_percepcion.incluido` | boolean | Sí | | | `agente_percepcion.desde` | string (date) \| null | Sí | Desde cuándo figura, si SUNAT lo publica. | | `agente_percepcion.resolucion` | string \| null | Sí | Resolución que lo incorporó, si SUNAT la publica. | | `buen_contribuyente` | object | Sí | | | `buen_contribuyente.incluido` | boolean | Sí | | | `buen_contribuyente.desde` | string (date) \| null | Sí | Desde cuándo figura, si SUNAT lo publica. | | `buen_contribuyente.resolucion` | string \| null | Sí | Resolución que lo incorporó, si SUNAT la publica. | | `actualizado_al` | string (date) | Sí | Fecha de la última descarga de los padrones de SUNAT. | | `desactualizado` | boolean | Sí | `true` si la última descarga tiene más días de lo normal: tómalo con cuidado. | ### Errores Cada código tiene su explicación en [Errores](https://docs.opennexum.com/errores/). - **400** [`validacion`](https://docs.opennexum.com/errores#validacion) - **401** [`clave_invalida`](https://docs.opennexum.com/errores#clave_invalida) - **402** [`saldo_insuficiente`](https://docs.opennexum.com/errores#saldo_insuficiente) - **402** [`tope_alcanzado`](https://docs.opennexum.com/errores#tope_alcanzado) - **403** [`permiso_faltante`](https://docs.opennexum.com/errores#permiso_faltante) - **404** [`no_encontrado`](https://docs.opennexum.com/errores#no_encontrado) - **429** [`limite_uso`](https://docs.opennexum.com/errores#limite_uso) - **500** [`error_interno`](https://docs.opennexum.com/errores#error_interno) - **501** [`operacion_no_disponible`](https://docs.opennexum.com/errores#operacion_no_disponible) - **503** [`no_disponible`](https://docs.opennexum.com/errores#no_disponible) --- Fuente: https://docs.opennexum.com/referencia/datos/tipo_cambio_consultar/ # Consulta el tipo de cambio > Compra y venta oficiales del dólar para una fecha, según el BCRP. Sin fecha, el de hoy en Lima. `GET /v1/tipo-cambio` Compra y venta oficiales del dólar para una fecha, según el BCRP. Sin fecha, el de hoy en Lima. ## Ficha | Dato | Valor | |---|---| | Permiso | `datos:leer` | | Cobro | Lectura medida: cuenta contra tu cupo gratis o tu saldo, y puede dar `402`. | | `Idempotency-Key` | No aplica | | Herramienta MCP | `tipo_cambio_consultar` (Próximamente) | ## Parámetros | Nombre | En | Requerido | Tipo | Descripción | |---|---|---|---|---| | `fecha` | query | No | string | Día que quieres; si no lo envías, hoy en Lima. | | `X-Request-Id` | header | No | string | Identificador de la petición. Va en cada respuesta; menciónalo al escribir a soporte. | ## Ejemplo Contra el sandbox, con una clave `onx_test_…`: ```bash curl "https://api-sandbox.opennexum.com/v1/tipo-cambio" \ -H "Authorization: Bearer onx_test_…" ``` ## Respuestas ### 200 Tipo de cambio. | Campo | Tipo | Requerido | Descripción | |---|---|---|---| | `fecha` | string (date) | Sí | El día que pediste. | | `publicado_el` | string (date) | Sí | Día de la publicación usada; en feriados y fines de semana, la última anterior. | | `moneda` | "USD" | Sí | | | `compra` | string | Sí | Soles por dólar, con tres decimales. | | `venta` | string | Sí | Soles por dólar, con tres decimales. | | `fuente` | "BCRP" | Sí | Fuente oficial del dato. | ### Errores Cada código tiene su explicación en [Errores](https://docs.opennexum.com/errores/). - **400** [`validacion`](https://docs.opennexum.com/errores#validacion) - **401** [`clave_invalida`](https://docs.opennexum.com/errores#clave_invalida) - **402** [`saldo_insuficiente`](https://docs.opennexum.com/errores#saldo_insuficiente) - **402** [`tope_alcanzado`](https://docs.opennexum.com/errores#tope_alcanzado) - **403** [`permiso_faltante`](https://docs.opennexum.com/errores#permiso_faltante) - **404** [`no_encontrado`](https://docs.opennexum.com/errores#no_encontrado) - **429** [`limite_uso`](https://docs.opennexum.com/errores#limite_uso) - **500** [`error_interno`](https://docs.opennexum.com/errores#error_interno) - **501** [`operacion_no_disponible`](https://docs.opennexum.com/errores#operacion_no_disponible) - **503** [`no_disponible`](https://docs.opennexum.com/errores#no_disponible) --- Fuente: https://docs.opennexum.com/referencia/emisores/emisor_crear/ # Registra un RUC emisor > 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). `POST /v1/emisores` 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). ## Ficha | Dato | Valor | |---|---| | Permiso | `emisores:administrar` | | Cobro | No cobra. | | `Idempotency-Key` | Opcional | | Herramienta MCP | `emisor_crear` (Próximamente) | ## Parámetros | Nombre | En | Requerido | Tipo | Descripción | |---|---|---|---|---| | `Idempotency-Key` | header | No | string | 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. | | `X-Request-Id` | header | No | string | Identificador de la petición. Va en cada respuesta; menciónalo al escribir a soporte. | ## Cuerpo `application/json`, obligatorio. Los campos anidados van con punto y los de listas con `[]`. No se aceptan campos desconocidos. | Campo | Tipo | Requerido | Descripción | |---|---|---|---| | `ruc` | string | Sí | RUC de 11 dígitos. Se valida el dígito verificador (módulo 11 de SUNAT). | | `nombre_comercial` | string | No | | | `direccion_fiscal` | object | No | Si no la envías, usamos la del padrón de SUNAT. | | `direccion_fiscal.ubigeo` | string | Sí | Ubigeo INEI de 6 dígitos. | | `direccion_fiscal.direccion` | string | Sí | | | `direccion_fiscal.codigo_establecimiento` | string | No | Código de establecimiento anexo en SUNAT; 0000 es el domicilio fiscal. | ## Ejemplo Contra el sandbox, con una clave `onx_test_…`: ```bash curl -X POST "https://api-sandbox.opennexum.com/v1/emisores" \ -H "Authorization: Bearer onx_test_…" \ -H "Content-Type: application/json" \ -d '{ "ruc": "20000000001" }' ``` ## Respuestas ### 201 Emisor registrado. | Campo | Tipo | Requerido | Descripción | |---|---|---|---| | `ruc` | string | Sí | RUC de 11 dígitos. Se valida el dígito verificador (módulo 11 de SUNAT). | | `razon_social` | string | Sí | | | `nombre_comercial` | string \| null | Sí | | | `direccion_fiscal` | object \| null | Sí | | | `direccion_fiscal.ubigeo` | string | Sí | Ubigeo INEI de 6 dígitos. | | `direccion_fiscal.direccion` | string | Sí | | | `direccion_fiscal.codigo_establecimiento` | string | No | Código de establecimiento anexo en SUNAT; 0000 es el domicilio fiscal. | | `entorno` | "beta" \| "produccion" | Sí | `beta` en sandbox (SUNAT beta); `produccion` en producción. | | `modo_credenciales` | "por_llamada" \| "boveda" | Sí | `por_llamada`: envías `credenciales` en cada emisión. `boveda`: las guardamos cifradas. | | `credenciales_guardadas` | boolean | Sí | | | `creado_en` | string (date-time) | Sí | Fecha y hora ISO 8601 con la zona de Lima (-05:00). | ### Errores Cada código tiene su explicación en [Errores](https://docs.opennexum.com/errores/). - **400** [`validacion`](https://docs.opennexum.com/errores#validacion) - **401** [`clave_invalida`](https://docs.opennexum.com/errores#clave_invalida) - **403** [`permiso_faltante`](https://docs.opennexum.com/errores#permiso_faltante) - **403** [`emisor_obligado_ose`](https://docs.opennexum.com/errores#emisor_obligado_ose) - **409** [`idempotencia_en_conflicto`](https://docs.opennexum.com/errores#idempotencia_en_conflicto) - **409** [`solicitud_en_curso`](https://docs.opennexum.com/errores#solicitud_en_curso) - **409** [`ya_registrado`](https://docs.opennexum.com/errores#ya_registrado) - **429** [`limite_uso`](https://docs.opennexum.com/errores#limite_uso) - **500** [`error_interno`](https://docs.opennexum.com/errores#error_interno) - **501** [`operacion_no_disponible`](https://docs.opennexum.com/errores#operacion_no_disponible) - **503** [`no_disponible`](https://docs.opennexum.com/errores#no_disponible) --- Fuente: https://docs.opennexum.com/referencia/emisores/emisor_listar/ # Lista tus RUC emisores > RUC emisores de tu cuenta a los que tiene acceso la clave. `GET /v1/emisores` RUC emisores de tu cuenta a los que tiene acceso la clave. ## Ficha | Dato | Valor | |---|---| | Permiso | `comprobantes:leer` | | Cobro | No cobra. | | `Idempotency-Key` | No aplica | | Herramienta MCP | `emisor_listar` (Próximamente) | ## Parámetros | Nombre | En | Requerido | Tipo | Descripción | |---|---|---|---|---| | `cursor` | query | No | string | Cursor opaco que devolvió la página anterior en `siguiente_cursor`. | | `limite` | query | No | integer | Cuántos elementos traer (1 a 100; por defecto 20). | | `X-Request-Id` | header | No | string | Identificador de la petición. Va en cada respuesta; menciónalo al escribir a soporte. | ## Ejemplo Contra el sandbox, con una clave `onx_test_…`: ```bash curl "https://api-sandbox.opennexum.com/v1/emisores" \ -H "Authorization: Bearer onx_test_…" ``` ## Respuestas ### 200 Página de emisores. | Campo | Tipo | Requerido | Descripción | |---|---|---|---| | `elementos` | object[] | Sí | | | `elementos[].ruc` | string | Sí | RUC de 11 dígitos. Se valida el dígito verificador (módulo 11 de SUNAT). | | `elementos[].razon_social` | string | Sí | | | `elementos[].nombre_comercial` | string \| null | Sí | | | `elementos[].direccion_fiscal` | object \| null | Sí | | | `elementos[].direccion_fiscal.ubigeo` | string | Sí | Ubigeo INEI de 6 dígitos. | | `elementos[].direccion_fiscal.direccion` | string | Sí | | | `elementos[].direccion_fiscal.codigo_establecimiento` | string | No | Código de establecimiento anexo en SUNAT; 0000 es el domicilio fiscal. | | `elementos[].entorno` | "beta" \| "produccion" | Sí | `beta` en sandbox (SUNAT beta); `produccion` en producción. | | `elementos[].modo_credenciales` | "por_llamada" \| "boveda" | Sí | `por_llamada`: envías `credenciales` en cada emisión. `boveda`: las guardamos cifradas. | | `elementos[].credenciales_guardadas` | boolean | Sí | | | `elementos[].creado_en` | string (date-time) | Sí | Fecha y hora ISO 8601 con la zona de Lima (-05:00). | | `siguiente_cursor` | string \| null | Sí | Pásalo como `cursor` para la página siguiente; `null` si ya no hay más. | ### Errores Cada código tiene su explicación en [Errores](https://docs.opennexum.com/errores/). - **400** [`validacion`](https://docs.opennexum.com/errores#validacion) - **401** [`clave_invalida`](https://docs.opennexum.com/errores#clave_invalida) - **403** [`permiso_faltante`](https://docs.opennexum.com/errores#permiso_faltante) - **429** [`limite_uso`](https://docs.opennexum.com/errores#limite_uso) - **500** [`error_interno`](https://docs.opennexum.com/errores#error_interno) - **501** [`operacion_no_disponible`](https://docs.opennexum.com/errores#operacion_no_disponible) - **503** [`no_disponible`](https://docs.opennexum.com/errores#no_disponible) --- Fuente: https://docs.opennexum.com/referencia/emisores/emisor_ver/ # Consulta un RUC emisor > Datos del emisor, entorno y modo de credenciales. `GET /v1/emisores/{ruc}` Datos del emisor, entorno y modo de credenciales. ## Ficha | Dato | Valor | |---|---| | Permiso | `comprobantes:leer` | | Cobro | No cobra. | | `Idempotency-Key` | No aplica | | Herramienta MCP | `emisor_ver` (Próximamente) | ## Parámetros | Nombre | En | Requerido | Tipo | Descripción | |---|---|---|---|---| | `ruc` | path | Sí | string | RUC del emisor o contribuyente. | | `X-Request-Id` | header | No | string | Identificador de la petición. Va en cada respuesta; menciónalo al escribir a soporte. | ## Ejemplo Contra el sandbox, con una clave `onx_test_…`: ```bash curl "https://api-sandbox.opennexum.com/v1/emisores/20000000001" \ -H "Authorization: Bearer onx_test_…" ``` ## Respuestas ### 200 Emisor. | Campo | Tipo | Requerido | Descripción | |---|---|---|---| | `ruc` | string | Sí | RUC de 11 dígitos. Se valida el dígito verificador (módulo 11 de SUNAT). | | `razon_social` | string | Sí | | | `nombre_comercial` | string \| null | Sí | | | `direccion_fiscal` | object \| null | Sí | | | `direccion_fiscal.ubigeo` | string | Sí | Ubigeo INEI de 6 dígitos. | | `direccion_fiscal.direccion` | string | Sí | | | `direccion_fiscal.codigo_establecimiento` | string | No | Código de establecimiento anexo en SUNAT; 0000 es el domicilio fiscal. | | `entorno` | "beta" \| "produccion" | Sí | `beta` en sandbox (SUNAT beta); `produccion` en producción. | | `modo_credenciales` | "por_llamada" \| "boveda" | Sí | `por_llamada`: envías `credenciales` en cada emisión. `boveda`: las guardamos cifradas. | | `credenciales_guardadas` | boolean | Sí | | | `creado_en` | string (date-time) | Sí | Fecha y hora ISO 8601 con la zona de Lima (-05:00). | ### Errores Cada código tiene su explicación en [Errores](https://docs.opennexum.com/errores/). - **400** [`validacion`](https://docs.opennexum.com/errores#validacion) - **401** [`clave_invalida`](https://docs.opennexum.com/errores#clave_invalida) - **403** [`permiso_faltante`](https://docs.opennexum.com/errores#permiso_faltante) - **404** [`no_encontrado`](https://docs.opennexum.com/errores#no_encontrado) - **429** [`limite_uso`](https://docs.opennexum.com/errores#limite_uso) - **500** [`error_interno`](https://docs.opennexum.com/errores#error_interno) - **501** [`operacion_no_disponible`](https://docs.opennexum.com/errores#operacion_no_disponible) - **503** [`no_disponible`](https://docs.opennexum.com/errores#no_disponible) --- Fuente: https://docs.opennexum.com/referencia/emisores/credenciales_guardar/ # Guarda credenciales en la bóveda > 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. `PUT /v1/emisores/{ruc}/credenciales` 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. ## Ficha | Dato | Valor | |---|---| | Permiso | `emisores:administrar` | | Cobro | No cobra. | | `Idempotency-Key` | No aplica | | Herramienta MCP | No se ofrece a agentes. | ## Parámetros | Nombre | En | Requerido | Tipo | Descripción | |---|---|---|---|---| | `ruc` | path | Sí | string | RUC del emisor o contribuyente. | | `X-Request-Id` | header | No | string | Identificador de la petición. Va en cada respuesta; menciónalo al escribir a soporte. | ## Cuerpo `application/json`, obligatorio. Los campos anidados van con punto y los de listas con `[]`. No se aceptan campos desconocidos. | Campo | Tipo | Requerido | Descripción | |---|---|---|---| | `certificado` | object | Sí | Certificado digital del emisor. Nunca se guarda en registros ni se devuelve. | | `certificado.pfx_base64` | string (base64) | Sí | Archivo .pfx o .p12 del certificado digital, en base64. | | `certificado.clave` | string (password) | Sí | Contraseña del archivo .pfx. | | `sol` | object | Sí | Usuario secundario SOL del emisor. Nunca se guarda en registros ni se devuelve. | | `sol.usuario` | string | Sí | Usuario secundario SOL, sin el RUC (lo agregamos con el RUC del emisor). | | `sol.clave` | string (password) | Sí | Clave SOL del usuario secundario. | | `api_sunat` | object | No | Credenciales de la API de SUNAT (guías y SIRE), generadas en SOL. Nunca se guarda en registros ni se devuelve. | | `api_sunat.client_id` | string | Sí | | | `api_sunat.client_secret` | string (password) | Sí | | ## Ejemplo Contra el sandbox, con una clave `onx_test_…`: ```bash curl -X PUT "https://api-sandbox.opennexum.com/v1/emisores/20000000001/credenciales" \ -H "Authorization: Bearer onx_test_…" \ -H "Content-Type: application/json" \ -d '{ "certificado": { "pfx_base64": "texto", "clave": "texto" }, "sol": { "usuario": "texto", "clave": "texto" } }' ``` ## Respuestas ### 200 Credenciales guardadas (sin datos secretos). | Campo | Tipo | Requerido | Descripción | |---|---|---|---| | `ruc` | string | Sí | RUC de 11 dígitos. Se valida el dígito verificador (módulo 11 de SUNAT). | | `modo` | "boveda" | Sí | | | `certificado` | object | Sí | | | `certificado.titular_ruc` | string | Sí | RUC de 11 dígitos. Se valida el dígito verificador (módulo 11 de SUNAT). | | `certificado.vence_el` | string (date) | Sí | Fecha AAAA-MM-DD (día en Lima). | | `certificado.huella_sha256` | string | Sí | Huella del certificado, para reconocerlo. | | `sol` | object | Sí | | | `sol.usuario` | string | Sí | | | `api_sunat` | object \| null | Sí | | | `api_sunat.client_id` | string | Sí | | | `actualizadas_en` | string (date-time) | Sí | Fecha y hora ISO 8601 con la zona de Lima (-05:00). | | `version` | integer | Sí | Sube con cada cambio de credenciales. | ### Errores Cada código tiene su explicación en [Errores](https://docs.opennexum.com/errores/). - **400** [`validacion`](https://docs.opennexum.com/errores#validacion) - **401** [`clave_invalida`](https://docs.opennexum.com/errores#clave_invalida) - **403** [`permiso_faltante`](https://docs.opennexum.com/errores#permiso_faltante) - **404** [`no_encontrado`](https://docs.opennexum.com/errores#no_encontrado) - **409** [`boveda_inactiva`](https://docs.opennexum.com/errores#boveda_inactiva) - **422** [`credenciales_sunat`](https://docs.opennexum.com/errores#credenciales_sunat) - **429** [`limite_uso`](https://docs.opennexum.com/errores#limite_uso) - **500** [`error_interno`](https://docs.opennexum.com/errores#error_interno) - **501** [`operacion_no_disponible`](https://docs.opennexum.com/errores#operacion_no_disponible) - **503** [`no_disponible`](https://docs.opennexum.com/errores#no_disponible) --- Fuente: https://docs.opennexum.com/referencia/emisores/serie_listar/ # Lista las series de un emisor > Series registradas y el último número asignado en cada una. `GET /v1/emisores/{ruc}/series` Series registradas y el último número asignado en cada una. ## Ficha | Dato | Valor | |---|---| | Permiso | `comprobantes:leer` | | Cobro | No cobra. | | `Idempotency-Key` | No aplica | | Herramienta MCP | `serie_listar` (Próximamente) | ## Parámetros | Nombre | En | Requerido | Tipo | Descripción | |---|---|---|---|---| | `ruc` | path | Sí | string | RUC del emisor o contribuyente. | | `cursor` | query | No | string | Cursor opaco que devolvió la página anterior en `siguiente_cursor`. | | `limite` | query | No | integer | Cuántos elementos traer (1 a 100; por defecto 20). | | `X-Request-Id` | header | No | string | Identificador de la petición. Va en cada respuesta; menciónalo al escribir a soporte. | ## Ejemplo Contra el sandbox, con una clave `onx_test_…`: ```bash curl "https://api-sandbox.opennexum.com/v1/emisores/20000000001/series" \ -H "Authorization: Bearer onx_test_…" ``` ## Respuestas ### 200 Página de series. | Campo | Tipo | Requerido | Descripción | |---|---|---|---| | `elementos` | object[] | Sí | | | `elementos[].tipo` | "01" \| "03" \| "07" \| "08" \| "09" | Sí | 01 factura, 03 boleta, 07 nota de crédito, 08 nota de débito, 09 guía de remisión remitente. | | `elementos[].serie` | string | Sí | | | `elementos[].ultimo_numero` | integer | Sí | Último número asignado; el próximo será este + 1. | | `elementos[].creada_en` | string (date-time) | Sí | Fecha y hora ISO 8601 con la zona de Lima (-05:00). | | `siguiente_cursor` | string \| null | Sí | Pásalo como `cursor` para la página siguiente; `null` si ya no hay más. | ### Errores Cada código tiene su explicación en [Errores](https://docs.opennexum.com/errores/). - **400** [`validacion`](https://docs.opennexum.com/errores#validacion) - **401** [`clave_invalida`](https://docs.opennexum.com/errores#clave_invalida) - **403** [`permiso_faltante`](https://docs.opennexum.com/errores#permiso_faltante) - **404** [`no_encontrado`](https://docs.opennexum.com/errores#no_encontrado) - **429** [`limite_uso`](https://docs.opennexum.com/errores#limite_uso) - **500** [`error_interno`](https://docs.opennexum.com/errores#error_interno) - **501** [`operacion_no_disponible`](https://docs.opennexum.com/errores#operacion_no_disponible) - **503** [`no_disponible`](https://docs.opennexum.com/errores#no_disponible) --- Fuente: https://docs.opennexum.com/referencia/emisores/serie_crear/ # Crea una serie > Registra una serie (F001, B001, T001…). Si vienes de otro sistema, indica el último número usado. `POST /v1/emisores/{ruc}/series` Registra una serie (F001, B001, T001…). Si vienes de otro sistema, indica el último número usado. ## Ficha | Dato | Valor | |---|---| | Permiso | `emisores:administrar` | | Cobro | No cobra. | | `Idempotency-Key` | Opcional | | Herramienta MCP | `serie_crear` (Próximamente) | ## Parámetros | Nombre | En | Requerido | Tipo | Descripción | |---|---|---|---|---| | `ruc` | path | Sí | string | RUC del emisor o contribuyente. | | `Idempotency-Key` | header | No | string | 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. | | `X-Request-Id` | header | No | string | Identificador de la petición. Va en cada respuesta; menciónalo al escribir a soporte. | ## Cuerpo `application/json`, obligatorio. Los campos anidados van con punto y los de listas con `[]`. No se aceptan campos desconocidos. | Campo | Tipo | Requerido | Descripción | |---|---|---|---| | `tipo` | "01" \| "03" \| "07" \| "08" \| "09" | Sí | 01 factura, 03 boleta, 07 nota de crédito, 08 nota de débito, 09 guía de remisión remitente. | | `serie` | string | Sí | | | `ultimo_numero` | integer | No | Si vienes de otro sistema, el último número que usaste; seguimos desde el siguiente. | ## Ejemplo Contra el sandbox, con una clave `onx_test_…`: ```bash curl -X POST "https://api-sandbox.opennexum.com/v1/emisores/20000000001/series" \ -H "Authorization: Bearer onx_test_…" \ -H "Content-Type: application/json" \ -d '{ "tipo": "01", "serie": "texto" }' ``` ## Respuestas ### 201 Serie creada. | Campo | Tipo | Requerido | Descripción | |---|---|---|---| | `tipo` | "01" \| "03" \| "07" \| "08" \| "09" | Sí | 01 factura, 03 boleta, 07 nota de crédito, 08 nota de débito, 09 guía de remisión remitente. | | `serie` | string | Sí | | | `ultimo_numero` | integer | Sí | Último número asignado; el próximo será este + 1. | | `creada_en` | string (date-time) | Sí | Fecha y hora ISO 8601 con la zona de Lima (-05:00). | ### Errores Cada código tiene su explicación en [Errores](https://docs.opennexum.com/errores/). - **400** [`validacion`](https://docs.opennexum.com/errores#validacion) - **401** [`clave_invalida`](https://docs.opennexum.com/errores#clave_invalida) - **403** [`permiso_faltante`](https://docs.opennexum.com/errores#permiso_faltante) - **404** [`no_encontrado`](https://docs.opennexum.com/errores#no_encontrado) - **409** [`idempotencia_en_conflicto`](https://docs.opennexum.com/errores#idempotencia_en_conflicto) - **409** [`solicitud_en_curso`](https://docs.opennexum.com/errores#solicitud_en_curso) - **409** [`ya_registrado`](https://docs.opennexum.com/errores#ya_registrado) - **429** [`limite_uso`](https://docs.opennexum.com/errores#limite_uso) - **500** [`error_interno`](https://docs.opennexum.com/errores#error_interno) - **501** [`operacion_no_disponible`](https://docs.opennexum.com/errores#operacion_no_disponible) - **503** [`no_disponible`](https://docs.opennexum.com/errores#no_disponible) --- Fuente: https://docs.opennexum.com/referencia/comprobantes/comprobante_validar/ # Ensaya un comprobante sin emitirlo > 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. `POST /v1/emisores/{ruc}/comprobantes/validar` 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. ## Ficha | Dato | Valor | |---|---| | Permiso | `comprobantes:emitir` | | Cobro | No cobra. | | `Idempotency-Key` | No aplica | | Credenciales en la llamada | Si envías `credenciales`, la clave necesita `credenciales:por_llamada`. | | Herramienta MCP | `comprobante_validar` (Próximamente) | ## Parámetros | Nombre | En | Requerido | Tipo | Descripción | |---|---|---|---|---| | `ruc` | path | Sí | string | RUC del emisor o contribuyente. | | `X-Request-Id` | header | No | string | Identificador de la petición. Va en cada respuesta; menciónalo al escribir a soporte. | ## Cuerpo `application/json`, obligatorio. Los campos anidados van con punto y los de listas con `[]`. No se aceptan campos desconocidos. | Campo | Tipo | Requerido | Descripción | |---|---|---|---| | `tipo` | "01" \| "03" \| "07" \| "08" | Sí | 01 factura, 03 boleta, 07 nota de crédito, 08 nota de débito. | | `serie` | string | Sí | Serie registrada del emisor. El número lo asigna el servidor. | | `fecha_emision` | string (date) | No | Por defecto, hoy en Lima. SUNAT acepta pocos días hacia atrás. | | `fecha_vencimiento` | string (date) | No | Fecha AAAA-MM-DD (día en Lima). | | `moneda` | "PEN" \| "USD" | Sí | Código ISO 4217: PEN (soles) o USD (dólares). | | `tipo_cambio` | string | No | Obligatorio en dólares; no va en soles. | | `cliente` | object | Sí | A quién se le emite. | | `cliente.tipo_documento` | "0" \| "1" \| "4" \| "6" \| "7" | Sí | Catálogo 06: 0 sin documento, 1 DNI, 4 carné de extranjería, 6 RUC, 7 pasaporte. | | `cliente.numero_documento` | string | Sí | Número del documento; en tipo 0 puede ir «-». | | `cliente.nombre` | string | Sí | Razón social o nombre completo. | | `cliente.direccion` | string | No | | | `cliente.correo` | string (email) | No | Si lo envías, le mandamos el PDF y el XML. | | `items` | object[] | Sí | | | `items[].descripcion` | string | Sí | | | `items[].cantidad` | string | Sí | Cantidad como texto, mayor que cero, con hasta 6 decimales. | | `items[].unidad` | string | No | Unidad del catálogo 03, por ejemplo NIU (bienes) o ZZ (servicios). Por defecto NIU. | | `items[].codigo` | string | No | Tu código interno del producto. | | `items[].codigo_sunat` | string | No | Código de producto SUNAT (catálogo 25). | | `items[].precio_unitario` | string | Sí | 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). | | `items[].afectacion_igv` | "10" \| "11" \| "12" \| "13" \| "14" \| "15" \| "16" \| "20" \| "30" \| "31" \| "32" \| "33" \| "34" \| "35" \| "36" \| "37" | Sí | Catálogo 07: 10 gravado, 20 exonerado, 30 inafecto; 11–16 y 31–37 son transferencias gratuitas. | | `items[].icbper` | boolean | No | `true` si la línea son bolsas plásticas: se suma el ICBPER por bolsa. | | `forma_pago` | object \| object | No | Contado o crédito con cuotas. Si no la envías, es al contado. | | `detraccion` | object | No | Detracción (SPOT). Solo en facturas. | | `detraccion.codigo_bien_servicio` | string | Sí | Catálogo 54, por ejemplo 022 (otros servicios). | | `detraccion.porcentaje` | string | Sí | Porcentaje con dos decimales, por ejemplo "12.00". | | `detraccion.monto` | string | Sí | Monto de la detracción en soles. | | `detraccion.cuenta_banco_nacion` | string | Sí | Cuenta de detracciones del Banco de la Nación. | | `detraccion.medio_pago` | string | No | Catálogo 59; por defecto 001 (depósito en cuenta). | | `referencia` | object | No | Solo notas: el comprobante que modificas. | | `referencia.tipo` | "01" \| "03" | Sí | | | `referencia.serie` | string | Sí | | | `referencia.numero` | integer | Sí | | | `motivo` | object | No | Solo notas: el motivo con su código de catálogo. | | `motivo.codigo` | string | Sí | Catálogo 09 (crédito) o 10 (débito), por ejemplo 01. | | `motivo.descripcion` | string | Sí | | | `observacion` | string | No | | | `orden_compra` | string | No | | | `credenciales` | object | No | 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. | | `credenciales.certificado` | object | Sí | Certificado digital del emisor. Nunca se guarda en registros ni se devuelve. | | `credenciales.certificado.pfx_base64` | string (base64) | Sí | Archivo .pfx o .p12 del certificado digital, en base64. | | `credenciales.certificado.clave` | string (password) | Sí | Contraseña del archivo .pfx. | | `credenciales.sol` | object | Sí | Usuario secundario SOL del emisor. Nunca se guarda en registros ni se devuelve. | | `credenciales.sol.usuario` | string | Sí | Usuario secundario SOL, sin el RUC (lo agregamos con el RUC del emisor). | | `credenciales.sol.clave` | string (password) | Sí | Clave SOL del usuario secundario. | ## Ejemplo Contra el sandbox, con una clave `onx_test_…`: ```bash curl -X POST "https://api-sandbox.opennexum.com/v1/emisores/20000000001/comprobantes/validar" \ -H "Authorization: Bearer onx_test_…" \ -H "Content-Type: application/json" \ -d '{ "tipo": "01", "serie": "texto", "moneda": "PEN", "cliente": { "tipo_documento": "0", "numero_documento": "texto", "nombre": "texto" }, "items": [ { "descripcion": "texto", "cantidad": "2", "precio_unitario": "1250.50", "afectacion_igv": "10" } ] }' ``` ## Respuestas ### 200 Resultado del ensayo. | Campo | Tipo | Requerido | Descripción | |---|---|---|---| | `valido` | boolean | Sí | | | `totales` | object | Sí | Totales calculados por el servidor. | | `totales.gravado` | string | Sí | Monto como texto con dos decimales y punto decimal, sin separador de miles. "1250.50" es S/ 1,250.50. | | `totales.exonerado` | string | Sí | Monto como texto con dos decimales y punto decimal, sin separador de miles. "1250.50" es S/ 1,250.50. | | `totales.inafecto` | string | Sí | Monto como texto con dos decimales y punto decimal, sin separador de miles. "1250.50" es S/ 1,250.50. | | `totales.gratuito` | string | Sí | Monto como texto con dos decimales y punto decimal, sin separador de miles. "1250.50" es S/ 1,250.50. | | `totales.igv` | string | Sí | Monto como texto con dos decimales y punto decimal, sin separador de miles. "1250.50" es S/ 1,250.50. | | `totales.icbper` | string | Sí | Monto como texto con dos decimales y punto decimal, sin separador de miles. "1250.50" es S/ 1,250.50. | | `totales.total` | string | Sí | Importe total que paga el cliente. | | `problemas` | object[] | Sí | Reglas de negocio o de SUNAT que fallarían al emitir. | | `problemas[].campo` | string | Sí | | | `problemas[].mensaje` | string | Sí | | ### Errores Cada código tiene su explicación en [Errores](https://docs.opennexum.com/errores/). - **400** [`validacion`](https://docs.opennexum.com/errores#validacion) - **401** [`clave_invalida`](https://docs.opennexum.com/errores#clave_invalida) - **403** [`permiso_faltante`](https://docs.opennexum.com/errores#permiso_faltante) - **403** [`emisor_obligado_ose`](https://docs.opennexum.com/errores#emisor_obligado_ose) - **404** [`no_encontrado`](https://docs.opennexum.com/errores#no_encontrado) - **422** [`credenciales_sunat`](https://docs.opennexum.com/errores#credenciales_sunat) - **429** [`limite_uso`](https://docs.opennexum.com/errores#limite_uso) - **500** [`error_interno`](https://docs.opennexum.com/errores#error_interno) - **501** [`operacion_no_disponible`](https://docs.opennexum.com/errores#operacion_no_disponible) - **503** [`no_disponible`](https://docs.opennexum.com/errores#no_disponible) --- Fuente: https://docs.opennexum.com/referencia/comprobantes/comprobante_emitir/ # Emite una factura, boleta o nota > 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`). `POST /v1/emisores/{ruc}/comprobantes` 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`). ## Ficha | Dato | Valor | |---|---| | Permiso | `comprobantes:emitir` | | Cobro | Reserva el precio de tu saldo y lo cobra solo si el servicio confirma (por ejemplo, SUNAT acepta). | | `Idempotency-Key` | Obligatoria | | Aprobación humana | Según la configuración de tu clave puede responder `202` `requiere_confirmacion`. | | Credenciales en la llamada | Si envías `credenciales`, la clave necesita `credenciales:por_llamada`. | | Herramienta MCP | `comprobante_emitir` (Próximamente) | ## Parámetros | Nombre | En | Requerido | Tipo | Descripción | |---|---|---|---|---| | `ruc` | path | Sí | string | RUC del emisor o contribuyente. | | `Idempotency-Key` | header | Sí | string | 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. | | `X-Request-Id` | header | No | string | Identificador de la petición. Va en cada respuesta; menciónalo al escribir a soporte. | ## Cuerpo `application/json`, obligatorio. Los campos anidados van con punto y los de listas con `[]`. No se aceptan campos desconocidos. | Campo | Tipo | Requerido | Descripción | |---|---|---|---| | `tipo` | "01" \| "03" \| "07" \| "08" | Sí | 01 factura, 03 boleta, 07 nota de crédito, 08 nota de débito. | | `serie` | string | Sí | Serie registrada del emisor. El número lo asigna el servidor. | | `fecha_emision` | string (date) | No | Por defecto, hoy en Lima. SUNAT acepta pocos días hacia atrás. | | `fecha_vencimiento` | string (date) | No | Fecha AAAA-MM-DD (día en Lima). | | `moneda` | "PEN" \| "USD" | Sí | Código ISO 4217: PEN (soles) o USD (dólares). | | `tipo_cambio` | string | No | Obligatorio en dólares; no va en soles. | | `cliente` | object | Sí | A quién se le emite. | | `cliente.tipo_documento` | "0" \| "1" \| "4" \| "6" \| "7" | Sí | Catálogo 06: 0 sin documento, 1 DNI, 4 carné de extranjería, 6 RUC, 7 pasaporte. | | `cliente.numero_documento` | string | Sí | Número del documento; en tipo 0 puede ir «-». | | `cliente.nombre` | string | Sí | Razón social o nombre completo. | | `cliente.direccion` | string | No | | | `cliente.correo` | string (email) | No | Si lo envías, le mandamos el PDF y el XML. | | `items` | object[] | Sí | | | `items[].descripcion` | string | Sí | | | `items[].cantidad` | string | Sí | Cantidad como texto, mayor que cero, con hasta 6 decimales. | | `items[].unidad` | string | No | Unidad del catálogo 03, por ejemplo NIU (bienes) o ZZ (servicios). Por defecto NIU. | | `items[].codigo` | string | No | Tu código interno del producto. | | `items[].codigo_sunat` | string | No | Código de producto SUNAT (catálogo 25). | | `items[].precio_unitario` | string | Sí | 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). | | `items[].afectacion_igv` | "10" \| "11" \| "12" \| "13" \| "14" \| "15" \| "16" \| "20" \| "30" \| "31" \| "32" \| "33" \| "34" \| "35" \| "36" \| "37" | Sí | Catálogo 07: 10 gravado, 20 exonerado, 30 inafecto; 11–16 y 31–37 son transferencias gratuitas. | | `items[].icbper` | boolean | No | `true` si la línea son bolsas plásticas: se suma el ICBPER por bolsa. | | `forma_pago` | object \| object | No | Contado o crédito con cuotas. Si no la envías, es al contado. | | `detraccion` | object | No | Detracción (SPOT). Solo en facturas. | | `detraccion.codigo_bien_servicio` | string | Sí | Catálogo 54, por ejemplo 022 (otros servicios). | | `detraccion.porcentaje` | string | Sí | Porcentaje con dos decimales, por ejemplo "12.00". | | `detraccion.monto` | string | Sí | Monto de la detracción en soles. | | `detraccion.cuenta_banco_nacion` | string | Sí | Cuenta de detracciones del Banco de la Nación. | | `detraccion.medio_pago` | string | No | Catálogo 59; por defecto 001 (depósito en cuenta). | | `referencia` | object | No | Solo notas: el comprobante que modificas. | | `referencia.tipo` | "01" \| "03" | Sí | | | `referencia.serie` | string | Sí | | | `referencia.numero` | integer | Sí | | | `motivo` | object | No | Solo notas: el motivo con su código de catálogo. | | `motivo.codigo` | string | Sí | Catálogo 09 (crédito) o 10 (débito), por ejemplo 01. | | `motivo.descripcion` | string | Sí | | | `observacion` | string | No | | | `orden_compra` | string | No | | | `credenciales` | object | No | 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. | | `credenciales.certificado` | object | Sí | Certificado digital del emisor. Nunca se guarda en registros ni se devuelve. | | `credenciales.certificado.pfx_base64` | string (base64) | Sí | Archivo .pfx o .p12 del certificado digital, en base64. | | `credenciales.certificado.clave` | string (password) | Sí | Contraseña del archivo .pfx. | | `credenciales.sol` | object | Sí | Usuario secundario SOL del emisor. Nunca se guarda en registros ni se devuelve. | | `credenciales.sol.usuario` | string | Sí | Usuario secundario SOL, sin el RUC (lo agregamos con el RUC del emisor). | | `credenciales.sol.clave` | string (password) | Sí | Clave SOL del usuario secundario. | ## Ejemplo Contra el sandbox, con una clave `onx_test_…`: ```bash curl -X POST "https://api-sandbox.opennexum.com/v1/emisores/20000000001/comprobantes" \ -H "Authorization: Bearer onx_test_…" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "tipo": "01", "serie": "texto", "moneda": "PEN", "cliente": { "tipo_documento": "0", "numero_documento": "texto", "nombre": "texto" }, "items": [ { "descripcion": "texto", "cantidad": "2", "precio_unitario": "1250.50", "afectacion_igv": "10" } ] }' ``` ## Respuestas ### 201 Aceptado por SUNAT (o aceptado con observaciones). | Campo | Tipo | Requerido | Descripción | |---|---|---|---| | `id` | string | Sí | Identificador que empieza con `cmp_`. | | `emisor_ruc` | string | Sí | RUC de 11 dígitos. Se valida el dígito verificador (módulo 11 de SUNAT). | | `tipo` | "01" \| "03" \| "07" \| "08" | Sí | 01 factura, 03 boleta, 07 nota de crédito, 08 nota de débito. | | `serie` | string | Sí | | | `numero` | integer | Sí | Asignado por el servidor. | | `numero_completo` | string | Sí | Serie y número, por ejemplo F001-124. | | `fecha_emision` | string (date) | Sí | Fecha AAAA-MM-DD (día en Lima). | | `moneda` | "PEN" \| "USD" | Sí | Código ISO 4217: PEN (soles) o USD (dólares). | | `tipo_cambio` | string \| null | Sí | | | `cliente` | object | Sí | A quién se le emite. | | `cliente.tipo_documento` | "0" \| "1" \| "4" \| "6" \| "7" | Sí | Catálogo 06: 0 sin documento, 1 DNI, 4 carné de extranjería, 6 RUC, 7 pasaporte. | | `cliente.numero_documento` | string | Sí | Número del documento; en tipo 0 puede ir «-». | | `cliente.nombre` | string | Sí | Razón social o nombre completo. | | `cliente.direccion` | string | No | | | `cliente.correo` | string (email) | No | Si lo envías, le mandamos el PDF y el XML. | | `items` | object[] | Sí | | | `items[].descripcion` | string | Sí | | | `items[].cantidad` | string | Sí | Cantidad como texto, mayor que cero, con hasta 6 decimales. | | `items[].unidad` | string | No | Unidad del catálogo 03, por ejemplo NIU (bienes) o ZZ (servicios). Por defecto NIU. | | `items[].codigo` | string | No | Tu código interno del producto. | | `items[].codigo_sunat` | string | No | Código de producto SUNAT (catálogo 25). | | `items[].precio_unitario` | string | Sí | 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). | | `items[].afectacion_igv` | "10" \| "11" \| "12" \| "13" \| "14" \| "15" \| "16" \| "20" \| "30" \| "31" \| "32" \| "33" \| "34" \| "35" \| "36" \| "37" | Sí | Catálogo 07: 10 gravado, 20 exonerado, 30 inafecto; 11–16 y 31–37 son transferencias gratuitas. | | `items[].icbper` | boolean | No | `true` si la línea son bolsas plásticas: se suma el ICBPER por bolsa. | | `forma_pago` | object \| object | Sí | Contado o crédito con cuotas. Si no la envías, es al contado. | | `totales` | object | Sí | Totales calculados por el servidor. | | `totales.gravado` | string | Sí | Monto como texto con dos decimales y punto decimal, sin separador de miles. "1250.50" es S/ 1,250.50. | | `totales.exonerado` | string | Sí | Monto como texto con dos decimales y punto decimal, sin separador de miles. "1250.50" es S/ 1,250.50. | | `totales.inafecto` | string | Sí | Monto como texto con dos decimales y punto decimal, sin separador de miles. "1250.50" es S/ 1,250.50. | | `totales.gratuito` | string | Sí | Monto como texto con dos decimales y punto decimal, sin separador de miles. "1250.50" es S/ 1,250.50. | | `totales.igv` | string | Sí | Monto como texto con dos decimales y punto decimal, sin separador de miles. "1250.50" es S/ 1,250.50. | | `totales.icbper` | string | Sí | Monto como texto con dos decimales y punto decimal, sin separador de miles. "1250.50" es S/ 1,250.50. | | `totales.total` | string | Sí | Importe total que paga el cliente. | | `referencia` | object \| null | Sí | | | `referencia.tipo` | "01" \| "03" | Sí | | | `referencia.serie` | string | Sí | | | `referencia.numero` | integer | Sí | | | `motivo` | object \| null | Sí | | | `motivo.codigo` | string | Sí | Catálogo 09 (crédito) o 10 (débito), por ejemplo 01. | | `motivo.descripcion` | string | Sí | | | `estado` | "en_cola" \| "aceptado" \| "observado" \| "rechazado" \| "en_baja" \| "anulado" | Sí | `en_cola`: guardado y esperando a SUNAT. `observado`: aceptado con observaciones. `en_baja`: anulación en curso. | | `sunat` | object \| null | Sí | | | `sunat.codigo` | string | Sí | Código de respuesta de SUNAT; 0 es aceptado. | | `sunat.descripcion` | string | Sí | | | `sunat.observaciones` | string[] | Sí | | | `hash` | string \| null | Sí | Valor del resumen (DigestValue) de la firma, el que va en el QR. | | `enlaces` | object | Sí | | | `enlaces.xml` | string | Sí | | | `enlaces.cdr` | string \| null | Sí | `null` mientras SUNAT no responde. | | `enlaces.pdf` | string | Sí | | | `creado_en` | string (date-time) | Sí | Fecha y hora ISO 8601 con la zona de Lima (-05:00). | | `actualizado_en` | string (date-time) | Sí | Fecha y hora ISO 8601 con la zona de Lima (-05:00). | ### 202 En cola por SUNAT o esperando aprobación humana. | Campo | Tipo | Requerido | Descripción | |---|---|---|---| | `estado` | "requiere_confirmacion" | Sí | | | `operacion_id` | string | No | Úsalo en `GET /v1/confirmaciones/{id}` para saber si se aprobó. | | `confirmacion_url` | string (uri) | No | Enlace del panel donde una persona aprueba o rechaza. Pásaselo tal cual. | | `consulta_url` | string | Sí | Ruta para consultar el estado. | | `expira_en` | string (date-time) | No | Si nadie aprueba antes, la operación vence y no se hace. | | `mensaje` | string | Sí | Qué falta, en palabras para una persona. | | `recurso` | object | No | Lo que se creó y queda en proceso. | | `recurso.tipo` | "comprobante" \| "baja" \| "resumen" \| "guia" \| "sire_propuesta" \| "mensaje" \| "entrega" \| "clave" \| "conexion" \| "webhook" | No | | | `recurso.id` | string | No | | | `reintento_en` | string (date-time) | No | Próximo intento estimado, si aplica. | ### Errores Cada código tiene su explicación en [Errores](https://docs.opennexum.com/errores/). - **400** [`validacion`](https://docs.opennexum.com/errores#validacion) - **401** [`clave_invalida`](https://docs.opennexum.com/errores#clave_invalida) - **402** [`saldo_insuficiente`](https://docs.opennexum.com/errores#saldo_insuficiente) - **402** [`tope_alcanzado`](https://docs.opennexum.com/errores#tope_alcanzado) - **403** [`permiso_faltante`](https://docs.opennexum.com/errores#permiso_faltante) - **403** [`emisor_obligado_ose`](https://docs.opennexum.com/errores#emisor_obligado_ose) - **404** [`no_encontrado`](https://docs.opennexum.com/errores#no_encontrado) - **409** [`idempotencia_en_conflicto`](https://docs.opennexum.com/errores#idempotencia_en_conflicto) - **409** [`solicitud_en_curso`](https://docs.opennexum.com/errores#solicitud_en_curso) - **409** [`boveda_inactiva`](https://docs.opennexum.com/errores#boveda_inactiva) - **409** [`plazo_vencido`](https://docs.opennexum.com/errores#plazo_vencido) - **422** [`sunat_rechazo`](https://docs.opennexum.com/errores#sunat_rechazo) - **422** [`credenciales_sunat`](https://docs.opennexum.com/errores#credenciales_sunat) - **429** [`limite_uso`](https://docs.opennexum.com/errores#limite_uso) - **500** [`error_interno`](https://docs.opennexum.com/errores#error_interno) - **501** [`operacion_no_disponible`](https://docs.opennexum.com/errores#operacion_no_disponible) - **503** [`no_disponible`](https://docs.opennexum.com/errores#no_disponible) --- Fuente: https://docs.opennexum.com/referencia/comprobantes/comprobante_listar/ # Lista comprobantes de un emisor > Comprobantes del RUC, del más reciente al más antiguo, con filtros por tipo, serie, estado y fechas. `GET /v1/emisores/{ruc}/comprobantes` Comprobantes del RUC, del más reciente al más antiguo, con filtros por tipo, serie, estado y fechas. ## Ficha | Dato | Valor | |---|---| | Permiso | `comprobantes:leer` | | Cobro | No cobra. | | `Idempotency-Key` | No aplica | | Herramienta MCP | `comprobante_listar` (Próximamente) | ## Parámetros | Nombre | En | Requerido | Tipo | Descripción | |---|---|---|---|---| | `ruc` | path | Sí | string | RUC del emisor o contribuyente. | | `cursor` | query | No | string | Cursor opaco que devolvió la página anterior en `siguiente_cursor`. | | `limite` | query | No | integer | Cuántos elementos traer (1 a 100; por defecto 20). | | `tipo` | query | No | string | 01 factura, 03 boleta, 07 nota de crédito, 08 nota de débito. | | `serie` | query | No | string | | | `estado` | query | No | string | `en_cola`: guardado y esperando a SUNAT. `observado`: aceptado con observaciones. `en_baja`: anulación en curso. | | `desde` | query | No | string | Emitidos desde este día (incluido). | | `hasta` | query | No | string | Emitidos hasta este día (incluido). | | `cliente_documento` | query | No | string | Número de documento del cliente. | | `X-Request-Id` | header | No | string | Identificador de la petición. Va en cada respuesta; menciónalo al escribir a soporte. | ## Ejemplo Contra el sandbox, con una clave `onx_test_…`: ```bash curl "https://api-sandbox.opennexum.com/v1/emisores/20000000001/comprobantes" \ -H "Authorization: Bearer onx_test_…" ``` ## Respuestas ### 200 Página de comprobantes. | Campo | Tipo | Requerido | Descripción | |---|---|---|---| | `elementos` | object[] | Sí | | | `elementos[].id` | string | Sí | Identificador que empieza con `cmp_`. | | `elementos[].emisor_ruc` | string | Sí | RUC de 11 dígitos. Se valida el dígito verificador (módulo 11 de SUNAT). | | `elementos[].tipo` | "01" \| "03" \| "07" \| "08" | Sí | 01 factura, 03 boleta, 07 nota de crédito, 08 nota de débito. | | `elementos[].serie` | string | Sí | | | `elementos[].numero` | integer | Sí | Asignado por el servidor. | | `elementos[].numero_completo` | string | Sí | Serie y número, por ejemplo F001-124. | | `elementos[].fecha_emision` | string (date) | Sí | Fecha AAAA-MM-DD (día en Lima). | | `elementos[].moneda` | "PEN" \| "USD" | Sí | Código ISO 4217: PEN (soles) o USD (dólares). | | `elementos[].tipo_cambio` | string \| null | Sí | | | `elementos[].cliente` | object | Sí | A quién se le emite. | | `elementos[].cliente.tipo_documento` | "0" \| "1" \| "4" \| "6" \| "7" | Sí | Catálogo 06: 0 sin documento, 1 DNI, 4 carné de extranjería, 6 RUC, 7 pasaporte. | | `elementos[].cliente.numero_documento` | string | Sí | Número del documento; en tipo 0 puede ir «-». | | `elementos[].cliente.nombre` | string | Sí | Razón social o nombre completo. | | `elementos[].cliente.direccion` | string | No | | | `elementos[].cliente.correo` | string (email) | No | Si lo envías, le mandamos el PDF y el XML. | | `elementos[].items` | object[] | Sí | | | `elementos[].items[].descripcion` | string | Sí | | | `elementos[].items[].cantidad` | string | Sí | Cantidad como texto, mayor que cero, con hasta 6 decimales. | | `elementos[].items[].unidad` | string | No | Unidad del catálogo 03, por ejemplo NIU (bienes) o ZZ (servicios). Por defecto NIU. | | `elementos[].items[].codigo` | string | No | Tu código interno del producto. | | `elementos[].items[].codigo_sunat` | string | No | Código de producto SUNAT (catálogo 25). | | `elementos[].items[].precio_unitario` | string | Sí | 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). | | `elementos[].items[].afectacion_igv` | "10" \| "11" \| "12" \| "13" \| "14" \| "15" \| "16" \| "20" \| "30" \| "31" \| "32" \| "33" \| "34" \| "35" \| "36" \| "37" | Sí | Catálogo 07: 10 gravado, 20 exonerado, 30 inafecto; 11–16 y 31–37 son transferencias gratuitas. | | `elementos[].items[].icbper` | boolean | No | `true` si la línea son bolsas plásticas: se suma el ICBPER por bolsa. | | `elementos[].forma_pago` | object \| object | Sí | Contado o crédito con cuotas. Si no la envías, es al contado. | | `elementos[].totales` | object | Sí | Totales calculados por el servidor. | | `elementos[].totales.gravado` | string | Sí | Monto como texto con dos decimales y punto decimal, sin separador de miles. "1250.50" es S/ 1,250.50. | | `elementos[].totales.exonerado` | string | Sí | Monto como texto con dos decimales y punto decimal, sin separador de miles. "1250.50" es S/ 1,250.50. | | `elementos[].totales.inafecto` | string | Sí | Monto como texto con dos decimales y punto decimal, sin separador de miles. "1250.50" es S/ 1,250.50. | | `elementos[].totales.gratuito` | string | Sí | Monto como texto con dos decimales y punto decimal, sin separador de miles. "1250.50" es S/ 1,250.50. | | `elementos[].totales.igv` | string | Sí | Monto como texto con dos decimales y punto decimal, sin separador de miles. "1250.50" es S/ 1,250.50. | | `elementos[].totales.icbper` | string | Sí | Monto como texto con dos decimales y punto decimal, sin separador de miles. "1250.50" es S/ 1,250.50. | | `elementos[].totales.total` | string | Sí | Importe total que paga el cliente. | | `elementos[].referencia` | object \| null | Sí | | | `elementos[].referencia.tipo` | "01" \| "03" | Sí | | | `elementos[].referencia.serie` | string | Sí | | | `elementos[].referencia.numero` | integer | Sí | | | `elementos[].motivo` | object \| null | Sí | | | `elementos[].motivo.codigo` | string | Sí | Catálogo 09 (crédito) o 10 (débito), por ejemplo 01. | | `elementos[].motivo.descripcion` | string | Sí | | | `elementos[].estado` | "en_cola" \| "aceptado" \| "observado" \| "rechazado" \| "en_baja" \| "anulado" | Sí | `en_cola`: guardado y esperando a SUNAT. `observado`: aceptado con observaciones. `en_baja`: anulación en curso. | | `elementos[].sunat` | object \| null | Sí | | | `elementos[].sunat.codigo` | string | Sí | Código de respuesta de SUNAT; 0 es aceptado. | | `elementos[].sunat.descripcion` | string | Sí | | | `elementos[].sunat.observaciones` | string[] | Sí | | | `elementos[].hash` | string \| null | Sí | Valor del resumen (DigestValue) de la firma, el que va en el QR. | | `elementos[].enlaces` | object | Sí | | | `elementos[].enlaces.xml` | string | Sí | | | `elementos[].enlaces.cdr` | string \| null | Sí | `null` mientras SUNAT no responde. | | `elementos[].enlaces.pdf` | string | Sí | | | `elementos[].creado_en` | string (date-time) | Sí | Fecha y hora ISO 8601 con la zona de Lima (-05:00). | | `elementos[].actualizado_en` | string (date-time) | Sí | Fecha y hora ISO 8601 con la zona de Lima (-05:00). | | `siguiente_cursor` | string \| null | Sí | Pásalo como `cursor` para la página siguiente; `null` si ya no hay más. | ### Errores Cada código tiene su explicación en [Errores](https://docs.opennexum.com/errores/). - **400** [`validacion`](https://docs.opennexum.com/errores#validacion) - **401** [`clave_invalida`](https://docs.opennexum.com/errores#clave_invalida) - **403** [`permiso_faltante`](https://docs.opennexum.com/errores#permiso_faltante) - **404** [`no_encontrado`](https://docs.opennexum.com/errores#no_encontrado) - **429** [`limite_uso`](https://docs.opennexum.com/errores#limite_uso) - **500** [`error_interno`](https://docs.opennexum.com/errores#error_interno) - **501** [`operacion_no_disponible`](https://docs.opennexum.com/errores#operacion_no_disponible) - **503** [`no_disponible`](https://docs.opennexum.com/errores#no_disponible) --- Fuente: https://docs.opennexum.com/referencia/comprobantes/comprobante_ver/ # Consulta un comprobante > Detalle, estado ante SUNAT y enlaces de descarga de un comprobante. `GET /v1/emisores/{ruc}/comprobantes/{id}` Detalle, estado ante SUNAT y enlaces de descarga de un comprobante. ## Ficha | Dato | Valor | |---|---| | Permiso | `comprobantes:leer` | | Cobro | No cobra. | | `Idempotency-Key` | No aplica | | Herramienta MCP | `comprobante_ver` (Próximamente) | ## Parámetros | Nombre | En | Requerido | Tipo | Descripción | |---|---|---|---|---| | `ruc` | path | Sí | string | RUC del emisor. | | `id` | path | Sí | string | Identificador que empieza con `cmp_`. | | `X-Request-Id` | header | No | string | Identificador de la petición. Va en cada respuesta; menciónalo al escribir a soporte. | ## Ejemplo Contra el sandbox, con una clave `onx_test_…`: ```bash curl "https://api-sandbox.opennexum.com/v1/emisores/20000000001/comprobantes/cmp_8f2c1a7d9e" \ -H "Authorization: Bearer onx_test_…" ``` ## Respuestas ### 200 Comprobante. | Campo | Tipo | Requerido | Descripción | |---|---|---|---| | `id` | string | Sí | Identificador que empieza con `cmp_`. | | `emisor_ruc` | string | Sí | RUC de 11 dígitos. Se valida el dígito verificador (módulo 11 de SUNAT). | | `tipo` | "01" \| "03" \| "07" \| "08" | Sí | 01 factura, 03 boleta, 07 nota de crédito, 08 nota de débito. | | `serie` | string | Sí | | | `numero` | integer | Sí | Asignado por el servidor. | | `numero_completo` | string | Sí | Serie y número, por ejemplo F001-124. | | `fecha_emision` | string (date) | Sí | Fecha AAAA-MM-DD (día en Lima). | | `moneda` | "PEN" \| "USD" | Sí | Código ISO 4217: PEN (soles) o USD (dólares). | | `tipo_cambio` | string \| null | Sí | | | `cliente` | object | Sí | A quién se le emite. | | `cliente.tipo_documento` | "0" \| "1" \| "4" \| "6" \| "7" | Sí | Catálogo 06: 0 sin documento, 1 DNI, 4 carné de extranjería, 6 RUC, 7 pasaporte. | | `cliente.numero_documento` | string | Sí | Número del documento; en tipo 0 puede ir «-». | | `cliente.nombre` | string | Sí | Razón social o nombre completo. | | `cliente.direccion` | string | No | | | `cliente.correo` | string (email) | No | Si lo envías, le mandamos el PDF y el XML. | | `items` | object[] | Sí | | | `items[].descripcion` | string | Sí | | | `items[].cantidad` | string | Sí | Cantidad como texto, mayor que cero, con hasta 6 decimales. | | `items[].unidad` | string | No | Unidad del catálogo 03, por ejemplo NIU (bienes) o ZZ (servicios). Por defecto NIU. | | `items[].codigo` | string | No | Tu código interno del producto. | | `items[].codigo_sunat` | string | No | Código de producto SUNAT (catálogo 25). | | `items[].precio_unitario` | string | Sí | 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). | | `items[].afectacion_igv` | "10" \| "11" \| "12" \| "13" \| "14" \| "15" \| "16" \| "20" \| "30" \| "31" \| "32" \| "33" \| "34" \| "35" \| "36" \| "37" | Sí | Catálogo 07: 10 gravado, 20 exonerado, 30 inafecto; 11–16 y 31–37 son transferencias gratuitas. | | `items[].icbper` | boolean | No | `true` si la línea son bolsas plásticas: se suma el ICBPER por bolsa. | | `forma_pago` | object \| object | Sí | Contado o crédito con cuotas. Si no la envías, es al contado. | | `totales` | object | Sí | Totales calculados por el servidor. | | `totales.gravado` | string | Sí | Monto como texto con dos decimales y punto decimal, sin separador de miles. "1250.50" es S/ 1,250.50. | | `totales.exonerado` | string | Sí | Monto como texto con dos decimales y punto decimal, sin separador de miles. "1250.50" es S/ 1,250.50. | | `totales.inafecto` | string | Sí | Monto como texto con dos decimales y punto decimal, sin separador de miles. "1250.50" es S/ 1,250.50. | | `totales.gratuito` | string | Sí | Monto como texto con dos decimales y punto decimal, sin separador de miles. "1250.50" es S/ 1,250.50. | | `totales.igv` | string | Sí | Monto como texto con dos decimales y punto decimal, sin separador de miles. "1250.50" es S/ 1,250.50. | | `totales.icbper` | string | Sí | Monto como texto con dos decimales y punto decimal, sin separador de miles. "1250.50" es S/ 1,250.50. | | `totales.total` | string | Sí | Importe total que paga el cliente. | | `referencia` | object \| null | Sí | | | `referencia.tipo` | "01" \| "03" | Sí | | | `referencia.serie` | string | Sí | | | `referencia.numero` | integer | Sí | | | `motivo` | object \| null | Sí | | | `motivo.codigo` | string | Sí | Catálogo 09 (crédito) o 10 (débito), por ejemplo 01. | | `motivo.descripcion` | string | Sí | | | `estado` | "en_cola" \| "aceptado" \| "observado" \| "rechazado" \| "en_baja" \| "anulado" | Sí | `en_cola`: guardado y esperando a SUNAT. `observado`: aceptado con observaciones. `en_baja`: anulación en curso. | | `sunat` | object \| null | Sí | | | `sunat.codigo` | string | Sí | Código de respuesta de SUNAT; 0 es aceptado. | | `sunat.descripcion` | string | Sí | | | `sunat.observaciones` | string[] | Sí | | | `hash` | string \| null | Sí | Valor del resumen (DigestValue) de la firma, el que va en el QR. | | `enlaces` | object | Sí | | | `enlaces.xml` | string | Sí | | | `enlaces.cdr` | string \| null | Sí | `null` mientras SUNAT no responde. | | `enlaces.pdf` | string | Sí | | | `creado_en` | string (date-time) | Sí | Fecha y hora ISO 8601 con la zona de Lima (-05:00). | | `actualizado_en` | string (date-time) | Sí | Fecha y hora ISO 8601 con la zona de Lima (-05:00). | ### Errores Cada código tiene su explicación en [Errores](https://docs.opennexum.com/errores/). - **400** [`validacion`](https://docs.opennexum.com/errores#validacion) - **401** [`clave_invalida`](https://docs.opennexum.com/errores#clave_invalida) - **403** [`permiso_faltante`](https://docs.opennexum.com/errores#permiso_faltante) - **404** [`no_encontrado`](https://docs.opennexum.com/errores#no_encontrado) - **429** [`limite_uso`](https://docs.opennexum.com/errores#limite_uso) - **500** [`error_interno`](https://docs.opennexum.com/errores#error_interno) - **501** [`operacion_no_disponible`](https://docs.opennexum.com/errores#operacion_no_disponible) - **503** [`no_disponible`](https://docs.opennexum.com/errores#no_disponible) --- Fuente: https://docs.opennexum.com/referencia/comprobantes/comprobante_xml/ # Descarga el XML firmado > XML UBL 2.1 firmado tal como se envió a SUNAT. `GET /v1/emisores/{ruc}/comprobantes/{id}/xml` XML UBL 2.1 firmado tal como se envió a SUNAT. ## Ficha | Dato | Valor | |---|---| | Permiso | `comprobantes:leer` | | Cobro | No cobra. | | `Idempotency-Key` | No aplica | | Herramienta MCP | No se ofrece a agentes. | ## Parámetros | Nombre | En | Requerido | Tipo | Descripción | |---|---|---|---|---| | `ruc` | path | Sí | string | RUC del emisor. | | `id` | path | Sí | string | Identificador que empieza con `cmp_`. | | `X-Request-Id` | header | No | string | Identificador de la petición. Va en cada respuesta; menciónalo al escribir a soporte. | ## Ejemplo Contra el sandbox, con una clave `onx_test_…`: ```bash curl "https://api-sandbox.opennexum.com/v1/emisores/20000000001/comprobantes/cmp_8f2c1a7d9e/xml" \ -H "Authorization: Bearer onx_test_…" ``` ## Respuestas ### 200 Archivo del comprobante. Contenido: `application/xml`. ### Errores Cada código tiene su explicación en [Errores](https://docs.opennexum.com/errores/). - **400** [`validacion`](https://docs.opennexum.com/errores#validacion) - **401** [`clave_invalida`](https://docs.opennexum.com/errores#clave_invalida) - **403** [`permiso_faltante`](https://docs.opennexum.com/errores#permiso_faltante) - **404** [`no_encontrado`](https://docs.opennexum.com/errores#no_encontrado) - **409** [`estado_no_permite`](https://docs.opennexum.com/errores#estado_no_permite) - **429** [`limite_uso`](https://docs.opennexum.com/errores#limite_uso) - **500** [`error_interno`](https://docs.opennexum.com/errores#error_interno) - **501** [`operacion_no_disponible`](https://docs.opennexum.com/errores#operacion_no_disponible) - **503** [`no_disponible`](https://docs.opennexum.com/errores#no_disponible) --- Fuente: https://docs.opennexum.com/referencia/comprobantes/comprobante_cdr/ # Descarga el CDR > Constancia de recepción (CDR) de SUNAT en XML. Mientras está `en_cola` responde `estado_no_permite`. `GET /v1/emisores/{ruc}/comprobantes/{id}/cdr` Constancia de recepción (CDR) de SUNAT en XML. Mientras está `en_cola` responde `estado_no_permite`. ## Ficha | Dato | Valor | |---|---| | Permiso | `comprobantes:leer` | | Cobro | No cobra. | | `Idempotency-Key` | No aplica | | Herramienta MCP | No se ofrece a agentes. | ## Parámetros | Nombre | En | Requerido | Tipo | Descripción | |---|---|---|---|---| | `ruc` | path | Sí | string | RUC del emisor. | | `id` | path | Sí | string | Identificador que empieza con `cmp_`. | | `X-Request-Id` | header | No | string | Identificador de la petición. Va en cada respuesta; menciónalo al escribir a soporte. | ## Ejemplo Contra el sandbox, con una clave `onx_test_…`: ```bash curl "https://api-sandbox.opennexum.com/v1/emisores/20000000001/comprobantes/cmp_8f2c1a7d9e/cdr" \ -H "Authorization: Bearer onx_test_…" ``` ## Respuestas ### 200 Archivo del comprobante. Contenido: `application/xml`. ### Errores Cada código tiene su explicación en [Errores](https://docs.opennexum.com/errores/). - **400** [`validacion`](https://docs.opennexum.com/errores#validacion) - **401** [`clave_invalida`](https://docs.opennexum.com/errores#clave_invalida) - **403** [`permiso_faltante`](https://docs.opennexum.com/errores#permiso_faltante) - **404** [`no_encontrado`](https://docs.opennexum.com/errores#no_encontrado) - **409** [`estado_no_permite`](https://docs.opennexum.com/errores#estado_no_permite) - **429** [`limite_uso`](https://docs.opennexum.com/errores#limite_uso) - **500** [`error_interno`](https://docs.opennexum.com/errores#error_interno) - **501** [`operacion_no_disponible`](https://docs.opennexum.com/errores#operacion_no_disponible) - **503** [`no_disponible`](https://docs.opennexum.com/errores#no_disponible) --- Fuente: https://docs.opennexum.com/referencia/comprobantes/comprobante_pdf/ # Descarga el PDF > Representación impresa con QR, en A4 o ticket de 80 mm. `GET /v1/emisores/{ruc}/comprobantes/{id}/pdf` Representación impresa con QR, en A4 o ticket de 80 mm. ## Ficha | Dato | Valor | |---|---| | Permiso | `comprobantes:leer` | | Cobro | No cobra. | | `Idempotency-Key` | No aplica | | Herramienta MCP | `comprobante_pdf` (Próximamente) | ## Parámetros | Nombre | En | Requerido | Tipo | Descripción | |---|---|---|---|---| | `ruc` | path | Sí | string | RUC del emisor. | | `id` | path | Sí | string | Identificador que empieza con `cmp_`. | | `formato` | query | No | string | `a4` (por defecto) o `ticket80` para impresoras de 80 mm. | | `X-Request-Id` | header | No | string | Identificador de la petición. Va en cada respuesta; menciónalo al escribir a soporte. | ## Ejemplo Contra el sandbox, con una clave `onx_test_…`: ```bash curl "https://api-sandbox.opennexum.com/v1/emisores/20000000001/comprobantes/cmp_8f2c1a7d9e/pdf" \ -H "Authorization: Bearer onx_test_…" ``` ## Respuestas ### 200 Archivo del comprobante. Contenido: `application/pdf`. ### Errores Cada código tiene su explicación en [Errores](https://docs.opennexum.com/errores/). - **400** [`validacion`](https://docs.opennexum.com/errores#validacion) - **401** [`clave_invalida`](https://docs.opennexum.com/errores#clave_invalida) - **403** [`permiso_faltante`](https://docs.opennexum.com/errores#permiso_faltante) - **404** [`no_encontrado`](https://docs.opennexum.com/errores#no_encontrado) - **409** [`estado_no_permite`](https://docs.opennexum.com/errores#estado_no_permite) - **429** [`limite_uso`](https://docs.opennexum.com/errores#limite_uso) - **500** [`error_interno`](https://docs.opennexum.com/errores#error_interno) - **501** [`operacion_no_disponible`](https://docs.opennexum.com/errores#operacion_no_disponible) - **503** [`no_disponible`](https://docs.opennexum.com/errores#no_disponible) --- Fuente: https://docs.opennexum.com/referencia/comprobantes/comprobante_anular/ # Da de baja un comprobante > 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. `POST /v1/emisores/{ruc}/comprobantes/{id}/anular` 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. ## Ficha | Dato | Valor | |---|---| | Permiso | `comprobantes:anular` | | Cobro | No cobra. | | `Idempotency-Key` | Obligatoria | | Aprobación humana | Según la configuración de tu clave puede responder `202` `requiere_confirmacion`. | | Credenciales en la llamada | Si envías `credenciales`, la clave necesita `credenciales:por_llamada`. | | Herramienta MCP | `comprobante_anular` (Próximamente) | ## Parámetros | Nombre | En | Requerido | Tipo | Descripción | |---|---|---|---|---| | `ruc` | path | Sí | string | RUC del emisor. | | `id` | path | Sí | string | Identificador que empieza con `cmp_`. | | `Idempotency-Key` | header | Sí | string | 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. | | `X-Request-Id` | header | No | string | Identificador de la petición. Va en cada respuesta; menciónalo al escribir a soporte. | ## Cuerpo `application/json`, obligatorio. Los campos anidados van con punto y los de listas con `[]`. No se aceptan campos desconocidos. | Campo | Tipo | Requerido | Descripción | |---|---|---|---| | `motivo` | string | Sí | Motivo de la baja que verá SUNAT. | | `credenciales` | object | No | 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. | | `credenciales.certificado` | object | Sí | Certificado digital del emisor. Nunca se guarda en registros ni se devuelve. | | `credenciales.certificado.pfx_base64` | string (base64) | Sí | Archivo .pfx o .p12 del certificado digital, en base64. | | `credenciales.certificado.clave` | string (password) | Sí | Contraseña del archivo .pfx. | | `credenciales.sol` | object | Sí | Usuario secundario SOL del emisor. Nunca se guarda en registros ni se devuelve. | | `credenciales.sol.usuario` | string | Sí | Usuario secundario SOL, sin el RUC (lo agregamos con el RUC del emisor). | | `credenciales.sol.clave` | string (password) | Sí | Clave SOL del usuario secundario. | ## Ejemplo Contra el sandbox, con una clave `onx_test_…`: ```bash curl -X POST "https://api-sandbox.opennexum.com/v1/emisores/20000000001/comprobantes/cmp_8f2c1a7d9e/anular" \ -H "Authorization: Bearer onx_test_…" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "motivo": "texto" }' ``` ## Respuestas ### 202 Baja en cola o esperando aprobación. | Campo | Tipo | Requerido | Descripción | |---|---|---|---| | `estado` | "requiere_confirmacion" | Sí | | | `operacion_id` | string | No | Úsalo en `GET /v1/confirmaciones/{id}` para saber si se aprobó. | | `confirmacion_url` | string (uri) | No | Enlace del panel donde una persona aprueba o rechaza. Pásaselo tal cual. | | `consulta_url` | string | Sí | Ruta para consultar el estado. | | `expira_en` | string (date-time) | No | Si nadie aprueba antes, la operación vence y no se hace. | | `mensaje` | string | Sí | Qué falta, en palabras para una persona. | | `recurso` | object | No | Lo que se creó y queda en proceso. | | `recurso.tipo` | "comprobante" \| "baja" \| "resumen" \| "guia" \| "sire_propuesta" \| "mensaje" \| "entrega" \| "clave" \| "conexion" \| "webhook" | No | | | `recurso.id` | string | No | | | `reintento_en` | string (date-time) | No | Próximo intento estimado, si aplica. | ### Errores Cada código tiene su explicación en [Errores](https://docs.opennexum.com/errores/). - **400** [`validacion`](https://docs.opennexum.com/errores#validacion) - **401** [`clave_invalida`](https://docs.opennexum.com/errores#clave_invalida) - **403** [`permiso_faltante`](https://docs.opennexum.com/errores#permiso_faltante) - **404** [`no_encontrado`](https://docs.opennexum.com/errores#no_encontrado) - **409** [`idempotencia_en_conflicto`](https://docs.opennexum.com/errores#idempotencia_en_conflicto) - **409** [`solicitud_en_curso`](https://docs.opennexum.com/errores#solicitud_en_curso) - **409** [`boveda_inactiva`](https://docs.opennexum.com/errores#boveda_inactiva) - **409** [`estado_no_permite`](https://docs.opennexum.com/errores#estado_no_permite) - **409** [`plazo_vencido`](https://docs.opennexum.com/errores#plazo_vencido) - **422** [`credenciales_sunat`](https://docs.opennexum.com/errores#credenciales_sunat) - **429** [`limite_uso`](https://docs.opennexum.com/errores#limite_uso) - **500** [`error_interno`](https://docs.opennexum.com/errores#error_interno) - **501** [`operacion_no_disponible`](https://docs.opennexum.com/errores#operacion_no_disponible) - **503** [`no_disponible`](https://docs.opennexum.com/errores#no_disponible) --- Fuente: https://docs.opennexum.com/referencia/comprobantes/comprobante_consultar_sunat/ # Pregunta a SUNAT el estado de un comprobante > Consulta el estado en SUNAT, guarda el CDR si llega y devuelve el comprobante actualizado. `POST /v1/emisores/{ruc}/comprobantes/{id}/consultar-sunat` Consulta el estado en SUNAT, guarda el CDR si llega y devuelve el comprobante actualizado. ## Ficha | Dato | Valor | |---|---| | Permiso | `comprobantes:leer` | | Cobro | No cobra. | | `Idempotency-Key` | No aplica | | Credenciales en la llamada | Si envías `credenciales`, la clave necesita `credenciales:por_llamada`. | | Herramienta MCP | `comprobante_consultar_sunat` (Próximamente) | ## Parámetros | Nombre | En | Requerido | Tipo | Descripción | |---|---|---|---|---| | `ruc` | path | Sí | string | RUC del emisor. | | `id` | path | Sí | string | Identificador que empieza con `cmp_`. | | `X-Request-Id` | header | No | string | Identificador de la petición. Va en cada respuesta; menciónalo al escribir a soporte. | ## Cuerpo `application/json`, opcional. Los campos anidados van con punto y los de listas con `[]`. No se aceptan campos desconocidos. | Campo | Tipo | Requerido | Descripción | |---|---|---|---| | `credenciales` | object | No | 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. | | `credenciales.sol` | object | Sí | Usuario secundario SOL del emisor. Nunca se guarda en registros ni se devuelve. | | `credenciales.sol.usuario` | string | Sí | Usuario secundario SOL, sin el RUC (lo agregamos con el RUC del emisor). | | `credenciales.sol.clave` | string (password) | Sí | Clave SOL del usuario secundario. | ## Ejemplo Contra el sandbox, con una clave `onx_test_…`: ```bash curl -X POST "https://api-sandbox.opennexum.com/v1/emisores/20000000001/comprobantes/cmp_8f2c1a7d9e/consultar-sunat" \ -H "Authorization: Bearer onx_test_…" \ -H "Content-Type: application/json" \ -d '{}' ``` ## Respuestas ### 200 Comprobante con el estado que dio SUNAT. | Campo | Tipo | Requerido | Descripción | |---|---|---|---| | `id` | string | Sí | Identificador que empieza con `cmp_`. | | `emisor_ruc` | string | Sí | RUC de 11 dígitos. Se valida el dígito verificador (módulo 11 de SUNAT). | | `tipo` | "01" \| "03" \| "07" \| "08" | Sí | 01 factura, 03 boleta, 07 nota de crédito, 08 nota de débito. | | `serie` | string | Sí | | | `numero` | integer | Sí | Asignado por el servidor. | | `numero_completo` | string | Sí | Serie y número, por ejemplo F001-124. | | `fecha_emision` | string (date) | Sí | Fecha AAAA-MM-DD (día en Lima). | | `moneda` | "PEN" \| "USD" | Sí | Código ISO 4217: PEN (soles) o USD (dólares). | | `tipo_cambio` | string \| null | Sí | | | `cliente` | object | Sí | A quién se le emite. | | `cliente.tipo_documento` | "0" \| "1" \| "4" \| "6" \| "7" | Sí | Catálogo 06: 0 sin documento, 1 DNI, 4 carné de extranjería, 6 RUC, 7 pasaporte. | | `cliente.numero_documento` | string | Sí | Número del documento; en tipo 0 puede ir «-». | | `cliente.nombre` | string | Sí | Razón social o nombre completo. | | `cliente.direccion` | string | No | | | `cliente.correo` | string (email) | No | Si lo envías, le mandamos el PDF y el XML. | | `items` | object[] | Sí | | | `items[].descripcion` | string | Sí | | | `items[].cantidad` | string | Sí | Cantidad como texto, mayor que cero, con hasta 6 decimales. | | `items[].unidad` | string | No | Unidad del catálogo 03, por ejemplo NIU (bienes) o ZZ (servicios). Por defecto NIU. | | `items[].codigo` | string | No | Tu código interno del producto. | | `items[].codigo_sunat` | string | No | Código de producto SUNAT (catálogo 25). | | `items[].precio_unitario` | string | Sí | 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). | | `items[].afectacion_igv` | "10" \| "11" \| "12" \| "13" \| "14" \| "15" \| "16" \| "20" \| "30" \| "31" \| "32" \| "33" \| "34" \| "35" \| "36" \| "37" | Sí | Catálogo 07: 10 gravado, 20 exonerado, 30 inafecto; 11–16 y 31–37 son transferencias gratuitas. | | `items[].icbper` | boolean | No | `true` si la línea son bolsas plásticas: se suma el ICBPER por bolsa. | | `forma_pago` | object \| object | Sí | Contado o crédito con cuotas. Si no la envías, es al contado. | | `totales` | object | Sí | Totales calculados por el servidor. | | `totales.gravado` | string | Sí | Monto como texto con dos decimales y punto decimal, sin separador de miles. "1250.50" es S/ 1,250.50. | | `totales.exonerado` | string | Sí | Monto como texto con dos decimales y punto decimal, sin separador de miles. "1250.50" es S/ 1,250.50. | | `totales.inafecto` | string | Sí | Monto como texto con dos decimales y punto decimal, sin separador de miles. "1250.50" es S/ 1,250.50. | | `totales.gratuito` | string | Sí | Monto como texto con dos decimales y punto decimal, sin separador de miles. "1250.50" es S/ 1,250.50. | | `totales.igv` | string | Sí | Monto como texto con dos decimales y punto decimal, sin separador de miles. "1250.50" es S/ 1,250.50. | | `totales.icbper` | string | Sí | Monto como texto con dos decimales y punto decimal, sin separador de miles. "1250.50" es S/ 1,250.50. | | `totales.total` | string | Sí | Importe total que paga el cliente. | | `referencia` | object \| null | Sí | | | `referencia.tipo` | "01" \| "03" | Sí | | | `referencia.serie` | string | Sí | | | `referencia.numero` | integer | Sí | | | `motivo` | object \| null | Sí | | | `motivo.codigo` | string | Sí | Catálogo 09 (crédito) o 10 (débito), por ejemplo 01. | | `motivo.descripcion` | string | Sí | | | `estado` | "en_cola" \| "aceptado" \| "observado" \| "rechazado" \| "en_baja" \| "anulado" | Sí | `en_cola`: guardado y esperando a SUNAT. `observado`: aceptado con observaciones. `en_baja`: anulación en curso. | | `sunat` | object \| null | Sí | | | `sunat.codigo` | string | Sí | Código de respuesta de SUNAT; 0 es aceptado. | | `sunat.descripcion` | string | Sí | | | `sunat.observaciones` | string[] | Sí | | | `hash` | string \| null | Sí | Valor del resumen (DigestValue) de la firma, el que va en el QR. | | `enlaces` | object | Sí | | | `enlaces.xml` | string | Sí | | | `enlaces.cdr` | string \| null | Sí | `null` mientras SUNAT no responde. | | `enlaces.pdf` | string | Sí | | | `creado_en` | string (date-time) | Sí | Fecha y hora ISO 8601 con la zona de Lima (-05:00). | | `actualizado_en` | string (date-time) | Sí | Fecha y hora ISO 8601 con la zona de Lima (-05:00). | ### Errores Cada código tiene su explicación en [Errores](https://docs.opennexum.com/errores/). - **400** [`validacion`](https://docs.opennexum.com/errores#validacion) - **401** [`clave_invalida`](https://docs.opennexum.com/errores#clave_invalida) - **403** [`permiso_faltante`](https://docs.opennexum.com/errores#permiso_faltante) - **404** [`no_encontrado`](https://docs.opennexum.com/errores#no_encontrado) - **409** [`boveda_inactiva`](https://docs.opennexum.com/errores#boveda_inactiva) - **422** [`credenciales_sunat`](https://docs.opennexum.com/errores#credenciales_sunat) - **429** [`limite_uso`](https://docs.opennexum.com/errores#limite_uso) - **500** [`error_interno`](https://docs.opennexum.com/errores#error_interno) - **501** [`operacion_no_disponible`](https://docs.opennexum.com/errores#operacion_no_disponible) - **502** [`servicio_externo_no_disponible`](https://docs.opennexum.com/errores#servicio_externo_no_disponible) - **503** [`no_disponible`](https://docs.opennexum.com/errores#no_disponible) --- Fuente: https://docs.opennexum.com/referencia/resumenes/resumen_crear/ # Envía el resumen diario de boletas > 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`. `POST /v1/emisores/{ruc}/resumenes` 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`. ## Ficha | Dato | Valor | |---|---| | Permiso | `comprobantes:emitir` | | Cobro | No cobra. | | `Idempotency-Key` | Obligatoria | | Credenciales en la llamada | Si envías `credenciales`, la clave necesita `credenciales:por_llamada`. | | Herramienta MCP | `resumen_crear` (Próximamente) | ## Parámetros | Nombre | En | Requerido | Tipo | Descripción | |---|---|---|---|---| | `ruc` | path | Sí | string | RUC del emisor o contribuyente. | | `Idempotency-Key` | header | Sí | string | 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. | | `X-Request-Id` | header | No | string | Identificador de la petición. Va en cada respuesta; menciónalo al escribir a soporte. | ## Cuerpo `application/json`, obligatorio. Los campos anidados van con punto y los de listas con `[]`. No se aceptan campos desconocidos. | Campo | Tipo | Requerido | Descripción | |---|---|---|---| | `fecha` | string (date) | Sí | Día de emisión de las boletas a informar. | | `credenciales` | object | No | 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. | | `credenciales.certificado` | object | Sí | Certificado digital del emisor. Nunca se guarda en registros ni se devuelve. | | `credenciales.certificado.pfx_base64` | string (base64) | Sí | Archivo .pfx o .p12 del certificado digital, en base64. | | `credenciales.certificado.clave` | string (password) | Sí | Contraseña del archivo .pfx. | | `credenciales.sol` | object | Sí | Usuario secundario SOL del emisor. Nunca se guarda en registros ni se devuelve. | | `credenciales.sol.usuario` | string | Sí | Usuario secundario SOL, sin el RUC (lo agregamos con el RUC del emisor). | | `credenciales.sol.clave` | string (password) | Sí | Clave SOL del usuario secundario. | ## Ejemplo Contra el sandbox, con una clave `onx_test_…`: ```bash curl -X POST "https://api-sandbox.opennexum.com/v1/emisores/20000000001/resumenes" \ -H "Authorization: Bearer onx_test_…" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "fecha": "2026-11-15" }' ``` ## Respuestas ### 202 Resumen en cola. | Campo | Tipo | Requerido | Descripción | |---|---|---|---| | `estado` | "en_cola" | Sí | | | `recurso` | object | Sí | Lo que se creó y queda en proceso. | | `recurso.tipo` | "comprobante" \| "baja" \| "resumen" \| "guia" \| "sire_propuesta" \| "mensaje" \| "entrega" \| "clave" \| "conexion" \| "webhook" | Sí | | | `recurso.id` | string | Sí | | | `consulta_url` | string | Sí | Ruta para consultar cómo va. | | `mensaje` | string | Sí | | | `reintento_en` | string (date-time) | No | Próximo intento estimado, si aplica. | ### Errores Cada código tiene su explicación en [Errores](https://docs.opennexum.com/errores/). - **400** [`validacion`](https://docs.opennexum.com/errores#validacion) - **401** [`clave_invalida`](https://docs.opennexum.com/errores#clave_invalida) - **403** [`permiso_faltante`](https://docs.opennexum.com/errores#permiso_faltante) - **404** [`no_encontrado`](https://docs.opennexum.com/errores#no_encontrado) - **409** [`idempotencia_en_conflicto`](https://docs.opennexum.com/errores#idempotencia_en_conflicto) - **409** [`solicitud_en_curso`](https://docs.opennexum.com/errores#solicitud_en_curso) - **409** [`boveda_inactiva`](https://docs.opennexum.com/errores#boveda_inactiva) - **409** [`plazo_vencido`](https://docs.opennexum.com/errores#plazo_vencido) - **422** [`credenciales_sunat`](https://docs.opennexum.com/errores#credenciales_sunat) - **429** [`limite_uso`](https://docs.opennexum.com/errores#limite_uso) - **500** [`error_interno`](https://docs.opennexum.com/errores#error_interno) - **501** [`operacion_no_disponible`](https://docs.opennexum.com/errores#operacion_no_disponible) - **503** [`no_disponible`](https://docs.opennexum.com/errores#no_disponible) --- Fuente: https://docs.opennexum.com/referencia/resumenes/resumen_listar/ # Lista resúmenes y comunicaciones de baja > Resúmenes diarios (RC) y comunicaciones de baja (RA) del emisor, con su estado en SUNAT. `GET /v1/emisores/{ruc}/resumenes` Resúmenes diarios (RC) y comunicaciones de baja (RA) del emisor, con su estado en SUNAT. ## Ficha | Dato | Valor | |---|---| | Permiso | `comprobantes:leer` | | Cobro | No cobra. | | `Idempotency-Key` | No aplica | | Herramienta MCP | `resumen_listar` (Próximamente) | ## Parámetros | Nombre | En | Requerido | Tipo | Descripción | |---|---|---|---|---| | `ruc` | path | Sí | string | RUC del emisor o contribuyente. | | `cursor` | query | No | string | Cursor opaco que devolvió la página anterior en `siguiente_cursor`. | | `limite` | query | No | integer | Cuántos elementos traer (1 a 100; por defecto 20). | | `desde` | query | No | string | Fecha AAAA-MM-DD (día en Lima). | | `hasta` | query | No | string | Fecha AAAA-MM-DD (día en Lima). | | `X-Request-Id` | header | No | string | Identificador de la petición. Va en cada respuesta; menciónalo al escribir a soporte. | ## Ejemplo Contra el sandbox, con una clave `onx_test_…`: ```bash curl "https://api-sandbox.opennexum.com/v1/emisores/20000000001/resumenes" \ -H "Authorization: Bearer onx_test_…" ``` ## Respuestas ### 200 Página de resúmenes. | Campo | Tipo | Requerido | Descripción | |---|---|---|---| | `elementos` | object[] | Sí | | | `elementos[].id` | string | Sí | Identificador que empieza con `res_`. | | `elementos[].emisor_ruc` | string | Sí | RUC de 11 dígitos. Se valida el dígito verificador (módulo 11 de SUNAT). | | `elementos[].tipo` | "RC" \| "RA" | Sí | RC resumen diario; RA comunicación de baja. | | `elementos[].fecha_referencia` | string (date) | Sí | Fecha AAAA-MM-DD (día en Lima). | | `elementos[].estado` | "en_cola" \| "enviado" \| "aceptado" \| "rechazado" | Sí | | | `elementos[].ticket` | string \| null | Sí | Ticket que dio SUNAT al recibirlo. | | `elementos[].cantidad_comprobantes` | integer | Sí | | | `elementos[].sunat` | object \| null | Sí | | | `elementos[].sunat.codigo` | string | Sí | Código de respuesta de SUNAT; 0 es aceptado. | | `elementos[].sunat.descripcion` | string | Sí | | | `elementos[].sunat.observaciones` | string[] | Sí | | | `elementos[].creado_en` | string (date-time) | Sí | Fecha y hora ISO 8601 con la zona de Lima (-05:00). | | `elementos[].actualizado_en` | string (date-time) | Sí | Fecha y hora ISO 8601 con la zona de Lima (-05:00). | | `siguiente_cursor` | string \| null | Sí | Pásalo como `cursor` para la página siguiente; `null` si ya no hay más. | ### Errores Cada código tiene su explicación en [Errores](https://docs.opennexum.com/errores/). - **400** [`validacion`](https://docs.opennexum.com/errores#validacion) - **401** [`clave_invalida`](https://docs.opennexum.com/errores#clave_invalida) - **403** [`permiso_faltante`](https://docs.opennexum.com/errores#permiso_faltante) - **404** [`no_encontrado`](https://docs.opennexum.com/errores#no_encontrado) - **429** [`limite_uso`](https://docs.opennexum.com/errores#limite_uso) - **500** [`error_interno`](https://docs.opennexum.com/errores#error_interno) - **501** [`operacion_no_disponible`](https://docs.opennexum.com/errores#operacion_no_disponible) - **503** [`no_disponible`](https://docs.opennexum.com/errores#no_disponible) --- Fuente: https://docs.opennexum.com/referencia/resumenes/resumen_ver/ # Consulta un resumen > Estado de un resumen diario o de una comunicación de baja, con el ticket y la respuesta de SUNAT. `GET /v1/emisores/{ruc}/resumenes/{id}` Estado de un resumen diario o de una comunicación de baja, con el ticket y la respuesta de SUNAT. ## Ficha | Dato | Valor | |---|---| | Permiso | `comprobantes:leer` | | Cobro | No cobra. | | `Idempotency-Key` | No aplica | | Herramienta MCP | `resumen_ver` (Próximamente) | ## Parámetros | Nombre | En | Requerido | Tipo | Descripción | |---|---|---|---|---| | `ruc` | path | Sí | string | RUC del emisor. | | `id` | path | Sí | string | Identificador que empieza con `res_`. | | `X-Request-Id` | header | No | string | Identificador de la petición. Va en cada respuesta; menciónalo al escribir a soporte. | ## Ejemplo Contra el sandbox, con una clave `onx_test_…`: ```bash curl "https://api-sandbox.opennexum.com/v1/emisores/20000000001/resumenes/res_8f2c1a7d9e" \ -H "Authorization: Bearer onx_test_…" ``` ## Respuestas ### 200 Resumen. | Campo | Tipo | Requerido | Descripción | |---|---|---|---| | `id` | string | Sí | Identificador que empieza con `res_`. | | `emisor_ruc` | string | Sí | RUC de 11 dígitos. Se valida el dígito verificador (módulo 11 de SUNAT). | | `tipo` | "RC" \| "RA" | Sí | RC resumen diario; RA comunicación de baja. | | `fecha_referencia` | string (date) | Sí | Fecha AAAA-MM-DD (día en Lima). | | `estado` | "en_cola" \| "enviado" \| "aceptado" \| "rechazado" | Sí | | | `ticket` | string \| null | Sí | Ticket que dio SUNAT al recibirlo. | | `cantidad_comprobantes` | integer | Sí | | | `sunat` | object \| null | Sí | | | `sunat.codigo` | string | Sí | Código de respuesta de SUNAT; 0 es aceptado. | | `sunat.descripcion` | string | Sí | | | `sunat.observaciones` | string[] | Sí | | | `creado_en` | string (date-time) | Sí | Fecha y hora ISO 8601 con la zona de Lima (-05:00). | | `actualizado_en` | string (date-time) | Sí | Fecha y hora ISO 8601 con la zona de Lima (-05:00). | ### Errores Cada código tiene su explicación en [Errores](https://docs.opennexum.com/errores/). - **400** [`validacion`](https://docs.opennexum.com/errores#validacion) - **401** [`clave_invalida`](https://docs.opennexum.com/errores#clave_invalida) - **403** [`permiso_faltante`](https://docs.opennexum.com/errores#permiso_faltante) - **404** [`no_encontrado`](https://docs.opennexum.com/errores#no_encontrado) - **429** [`limite_uso`](https://docs.opennexum.com/errores#limite_uso) - **500** [`error_interno`](https://docs.opennexum.com/errores#error_interno) - **501** [`operacion_no_disponible`](https://docs.opennexum.com/errores#operacion_no_disponible) - **503** [`no_disponible`](https://docs.opennexum.com/errores#no_disponible) --- Fuente: https://docs.opennexum.com/referencia/guias/guia_emitir/ # Emite una guía de remisión remitente > 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`. `POST /v1/emisores/{ruc}/guias` 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`. ## Ficha | Dato | Valor | |---|---| | Permiso | `guias:emitir` | | Cobro | Reserva el precio de tu saldo y lo cobra solo si el servicio confirma (por ejemplo, SUNAT acepta). | | `Idempotency-Key` | Obligatoria | | Credenciales en la llamada | Si envías `credenciales`, la clave necesita `credenciales:por_llamada`. | | Herramienta MCP | `guia_emitir` (Próximamente) | ## Parámetros | Nombre | En | Requerido | Tipo | Descripción | |---|---|---|---|---| | `ruc` | path | Sí | string | RUC del emisor o contribuyente. | | `Idempotency-Key` | header | Sí | string | 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. | | `X-Request-Id` | header | No | string | Identificador de la petición. Va en cada respuesta; menciónalo al escribir a soporte. | ## Cuerpo `application/json`, obligatorio. Los campos anidados van con punto y los de listas con `[]`. No se aceptan campos desconocidos. | Campo | Tipo | Requerido | Descripción | |---|---|---|---| | `serie` | string | Sí | | | `fecha_emision` | string (date) | No | Fecha AAAA-MM-DD (día en Lima). | | `destinatario` | object | Sí | | | `destinatario.tipo_documento` | "1" \| "4" \| "6" \| "7" | Sí | | | `destinatario.numero_documento` | string | Sí | | | `destinatario.nombre` | string | Sí | | | `motivo_traslado` | object | Sí | | | `motivo_traslado.codigo` | string | Sí | Catálogo 20, por ejemplo 01 venta. | | `motivo_traslado.descripcion` | string | No | | | `peso_bruto_kg` | string | Sí | | | `numero_bultos` | integer | No | | | `modalidad` | "01" \| "02" | Sí | Catálogo 18: 01 transporte público, 02 transporte privado. | | `fecha_inicio_traslado` | string (date) | Sí | Fecha AAAA-MM-DD (día en Lima). | | `transportista` | object | No | Obligatorio en transporte público (01). | | `transportista.ruc` | string | Sí | RUC de 11 dígitos. Se valida el dígito verificador (módulo 11 de SUNAT). | | `transportista.razon_social` | string | Sí | | | `transportista.registro_mtc` | string | No | | | `conductores` | object[] | No | Obligatorio en transporte privado (02). | | `conductores[].tipo_documento` | "1" \| "4" \| "7" | Sí | | | `conductores[].numero_documento` | string | Sí | | | `conductores[].nombres` | string | Sí | | | `conductores[].apellidos` | string | Sí | | | `conductores[].licencia` | string | Sí | | | `vehiculos` | object[] | No | Obligatorio en transporte privado (02). | | `vehiculos[].placa` | string | Sí | | | `partida` | object | Sí | | | `partida.ubigeo` | string | Sí | Ubigeo INEI de 6 dígitos. | | `partida.direccion` | string | Sí | | | `partida.codigo_establecimiento` | string | No | | | `llegada` | object | Sí | | | `llegada.ubigeo` | string | Sí | Ubigeo INEI de 6 dígitos. | | `llegada.direccion` | string | Sí | | | `llegada.codigo_establecimiento` | string | No | | | `items` | object[] | Sí | | | `items[].descripcion` | string | Sí | | | `items[].cantidad` | string | Sí | Cantidad como texto, mayor que cero, con hasta 6 decimales. | | `items[].unidad` | string | No | | | `items[].codigo` | string | No | | | `documentos_relacionados` | object[] | No | | | `documentos_relacionados[].tipo` | "01" \| "03" | Sí | | | `documentos_relacionados[].serie` | string | Sí | | | `documentos_relacionados[].numero` | integer | Sí | | | `credenciales` | object | No | 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. | | `credenciales.certificado` | object | Sí | Certificado digital del emisor. Nunca se guarda en registros ni se devuelve. | | `credenciales.certificado.pfx_base64` | string (base64) | Sí | Archivo .pfx o .p12 del certificado digital, en base64. | | `credenciales.certificado.clave` | string (password) | Sí | Contraseña del archivo .pfx. | | `credenciales.sol` | object | Sí | Usuario secundario SOL del emisor. Nunca se guarda en registros ni se devuelve. | | `credenciales.sol.usuario` | string | Sí | Usuario secundario SOL, sin el RUC (lo agregamos con el RUC del emisor). | | `credenciales.sol.clave` | string (password) | Sí | Clave SOL del usuario secundario. | | `credenciales.api_sunat` | object | Sí | Credenciales de la API de SUNAT (guías y SIRE), generadas en SOL. Nunca se guarda en registros ni se devuelve. | | `credenciales.api_sunat.client_id` | string | Sí | | | `credenciales.api_sunat.client_secret` | string (password) | Sí | | ## Ejemplo Contra el sandbox, con una clave `onx_test_…`: ```bash curl -X POST "https://api-sandbox.opennexum.com/v1/emisores/20000000001/guias" \ -H "Authorization: Bearer onx_test_…" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "serie": "texto", "destinatario": { "tipo_documento": "1", "numero_documento": "texto", "nombre": "texto" }, "motivo_traslado": { "codigo": "texto" }, "peso_bruto_kg": "texto", "modalidad": "01", "fecha_inicio_traslado": "2026-11-15", "partida": { "ubigeo": "150101", "direccion": "texto" }, "llegada": { "ubigeo": "150101", "direccion": "texto" }, "items": [ { "descripcion": "texto", "cantidad": "2" } ] }' ``` ## Respuestas ### 201 Guía aceptada por SUNAT. | Campo | Tipo | Requerido | Descripción | |---|---|---|---| | `id` | string | Sí | Identificador que empieza con `gre_`. | | `emisor_ruc` | string | Sí | RUC de 11 dígitos. Se valida el dígito verificador (módulo 11 de SUNAT). | | `serie` | string | Sí | | | `numero` | integer | Sí | | | `numero_completo` | string | Sí | | | `fecha_emision` | string (date) | Sí | Fecha AAAA-MM-DD (día en Lima). | | `estado` | "en_cola" \| "aceptada" \| "rechazada" | Sí | | | `destinatario` | object | Sí | | | `destinatario.tipo_documento` | string | Sí | | | `destinatario.numero_documento` | string | Sí | | | `destinatario.nombre` | string | Sí | | | `sunat` | object \| null | Sí | | | `sunat.codigo` | string | Sí | Código de respuesta de SUNAT; 0 es aceptado. | | `sunat.descripcion` | string | Sí | | | `sunat.observaciones` | string[] | Sí | | | `enlaces` | object | Sí | | | `enlaces.xml` | string | Sí | | | `enlaces.cdr` | string \| null | Sí | | | `enlaces.pdf` | string | Sí | | | `creada_en` | string (date-time) | Sí | Fecha y hora ISO 8601 con la zona de Lima (-05:00). | | `actualizada_en` | string (date-time) | Sí | Fecha y hora ISO 8601 con la zona de Lima (-05:00). | ### 202 Guía en cola. | Campo | Tipo | Requerido | Descripción | |---|---|---|---| | `estado` | "en_cola" | Sí | | | `recurso` | object | Sí | Lo que se creó y queda en proceso. | | `recurso.tipo` | "comprobante" \| "baja" \| "resumen" \| "guia" \| "sire_propuesta" \| "mensaje" \| "entrega" \| "clave" \| "conexion" \| "webhook" | Sí | | | `recurso.id` | string | Sí | | | `consulta_url` | string | Sí | Ruta para consultar cómo va. | | `mensaje` | string | Sí | | | `reintento_en` | string (date-time) | No | Próximo intento estimado, si aplica. | ### Errores Cada código tiene su explicación en [Errores](https://docs.opennexum.com/errores/). - **400** [`validacion`](https://docs.opennexum.com/errores#validacion) - **401** [`clave_invalida`](https://docs.opennexum.com/errores#clave_invalida) - **402** [`saldo_insuficiente`](https://docs.opennexum.com/errores#saldo_insuficiente) - **402** [`tope_alcanzado`](https://docs.opennexum.com/errores#tope_alcanzado) - **403** [`permiso_faltante`](https://docs.opennexum.com/errores#permiso_faltante) - **403** [`emisor_obligado_ose`](https://docs.opennexum.com/errores#emisor_obligado_ose) - **404** [`no_encontrado`](https://docs.opennexum.com/errores#no_encontrado) - **409** [`idempotencia_en_conflicto`](https://docs.opennexum.com/errores#idempotencia_en_conflicto) - **409** [`solicitud_en_curso`](https://docs.opennexum.com/errores#solicitud_en_curso) - **409** [`boveda_inactiva`](https://docs.opennexum.com/errores#boveda_inactiva) - **422** [`sunat_rechazo`](https://docs.opennexum.com/errores#sunat_rechazo) - **422** [`credenciales_sunat`](https://docs.opennexum.com/errores#credenciales_sunat) - **429** [`limite_uso`](https://docs.opennexum.com/errores#limite_uso) - **500** [`error_interno`](https://docs.opennexum.com/errores#error_interno) - **501** [`operacion_no_disponible`](https://docs.opennexum.com/errores#operacion_no_disponible) - **503** [`no_disponible`](https://docs.opennexum.com/errores#no_disponible) --- Fuente: https://docs.opennexum.com/referencia/guias/guia_listar/ # Lista guías de un emisor > Guías de remisión del emisor, de la más reciente a la más antigua. `GET /v1/emisores/{ruc}/guias` Guías de remisión del emisor, de la más reciente a la más antigua. ## Ficha | Dato | Valor | |---|---| | Permiso | `comprobantes:leer` | | Cobro | No cobra. | | `Idempotency-Key` | No aplica | | Herramienta MCP | `guia_listar` (Próximamente) | ## Parámetros | Nombre | En | Requerido | Tipo | Descripción | |---|---|---|---|---| | `ruc` | path | Sí | string | RUC del emisor o contribuyente. | | `cursor` | query | No | string | Cursor opaco que devolvió la página anterior en `siguiente_cursor`. | | `limite` | query | No | integer | Cuántos elementos traer (1 a 100; por defecto 20). | | `X-Request-Id` | header | No | string | Identificador de la petición. Va en cada respuesta; menciónalo al escribir a soporte. | ## Ejemplo Contra el sandbox, con una clave `onx_test_…`: ```bash curl "https://api-sandbox.opennexum.com/v1/emisores/20000000001/guias" \ -H "Authorization: Bearer onx_test_…" ``` ## Respuestas ### 200 Página de guías. | Campo | Tipo | Requerido | Descripción | |---|---|---|---| | `elementos` | object[] | Sí | | | `elementos[].id` | string | Sí | Identificador que empieza con `gre_`. | | `elementos[].emisor_ruc` | string | Sí | RUC de 11 dígitos. Se valida el dígito verificador (módulo 11 de SUNAT). | | `elementos[].serie` | string | Sí | | | `elementos[].numero` | integer | Sí | | | `elementos[].numero_completo` | string | Sí | | | `elementos[].fecha_emision` | string (date) | Sí | Fecha AAAA-MM-DD (día en Lima). | | `elementos[].estado` | "en_cola" \| "aceptada" \| "rechazada" | Sí | | | `elementos[].destinatario` | object | Sí | | | `elementos[].destinatario.tipo_documento` | string | Sí | | | `elementos[].destinatario.numero_documento` | string | Sí | | | `elementos[].destinatario.nombre` | string | Sí | | | `elementos[].sunat` | object \| null | Sí | | | `elementos[].sunat.codigo` | string | Sí | Código de respuesta de SUNAT; 0 es aceptado. | | `elementos[].sunat.descripcion` | string | Sí | | | `elementos[].sunat.observaciones` | string[] | Sí | | | `elementos[].enlaces` | object | Sí | | | `elementos[].enlaces.xml` | string | Sí | | | `elementos[].enlaces.cdr` | string \| null | Sí | | | `elementos[].enlaces.pdf` | string | Sí | | | `elementos[].creada_en` | string (date-time) | Sí | Fecha y hora ISO 8601 con la zona de Lima (-05:00). | | `elementos[].actualizada_en` | string (date-time) | Sí | Fecha y hora ISO 8601 con la zona de Lima (-05:00). | | `siguiente_cursor` | string \| null | Sí | Pásalo como `cursor` para la página siguiente; `null` si ya no hay más. | ### Errores Cada código tiene su explicación en [Errores](https://docs.opennexum.com/errores/). - **400** [`validacion`](https://docs.opennexum.com/errores#validacion) - **401** [`clave_invalida`](https://docs.opennexum.com/errores#clave_invalida) - **403** [`permiso_faltante`](https://docs.opennexum.com/errores#permiso_faltante) - **404** [`no_encontrado`](https://docs.opennexum.com/errores#no_encontrado) - **429** [`limite_uso`](https://docs.opennexum.com/errores#limite_uso) - **500** [`error_interno`](https://docs.opennexum.com/errores#error_interno) - **501** [`operacion_no_disponible`](https://docs.opennexum.com/errores#operacion_no_disponible) - **503** [`no_disponible`](https://docs.opennexum.com/errores#no_disponible) --- Fuente: https://docs.opennexum.com/referencia/guias/guia_ver/ # Consulta una guía > Detalle y estado ante SUNAT de una guía de remisión. `GET /v1/emisores/{ruc}/guias/{id}` Detalle y estado ante SUNAT de una guía de remisión. ## Ficha | Dato | Valor | |---|---| | Permiso | `comprobantes:leer` | | Cobro | No cobra. | | `Idempotency-Key` | No aplica | | Herramienta MCP | `guia_ver` (Próximamente) | ## Parámetros | Nombre | En | Requerido | Tipo | Descripción | |---|---|---|---|---| | `ruc` | path | Sí | string | RUC del emisor. | | `id` | path | Sí | string | Identificador que empieza con `gre_`. | | `X-Request-Id` | header | No | string | Identificador de la petición. Va en cada respuesta; menciónalo al escribir a soporte. | ## Ejemplo Contra el sandbox, con una clave `onx_test_…`: ```bash curl "https://api-sandbox.opennexum.com/v1/emisores/20000000001/guias/gre_8f2c1a7d9e" \ -H "Authorization: Bearer onx_test_…" ``` ## Respuestas ### 200 Guía. | Campo | Tipo | Requerido | Descripción | |---|---|---|---| | `id` | string | Sí | Identificador que empieza con `gre_`. | | `emisor_ruc` | string | Sí | RUC de 11 dígitos. Se valida el dígito verificador (módulo 11 de SUNAT). | | `serie` | string | Sí | | | `numero` | integer | Sí | | | `numero_completo` | string | Sí | | | `fecha_emision` | string (date) | Sí | Fecha AAAA-MM-DD (día en Lima). | | `estado` | "en_cola" \| "aceptada" \| "rechazada" | Sí | | | `destinatario` | object | Sí | | | `destinatario.tipo_documento` | string | Sí | | | `destinatario.numero_documento` | string | Sí | | | `destinatario.nombre` | string | Sí | | | `sunat` | object \| null | Sí | | | `sunat.codigo` | string | Sí | Código de respuesta de SUNAT; 0 es aceptado. | | `sunat.descripcion` | string | Sí | | | `sunat.observaciones` | string[] | Sí | | | `enlaces` | object | Sí | | | `enlaces.xml` | string | Sí | | | `enlaces.cdr` | string \| null | Sí | | | `enlaces.pdf` | string | Sí | | | `creada_en` | string (date-time) | Sí | Fecha y hora ISO 8601 con la zona de Lima (-05:00). | | `actualizada_en` | string (date-time) | Sí | Fecha y hora ISO 8601 con la zona de Lima (-05:00). | ### Errores Cada código tiene su explicación en [Errores](https://docs.opennexum.com/errores/). - **400** [`validacion`](https://docs.opennexum.com/errores#validacion) - **401** [`clave_invalida`](https://docs.opennexum.com/errores#clave_invalida) - **403** [`permiso_faltante`](https://docs.opennexum.com/errores#permiso_faltante) - **404** [`no_encontrado`](https://docs.opennexum.com/errores#no_encontrado) - **429** [`limite_uso`](https://docs.opennexum.com/errores#limite_uso) - **500** [`error_interno`](https://docs.opennexum.com/errores#error_interno) - **501** [`operacion_no_disponible`](https://docs.opennexum.com/errores#operacion_no_disponible) - **503** [`no_disponible`](https://docs.opennexum.com/errores#no_disponible) --- Fuente: https://docs.opennexum.com/referencia/sire/sire_propuesta_pedir/ # Pide la propuesta del SIRE de un periodo > 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`. `POST /v1/emisores/{ruc}/sire/propuestas` 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`. ## Ficha | Dato | Valor | |---|---| | Permiso | `sire:leer` | | Cobro | Reserva el precio de tu saldo y lo cobra solo si el servicio confirma (por ejemplo, SUNAT acepta). | | `Idempotency-Key` | Obligatoria | | Credenciales en la llamada | Si envías `credenciales`, la clave necesita `credenciales:por_llamada`. | | Herramienta MCP | `sire_propuesta_pedir` (Próximamente) | ## Parámetros | Nombre | En | Requerido | Tipo | Descripción | |---|---|---|---|---| | `ruc` | path | Sí | string | RUC del emisor o contribuyente. | | `Idempotency-Key` | header | Sí | string | 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. | | `X-Request-Id` | header | No | string | Identificador de la petición. Va en cada respuesta; menciónalo al escribir a soporte. | ## Cuerpo `application/json`, obligatorio. Los campos anidados van con punto y los de listas con `[]`. No se aceptan campos desconocidos. | Campo | Tipo | Requerido | Descripción | |---|---|---|---| | `registro` | "RVIE" \| "RCE" | Sí | RVIE ventas e ingresos; RCE compras. | | `periodo` | string | Sí | Periodo tributario AAAAMM. | | `credenciales` | object | No | 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. | | `credenciales.sol` | object | Sí | Usuario secundario SOL del emisor. Nunca se guarda en registros ni se devuelve. | | `credenciales.sol.usuario` | string | Sí | Usuario secundario SOL, sin el RUC (lo agregamos con el RUC del emisor). | | `credenciales.sol.clave` | string (password) | Sí | Clave SOL del usuario secundario. | | `credenciales.api_sunat` | object | Sí | Credenciales de la API de SUNAT (guías y SIRE), generadas en SOL. Nunca se guarda en registros ni se devuelve. | | `credenciales.api_sunat.client_id` | string | Sí | | | `credenciales.api_sunat.client_secret` | string (password) | Sí | | ## Ejemplo Contra el sandbox, con una clave `onx_test_…`: ```bash curl -X POST "https://api-sandbox.opennexum.com/v1/emisores/20000000001/sire/propuestas" \ -H "Authorization: Bearer onx_test_…" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "registro": "RVIE", "periodo": "202611" }' ``` ## Respuestas ### 202 Propuesta en cola. | Campo | Tipo | Requerido | Descripción | |---|---|---|---| | `estado` | "en_cola" | Sí | | | `recurso` | object | Sí | Lo que se creó y queda en proceso. | | `recurso.tipo` | "comprobante" \| "baja" \| "resumen" \| "guia" \| "sire_propuesta" \| "mensaje" \| "entrega" \| "clave" \| "conexion" \| "webhook" | Sí | | | `recurso.id` | string | Sí | | | `consulta_url` | string | Sí | Ruta para consultar cómo va. | | `mensaje` | string | Sí | | | `reintento_en` | string (date-time) | No | Próximo intento estimado, si aplica. | ### Errores Cada código tiene su explicación en [Errores](https://docs.opennexum.com/errores/). - **400** [`validacion`](https://docs.opennexum.com/errores#validacion) - **401** [`clave_invalida`](https://docs.opennexum.com/errores#clave_invalida) - **402** [`saldo_insuficiente`](https://docs.opennexum.com/errores#saldo_insuficiente) - **402** [`tope_alcanzado`](https://docs.opennexum.com/errores#tope_alcanzado) - **403** [`permiso_faltante`](https://docs.opennexum.com/errores#permiso_faltante) - **404** [`no_encontrado`](https://docs.opennexum.com/errores#no_encontrado) - **409** [`idempotencia_en_conflicto`](https://docs.opennexum.com/errores#idempotencia_en_conflicto) - **409** [`solicitud_en_curso`](https://docs.opennexum.com/errores#solicitud_en_curso) - **409** [`boveda_inactiva`](https://docs.opennexum.com/errores#boveda_inactiva) - **422** [`credenciales_sunat`](https://docs.opennexum.com/errores#credenciales_sunat) - **429** [`limite_uso`](https://docs.opennexum.com/errores#limite_uso) - **500** [`error_interno`](https://docs.opennexum.com/errores#error_interno) - **501** [`operacion_no_disponible`](https://docs.opennexum.com/errores#operacion_no_disponible) - **502** [`servicio_externo_no_disponible`](https://docs.opennexum.com/errores#servicio_externo_no_disponible) - **503** [`no_disponible`](https://docs.opennexum.com/errores#no_disponible) --- Fuente: https://docs.opennexum.com/referencia/sire/sire_propuesta_ver/ # Consulta una propuesta del SIRE > Estado de la propuesta y, cuando está `lista`, sus totales. `GET /v1/emisores/{ruc}/sire/propuestas/{id}` Estado de la propuesta y, cuando está `lista`, sus totales. ## Ficha | Dato | Valor | |---|---| | Permiso | `sire:leer` | | Cobro | No cobra. | | `Idempotency-Key` | No aplica | | Herramienta MCP | `sire_propuesta_ver` (Próximamente) | ## Parámetros | Nombre | En | Requerido | Tipo | Descripción | |---|---|---|---|---| | `ruc` | path | Sí | string | RUC del emisor. | | `id` | path | Sí | string | Identificador que empieza con `sire_`. | | `X-Request-Id` | header | No | string | Identificador de la petición. Va en cada respuesta; menciónalo al escribir a soporte. | ## Ejemplo Contra el sandbox, con una clave `onx_test_…`: ```bash curl "https://api-sandbox.opennexum.com/v1/emisores/20000000001/sire/propuestas/sire_8f2c1a7d9e" \ -H "Authorization: Bearer onx_test_…" ``` ## Respuestas ### 200 Propuesta. | Campo | Tipo | Requerido | Descripción | |---|---|---|---| | `id` | string | Sí | Identificador que empieza con `sire_`. | | `emisor_ruc` | string | Sí | RUC de 11 dígitos. Se valida el dígito verificador (módulo 11 de SUNAT). | | `registro` | "RVIE" \| "RCE" | Sí | RVIE ventas e ingresos; RCE compras. | | `periodo` | string | Sí | Periodo tributario AAAAMM. | | `estado` | "en_cola" \| "procesando" \| "lista" \| "sin_datos" \| "error" | Sí | | | `resumen` | object \| null | Sí | | | `resumen.cantidad` | integer | Sí | | | `resumen.base_imponible` | string | Sí | Monto con dos decimales; negativo en notas de crédito. | | `resumen.igv` | string | Sí | Monto con dos decimales; negativo en notas de crédito. | | `resumen.total` | string | Sí | Monto con dos decimales; negativo en notas de crédito. | | `error` | object \| null | Sí | | | `error.mensaje` | string | Sí | | | `creada_en` | string (date-time) | Sí | Fecha y hora ISO 8601 con la zona de Lima (-05:00). | | `actualizada_en` | string (date-time) | Sí | Fecha y hora ISO 8601 con la zona de Lima (-05:00). | ### Errores Cada código tiene su explicación en [Errores](https://docs.opennexum.com/errores/). - **400** [`validacion`](https://docs.opennexum.com/errores#validacion) - **401** [`clave_invalida`](https://docs.opennexum.com/errores#clave_invalida) - **403** [`permiso_faltante`](https://docs.opennexum.com/errores#permiso_faltante) - **404** [`no_encontrado`](https://docs.opennexum.com/errores#no_encontrado) - **429** [`limite_uso`](https://docs.opennexum.com/errores#limite_uso) - **500** [`error_interno`](https://docs.opennexum.com/errores#error_interno) - **501** [`operacion_no_disponible`](https://docs.opennexum.com/errores#operacion_no_disponible) - **503** [`no_disponible`](https://docs.opennexum.com/errores#no_disponible) --- Fuente: https://docs.opennexum.com/referencia/sire/sire_registros_listar/ # Lista las líneas de una propuesta del SIRE > Comprobantes de la propuesta, normalizados. Solo cuando la propuesta está `lista`. `GET /v1/emisores/{ruc}/sire/propuestas/{id}/registros` Comprobantes de la propuesta, normalizados. Solo cuando la propuesta está `lista`. ## Ficha | Dato | Valor | |---|---| | Permiso | `sire:leer` | | Cobro | No cobra. | | `Idempotency-Key` | No aplica | | Herramienta MCP | `sire_registros_listar` (Próximamente) | ## Parámetros | Nombre | En | Requerido | Tipo | Descripción | |---|---|---|---|---| | `ruc` | path | Sí | string | RUC del emisor. | | `id` | path | Sí | string | Identificador que empieza con `sire_`. | | `cursor` | query | No | string | Cursor opaco que devolvió la página anterior en `siguiente_cursor`. | | `limite` | query | No | integer | Cuántos elementos traer (1 a 100; por defecto 20). | | `X-Request-Id` | header | No | string | Identificador de la petición. Va en cada respuesta; menciónalo al escribir a soporte. | ## Ejemplo Contra el sandbox, con una clave `onx_test_…`: ```bash curl "https://api-sandbox.opennexum.com/v1/emisores/20000000001/sire/propuestas/sire_8f2c1a7d9e/registros" \ -H "Authorization: Bearer onx_test_…" ``` ## Respuestas ### 200 Página de líneas. | Campo | Tipo | Requerido | Descripción | |---|---|---|---| | `elementos` | object[] | Sí | | | `elementos[].tipo_comprobante` | string | Sí | | | `elementos[].serie` | string | Sí | | | `elementos[].numero` | string | Sí | | | `elementos[].fecha_emision` | string (date) | Sí | Fecha AAAA-MM-DD (día en Lima). | | `elementos[].contraparte` | object | Sí | | | `elementos[].contraparte.tipo_documento` | string | Sí | | | `elementos[].contraparte.numero_documento` | string | Sí | | | `elementos[].contraparte.nombre` | string | Sí | | | `elementos[].moneda` | string | Sí | | | `elementos[].tipo_cambio` | string \| null | Sí | | | `elementos[].base_imponible` | string | Sí | Monto con dos decimales; negativo en notas de crédito. | | `elementos[].igv` | string | Sí | Monto con dos decimales; negativo en notas de crédito. | | `elementos[].no_gravado` | string | Sí | Monto con dos decimales; negativo en notas de crédito. | | `elementos[].total` | string | Sí | Monto con dos decimales; negativo en notas de crédito. | | `siguiente_cursor` | string \| null | Sí | Pásalo como `cursor` para la página siguiente; `null` si ya no hay más. | ### Errores Cada código tiene su explicación en [Errores](https://docs.opennexum.com/errores/). - **400** [`validacion`](https://docs.opennexum.com/errores#validacion) - **401** [`clave_invalida`](https://docs.opennexum.com/errores#clave_invalida) - **403** [`permiso_faltante`](https://docs.opennexum.com/errores#permiso_faltante) - **404** [`no_encontrado`](https://docs.opennexum.com/errores#no_encontrado) - **409** [`estado_no_permite`](https://docs.opennexum.com/errores#estado_no_permite) - **429** [`limite_uso`](https://docs.opennexum.com/errores#limite_uso) - **500** [`error_interno`](https://docs.opennexum.com/errores#error_interno) - **501** [`operacion_no_disponible`](https://docs.opennexum.com/errores#operacion_no_disponible) - **503** [`no_disponible`](https://docs.opennexum.com/errores#no_disponible) --- Fuente: https://docs.opennexum.com/referencia/conexiones/conexion_crear/ # Crea una conexión de WhatsApp, Instagram o Messenger > 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. `POST /v1/conecta/conexiones` 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. ## Ficha | Dato | Valor | |---|---| | Permiso | `conecta:administrar` | | Cobro | No cobra. | | `Idempotency-Key` | Opcional | | Herramienta MCP | `conexion_crear` (Próximamente) | ## Parámetros | Nombre | En | Requerido | Tipo | Descripción | |---|---|---|---|---| | `Idempotency-Key` | header | No | string | 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. | | `X-Request-Id` | header | No | string | Identificador de la petición. Va en cada respuesta; menciónalo al escribir a soporte. | ## Cuerpo `application/json`, obligatorio. Los campos anidados van con punto y los de listas con `[]`. No se aceptan campos desconocidos. | Campo | Tipo | Requerido | Descripción | |---|---|---|---| | `proveedor` | "zernio" \| "ycloud" \| "meta" | Sí | Por dónde sale la conexión. Puedes pasar un número de un proveedor a otro sin cambiar tu integración. | | `canal` | "whatsapp" \| "instagram" \| "messenger" | Sí | | | `nombre` | string | Sí | Para reconocerla, por ejemplo «WhatsApp de ventas». | | `telefono` | string | No | Solo WhatsApp: el número a conectar, si ya lo sabes. | ## Ejemplo Contra el sandbox, con una clave `onx_test_…`: ```bash curl -X POST "https://api-sandbox.opennexum.com/v1/conecta/conexiones" \ -H "Authorization: Bearer onx_test_…" \ -H "Content-Type: application/json" \ -d '{ "proveedor": "zernio", "canal": "whatsapp", "nombre": "texto" }' ``` ## Respuestas ### 201 Conexión creada, pendiente de alta. | Campo | Tipo | Requerido | Descripción | |---|---|---|---| | `id` | string | Sí | Identificador que empieza con `con_`. | | `proveedor` | "zernio" \| "ycloud" \| "meta" | Sí | Por dónde sale la conexión. Puedes pasar un número de un proveedor a otro sin cambiar tu integración. | | `canal` | "whatsapp" \| "instagram" \| "messenger" | Sí | | | `nombre` | string | Sí | | | `estado` | "pendiente" \| "activa" \| "desconectada" \| "error" | Sí | | | `telefono` | string \| null | Sí | | | `cuenta` | string \| null | Sí | Usuario de Instagram o página de Facebook, si aplica. | | `alta_url` | string (uri) \| null | Sí | Mientras está `pendiente`: dónde termina el alta una persona. | | `creada_en` | string (date-time) | Sí | Fecha y hora ISO 8601 con la zona de Lima (-05:00). | | `ultima_prueba_en` | string (date-time) \| null | Sí | | ### Errores Cada código tiene su explicación en [Errores](https://docs.opennexum.com/errores/). - **400** [`validacion`](https://docs.opennexum.com/errores#validacion) - **401** [`clave_invalida`](https://docs.opennexum.com/errores#clave_invalida) - **403** [`permiso_faltante`](https://docs.opennexum.com/errores#permiso_faltante) - **409** [`idempotencia_en_conflicto`](https://docs.opennexum.com/errores#idempotencia_en_conflicto) - **409** [`solicitud_en_curso`](https://docs.opennexum.com/errores#solicitud_en_curso) - **409** [`ya_registrado`](https://docs.opennexum.com/errores#ya_registrado) - **429** [`limite_uso`](https://docs.opennexum.com/errores#limite_uso) - **500** [`error_interno`](https://docs.opennexum.com/errores#error_interno) - **501** [`operacion_no_disponible`](https://docs.opennexum.com/errores#operacion_no_disponible) - **503** [`no_disponible`](https://docs.opennexum.com/errores#no_disponible) --- Fuente: https://docs.opennexum.com/referencia/conexiones/conexion_listar/ # Lista tus conexiones > Conexiones de la cuenta con su canal, proveedor y estado. `GET /v1/conecta/conexiones` Conexiones de la cuenta con su canal, proveedor y estado. ## Ficha | Dato | Valor | |---|---| | Permiso | `conecta:leer` | | Cobro | No cobra. | | `Idempotency-Key` | No aplica | | Herramienta MCP | `conexion_listar` (Próximamente) | ## Parámetros | Nombre | En | Requerido | Tipo | Descripción | |---|---|---|---|---| | `cursor` | query | No | string | Cursor opaco que devolvió la página anterior en `siguiente_cursor`. | | `limite` | query | No | integer | Cuántos elementos traer (1 a 100; por defecto 20). | | `canal` | query | No | string | | | `estado` | query | No | string | | | `X-Request-Id` | header | No | string | Identificador de la petición. Va en cada respuesta; menciónalo al escribir a soporte. | ## Ejemplo Contra el sandbox, con una clave `onx_test_…`: ```bash curl "https://api-sandbox.opennexum.com/v1/conecta/conexiones" \ -H "Authorization: Bearer onx_test_…" ``` ## Respuestas ### 200 Página de conexiones. | Campo | Tipo | Requerido | Descripción | |---|---|---|---| | `elementos` | object[] | Sí | | | `elementos[].id` | string | Sí | Identificador que empieza con `con_`. | | `elementos[].proveedor` | "zernio" \| "ycloud" \| "meta" | Sí | Por dónde sale la conexión. Puedes pasar un número de un proveedor a otro sin cambiar tu integración. | | `elementos[].canal` | "whatsapp" \| "instagram" \| "messenger" | Sí | | | `elementos[].nombre` | string | Sí | | | `elementos[].estado` | "pendiente" \| "activa" \| "desconectada" \| "error" | Sí | | | `elementos[].telefono` | string \| null | Sí | | | `elementos[].cuenta` | string \| null | Sí | Usuario de Instagram o página de Facebook, si aplica. | | `elementos[].alta_url` | string (uri) \| null | Sí | Mientras está `pendiente`: dónde termina el alta una persona. | | `elementos[].creada_en` | string (date-time) | Sí | Fecha y hora ISO 8601 con la zona de Lima (-05:00). | | `elementos[].ultima_prueba_en` | string (date-time) \| null | Sí | | | `siguiente_cursor` | string \| null | Sí | Pásalo como `cursor` para la página siguiente; `null` si ya no hay más. | ### Errores Cada código tiene su explicación en [Errores](https://docs.opennexum.com/errores/). - **400** [`validacion`](https://docs.opennexum.com/errores#validacion) - **401** [`clave_invalida`](https://docs.opennexum.com/errores#clave_invalida) - **403** [`permiso_faltante`](https://docs.opennexum.com/errores#permiso_faltante) - **429** [`limite_uso`](https://docs.opennexum.com/errores#limite_uso) - **500** [`error_interno`](https://docs.opennexum.com/errores#error_interno) - **501** [`operacion_no_disponible`](https://docs.opennexum.com/errores#operacion_no_disponible) - **503** [`no_disponible`](https://docs.opennexum.com/errores#no_disponible) --- Fuente: https://docs.opennexum.com/referencia/conexiones/conexion_ver/ # Consulta una conexión > Estado de una conexión y, si está pendiente, su enlace de alta. `GET /v1/conecta/conexiones/{id}` Estado de una conexión y, si está pendiente, su enlace de alta. ## Ficha | Dato | Valor | |---|---| | Permiso | `conecta:leer` | | Cobro | No cobra. | | `Idempotency-Key` | No aplica | | Herramienta MCP | `conexion_ver` (Próximamente) | ## Parámetros | Nombre | En | Requerido | Tipo | Descripción | |---|---|---|---|---| | `id` | path | Sí | string | Identificador que empieza con `con_`. | | `X-Request-Id` | header | No | string | Identificador de la petición. Va en cada respuesta; menciónalo al escribir a soporte. | ## Ejemplo Contra el sandbox, con una clave `onx_test_…`: ```bash curl "https://api-sandbox.opennexum.com/v1/conecta/conexiones/con_8f2c1a7d9e" \ -H "Authorization: Bearer onx_test_…" ``` ## Respuestas ### 200 Conexión. | Campo | Tipo | Requerido | Descripción | |---|---|---|---| | `id` | string | Sí | Identificador que empieza con `con_`. | | `proveedor` | "zernio" \| "ycloud" \| "meta" | Sí | Por dónde sale la conexión. Puedes pasar un número de un proveedor a otro sin cambiar tu integración. | | `canal` | "whatsapp" \| "instagram" \| "messenger" | Sí | | | `nombre` | string | Sí | | | `estado` | "pendiente" \| "activa" \| "desconectada" \| "error" | Sí | | | `telefono` | string \| null | Sí | | | `cuenta` | string \| null | Sí | Usuario de Instagram o página de Facebook, si aplica. | | `alta_url` | string (uri) \| null | Sí | Mientras está `pendiente`: dónde termina el alta una persona. | | `creada_en` | string (date-time) | Sí | Fecha y hora ISO 8601 con la zona de Lima (-05:00). | | `ultima_prueba_en` | string (date-time) \| null | Sí | | ### Errores Cada código tiene su explicación en [Errores](https://docs.opennexum.com/errores/). - **400** [`validacion`](https://docs.opennexum.com/errores#validacion) - **401** [`clave_invalida`](https://docs.opennexum.com/errores#clave_invalida) - **403** [`permiso_faltante`](https://docs.opennexum.com/errores#permiso_faltante) - **404** [`no_encontrado`](https://docs.opennexum.com/errores#no_encontrado) - **429** [`limite_uso`](https://docs.opennexum.com/errores#limite_uso) - **500** [`error_interno`](https://docs.opennexum.com/errores#error_interno) - **501** [`operacion_no_disponible`](https://docs.opennexum.com/errores#operacion_no_disponible) - **503** [`no_disponible`](https://docs.opennexum.com/errores#no_disponible) --- Fuente: https://docs.opennexum.com/referencia/conexiones/conexion_borrar/ # Borra una conexión > 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. `DELETE /v1/conecta/conexiones/{id}` 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. ## Ficha | Dato | Valor | |---|---| | Permiso | `conecta:administrar` | | Cobro | No cobra. | | `Idempotency-Key` | No aplica | | Aprobación humana | Según la configuración de tu clave puede responder `202` `requiere_confirmacion`. | | Herramienta MCP | `conexion_borrar` (Próximamente) | ## Parámetros | Nombre | En | Requerido | Tipo | Descripción | |---|---|---|---|---| | `id` | path | Sí | string | Identificador que empieza con `con_`. | | `X-Request-Id` | header | No | string | Identificador de la petición. Va en cada respuesta; menciónalo al escribir a soporte. | ## Ejemplo Contra el sandbox, con una clave `onx_test_…`: ```bash curl -X DELETE "https://api-sandbox.opennexum.com/v1/conecta/conexiones/con_8f2c1a7d9e" \ -H "Authorization: Bearer onx_test_…" ``` ## Respuestas ### 200 Conexión desconectada. | Campo | Tipo | Requerido | Descripción | |---|---|---|---| | `id` | string | Sí | Identificador que empieza con `con_`. | | `proveedor` | "zernio" \| "ycloud" \| "meta" | Sí | Por dónde sale la conexión. Puedes pasar un número de un proveedor a otro sin cambiar tu integración. | | `canal` | "whatsapp" \| "instagram" \| "messenger" | Sí | | | `nombre` | string | Sí | | | `estado` | "pendiente" \| "activa" \| "desconectada" \| "error" | Sí | | | `telefono` | string \| null | Sí | | | `cuenta` | string \| null | Sí | Usuario de Instagram o página de Facebook, si aplica. | | `alta_url` | string (uri) \| null | Sí | Mientras está `pendiente`: dónde termina el alta una persona. | | `creada_en` | string (date-time) | Sí | Fecha y hora ISO 8601 con la zona de Lima (-05:00). | | `ultima_prueba_en` | string (date-time) \| null | Sí | | ### 202 Espera la aprobación de una persona. | Campo | Tipo | Requerido | Descripción | |---|---|---|---| | `estado` | "requiere_confirmacion" | Sí | | | `operacion_id` | string | Sí | Úsalo en `GET /v1/confirmaciones/{id}` para saber si se aprobó. | | `confirmacion_url` | string (uri) | Sí | Enlace del panel donde una persona aprueba o rechaza. Pásaselo tal cual. | | `consulta_url` | string | Sí | Ruta para consultar el estado. | | `expira_en` | string (date-time) | Sí | Si nadie aprueba antes, la operación vence y no se hace. | | `mensaje` | string | Sí | Qué falta, en palabras para una persona. | ### Errores Cada código tiene su explicación en [Errores](https://docs.opennexum.com/errores/). - **400** [`validacion`](https://docs.opennexum.com/errores#validacion) - **401** [`clave_invalida`](https://docs.opennexum.com/errores#clave_invalida) - **403** [`permiso_faltante`](https://docs.opennexum.com/errores#permiso_faltante) - **404** [`no_encontrado`](https://docs.opennexum.com/errores#no_encontrado) - **429** [`limite_uso`](https://docs.opennexum.com/errores#limite_uso) - **500** [`error_interno`](https://docs.opennexum.com/errores#error_interno) - **501** [`operacion_no_disponible`](https://docs.opennexum.com/errores#operacion_no_disponible) - **503** [`no_disponible`](https://docs.opennexum.com/errores#no_disponible) --- Fuente: https://docs.opennexum.com/referencia/conexiones/conexion_probar/ # Prueba una conexión > Verifica con el proveedor que la conexión funciona. No envía mensajes a nadie. `POST /v1/conecta/conexiones/{id}/probar` Verifica con el proveedor que la conexión funciona. No envía mensajes a nadie. ## Ficha | Dato | Valor | |---|---| | Permiso | `conecta:leer` | | Cobro | No cobra. | | `Idempotency-Key` | No aplica | | Herramienta MCP | `conexion_probar` (Próximamente) | ## Parámetros | Nombre | En | Requerido | Tipo | Descripción | |---|---|---|---|---| | `id` | path | Sí | string | Identificador que empieza con `con_`. | | `X-Request-Id` | header | No | string | Identificador de la petición. Va en cada respuesta; menciónalo al escribir a soporte. | ## Ejemplo Contra el sandbox, con una clave `onx_test_…`: ```bash curl -X POST "https://api-sandbox.opennexum.com/v1/conecta/conexiones/con_8f2c1a7d9e/probar" \ -H "Authorization: Bearer onx_test_…" ``` ## Respuestas ### 200 Resultado de la prueba. | Campo | Tipo | Requerido | Descripción | |---|---|---|---| | `conexion_id` | string | Sí | Identificador que empieza con `con_`. | | `ok` | boolean | Sí | | | `estado` | "pendiente" \| "activa" \| "desconectada" \| "error" | Sí | | | `detalle` | string | Sí | | | `probado_en` | string (date-time) | Sí | Fecha y hora ISO 8601 con la zona de Lima (-05:00). | ### Errores Cada código tiene su explicación en [Errores](https://docs.opennexum.com/errores/). - **400** [`validacion`](https://docs.opennexum.com/errores#validacion) - **401** [`clave_invalida`](https://docs.opennexum.com/errores#clave_invalida) - **403** [`permiso_faltante`](https://docs.opennexum.com/errores#permiso_faltante) - **404** [`no_encontrado`](https://docs.opennexum.com/errores#no_encontrado) - **429** [`limite_uso`](https://docs.opennexum.com/errores#limite_uso) - **500** [`error_interno`](https://docs.opennexum.com/errores#error_interno) - **501** [`operacion_no_disponible`](https://docs.opennexum.com/errores#operacion_no_disponible) - **502** [`servicio_externo_no_disponible`](https://docs.opennexum.com/errores#servicio_externo_no_disponible) - **503** [`no_disponible`](https://docs.opennexum.com/errores#no_disponible) --- Fuente: https://docs.opennexum.com/referencia/mensajes/mensaje_enviar/ # Envía un mensaje > 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. `POST /v1/conecta/mensajes` 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. ## Ficha | Dato | Valor | |---|---| | Permiso | `conecta:enviar` | | Cobro | No cobra. | | `Idempotency-Key` | Obligatoria | | Aprobación humana | Según la configuración de tu clave puede responder `202` `requiere_confirmacion`. | | Herramienta MCP | `mensaje_enviar` (Próximamente) | ## Parámetros | Nombre | En | Requerido | Tipo | Descripción | |---|---|---|---|---| | `Idempotency-Key` | header | Sí | string | 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. | | `X-Request-Id` | header | No | string | Identificador de la petición. Va en cada respuesta; menciónalo al escribir a soporte. | ## Cuerpo `application/json`, obligatorio. Los campos anidados van con punto y los de listas con `[]`. No se aceptan campos desconocidos. | Campo | Tipo | Requerido | Descripción | |---|---|---|---| | `conexion_id` | string | Sí | Identificador que empieza con `con_`. | | `conversacion_id` | string | No | Responder en una conversación existente (cualquier canal). | | `telefono` | string | No | Solo WhatsApp: escribir a un número. | | `tipo` | "texto" | Sí | | | `texto` | string | No | | | `media` | object | No | | | `media.tipo` | "imagen" \| "video" \| "audio" \| "documento" | No | | | `media.url` | string (uri) | No | Archivo público por https; lo descargamos y lo enviamos. | | `media.nombre_archivo` | string | No | | | `media.leyenda` | string | No | | | `plantilla` | object | No | | | `plantilla.nombre` | string | No | | | `plantilla.idioma` | string | No | Código de idioma, por ejemplo es o es_PE. | | `plantilla.parametros` | object | No | | | `plantilla.parametros.encabezado` | string \| object | No | | | `plantilla.parametros.cuerpo` | string[] | No | Valores de {{1}}, {{2}}… en orden. | | `plantilla.parametros.botones` | string[] | No | | ## Ejemplo Contra el sandbox, con una clave `onx_test_…`: ```bash curl -X POST "https://api-sandbox.opennexum.com/v1/conecta/mensajes" \ -H "Authorization: Bearer onx_test_…" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "conexion_id": "con_8f2c1a7d9e", "tipo": "texto", "texto": "texto" }' ``` ## Respuestas ### 201 Mensaje aceptado por el proveedor. | Campo | Tipo | Requerido | Descripción | |---|---|---|---| | `id` | string | Sí | Identificador que empieza con `msg_`. | | `conexion_id` | string | Sí | Identificador que empieza con `con_`. | | `conversacion_id` | string | Sí | Identificador que empieza con `cnv_`. | | `canal` | "whatsapp" \| "instagram" \| "messenger" | Sí | | | `direccion` | "saliente" \| "entrante" | Sí | | | `tipo` | "texto" \| "media" \| "plantilla" \| "interactivo" \| "otro" | Sí | | | `texto` | string \| null | Sí | | | `media` | object \| null | Sí | En mensajes entrantes, la URL es nuestra y vence en unas horas. | | `media.tipo` | "imagen" \| "video" \| "audio" \| "documento" | Sí | | | `media.url` | string (uri) | Sí | | | `media.nombre_archivo` | string \| null | Sí | | | `media.leyenda` | string \| null | Sí | | | `plantilla` | object \| null | Sí | | | `plantilla.nombre` | string | Sí | | | `plantilla.idioma` | string | Sí | | | `estado` | "en_cola" \| "enviado" \| "entregado" \| "leido" \| "fallido" \| "incierto" \| "recibido" | Sí | `incierto`: el proveedor no confirmó; revisa antes de reenviar. `recibido`: mensaje entrante. | | `error` | object \| null | Sí | | | `error.codigo` | string | Sí | | | `error.mensaje` | string | Sí | | | `creado_en` | string (date-time) | Sí | Fecha y hora ISO 8601 con la zona de Lima (-05:00). | | `actualizado_en` | string (date-time) | Sí | Fecha y hora ISO 8601 con la zona de Lima (-05:00). | ### 202 Espera la aprobación de una persona. | Campo | Tipo | Requerido | Descripción | |---|---|---|---| | `estado` | "requiere_confirmacion" | Sí | | | `operacion_id` | string | Sí | Úsalo en `GET /v1/confirmaciones/{id}` para saber si se aprobó. | | `confirmacion_url` | string (uri) | Sí | Enlace del panel donde una persona aprueba o rechaza. Pásaselo tal cual. | | `consulta_url` | string | Sí | Ruta para consultar el estado. | | `expira_en` | string (date-time) | Sí | Si nadie aprueba antes, la operación vence y no se hace. | | `mensaje` | string | Sí | Qué falta, en palabras para una persona. | ### Errores Cada código tiene su explicación en [Errores](https://docs.opennexum.com/errores/). - **400** [`validacion`](https://docs.opennexum.com/errores#validacion) - **401** [`clave_invalida`](https://docs.opennexum.com/errores#clave_invalida) - **403** [`permiso_faltante`](https://docs.opennexum.com/errores#permiso_faltante) - **404** [`no_encontrado`](https://docs.opennexum.com/errores#no_encontrado) - **409** [`idempotencia_en_conflicto`](https://docs.opennexum.com/errores#idempotencia_en_conflicto) - **409** [`solicitud_en_curso`](https://docs.opennexum.com/errores#solicitud_en_curso) - **409** [`ventana_cerrada`](https://docs.opennexum.com/errores#ventana_cerrada) - **409** [`estado_no_permite`](https://docs.opennexum.com/errores#estado_no_permite) - **429** [`limite_uso`](https://docs.opennexum.com/errores#limite_uso) - **500** [`error_interno`](https://docs.opennexum.com/errores#error_interno) - **501** [`operacion_no_disponible`](https://docs.opennexum.com/errores#operacion_no_disponible) - **502** [`servicio_externo_no_disponible`](https://docs.opennexum.com/errores#servicio_externo_no_disponible) - **503** [`no_disponible`](https://docs.opennexum.com/errores#no_disponible) --- Fuente: https://docs.opennexum.com/referencia/mensajes/mensaje_ver/ # Consulta un mensaje > Estado de entrega de un mensaje enviado o detalle de uno recibido. `GET /v1/conecta/mensajes/{id}` Estado de entrega de un mensaje enviado o detalle de uno recibido. ## Ficha | Dato | Valor | |---|---| | Permiso | `conecta:leer` | | Cobro | No cobra. | | `Idempotency-Key` | No aplica | | Herramienta MCP | `mensaje_ver` (Próximamente) | ## Parámetros | Nombre | En | Requerido | Tipo | Descripción | |---|---|---|---|---| | `id` | path | Sí | string | Identificador que empieza con `msg_`. | | `X-Request-Id` | header | No | string | Identificador de la petición. Va en cada respuesta; menciónalo al escribir a soporte. | ## Ejemplo Contra el sandbox, con una clave `onx_test_…`: ```bash curl "https://api-sandbox.opennexum.com/v1/conecta/mensajes/msg_8f2c1a7d9e" \ -H "Authorization: Bearer onx_test_…" ``` ## Respuestas ### 200 Mensaje. | Campo | Tipo | Requerido | Descripción | |---|---|---|---| | `id` | string | Sí | Identificador que empieza con `msg_`. | | `conexion_id` | string | Sí | Identificador que empieza con `con_`. | | `conversacion_id` | string | Sí | Identificador que empieza con `cnv_`. | | `canal` | "whatsapp" \| "instagram" \| "messenger" | Sí | | | `direccion` | "saliente" \| "entrante" | Sí | | | `tipo` | "texto" \| "media" \| "plantilla" \| "interactivo" \| "otro" | Sí | | | `texto` | string \| null | Sí | | | `media` | object \| null | Sí | En mensajes entrantes, la URL es nuestra y vence en unas horas. | | `media.tipo` | "imagen" \| "video" \| "audio" \| "documento" | Sí | | | `media.url` | string (uri) | Sí | | | `media.nombre_archivo` | string \| null | Sí | | | `media.leyenda` | string \| null | Sí | | | `plantilla` | object \| null | Sí | | | `plantilla.nombre` | string | Sí | | | `plantilla.idioma` | string | Sí | | | `estado` | "en_cola" \| "enviado" \| "entregado" \| "leido" \| "fallido" \| "incierto" \| "recibido" | Sí | `incierto`: el proveedor no confirmó; revisa antes de reenviar. `recibido`: mensaje entrante. | | `error` | object \| null | Sí | | | `error.codigo` | string | Sí | | | `error.mensaje` | string | Sí | | | `creado_en` | string (date-time) | Sí | Fecha y hora ISO 8601 con la zona de Lima (-05:00). | | `actualizado_en` | string (date-time) | Sí | Fecha y hora ISO 8601 con la zona de Lima (-05:00). | ### Errores Cada código tiene su explicación en [Errores](https://docs.opennexum.com/errores/). - **400** [`validacion`](https://docs.opennexum.com/errores#validacion) - **401** [`clave_invalida`](https://docs.opennexum.com/errores#clave_invalida) - **403** [`permiso_faltante`](https://docs.opennexum.com/errores#permiso_faltante) - **404** [`no_encontrado`](https://docs.opennexum.com/errores#no_encontrado) - **429** [`limite_uso`](https://docs.opennexum.com/errores#limite_uso) - **500** [`error_interno`](https://docs.opennexum.com/errores#error_interno) - **501** [`operacion_no_disponible`](https://docs.opennexum.com/errores#operacion_no_disponible) - **503** [`no_disponible`](https://docs.opennexum.com/errores#no_disponible) --- Fuente: https://docs.opennexum.com/referencia/mensajes/conversacion_listar/ # Lista conversaciones > Bandeja de WhatsApp, Instagram y Messenger, con la ventana de atención de cada conversación. `GET /v1/conecta/conversaciones` Bandeja de WhatsApp, Instagram y Messenger, con la ventana de atención de cada conversación. ## Ficha | Dato | Valor | |---|---| | Permiso | `conecta:leer` | | Cobro | No cobra. | | `Idempotency-Key` | No aplica | | Herramienta MCP | `conversacion_listar` (Próximamente) | ## Parámetros | Nombre | En | Requerido | Tipo | Descripción | |---|---|---|---|---| | `cursor` | query | No | string | Cursor opaco que devolvió la página anterior en `siguiente_cursor`. | | `limite` | query | No | integer | Cuántos elementos traer (1 a 100; por defecto 20). | | `conexion_id` | query | No | string | Identificador que empieza con `con_`. | | `canal` | query | No | string | | | `X-Request-Id` | header | No | string | Identificador de la petición. Va en cada respuesta; menciónalo al escribir a soporte. | ## Ejemplo Contra el sandbox, con una clave `onx_test_…`: ```bash curl "https://api-sandbox.opennexum.com/v1/conecta/conversaciones" \ -H "Authorization: Bearer onx_test_…" ``` ## Respuestas ### 200 Página de conversaciones. | Campo | Tipo | Requerido | Descripción | |---|---|---|---| | `elementos` | object[] | Sí | | | `elementos[].id` | string | Sí | Identificador que empieza con `cnv_`. | | `elementos[].conexion_id` | string | Sí | Identificador que empieza con `con_`. | | `elementos[].canal` | "whatsapp" \| "instagram" \| "messenger" | Sí | | | `elementos[].contacto` | object | Sí | | | `elementos[].contacto.nombre` | string \| null | Sí | | | `elementos[].contacto.telefono` | string \| null | Sí | | | `elementos[].contacto.usuario` | string \| null | Sí | Usuario de Instagram, si aplica. | | `elementos[].ventana` | object | Sí | Ventana de atención: mientras está abierta puedes escribir libre; si no, solo plantillas. | | `elementos[].ventana.abierta` | boolean | Sí | | | `elementos[].ventana.cierra_en` | string (date-time) \| null | Sí | | | `elementos[].ventana.tipo` | "24h" \| "72h" \| null | Sí | 72h cuando el contacto llegó por un anuncio. | | `elementos[].no_leidos` | integer | Sí | | | `elementos[].ultimo_mensaje_en` | string (date-time) \| null | Sí | | | `elementos[].creada_en` | string (date-time) | Sí | Fecha y hora ISO 8601 con la zona de Lima (-05:00). | | `siguiente_cursor` | string \| null | Sí | Pásalo como `cursor` para la página siguiente; `null` si ya no hay más. | ### Errores Cada código tiene su explicación en [Errores](https://docs.opennexum.com/errores/). - **400** [`validacion`](https://docs.opennexum.com/errores#validacion) - **401** [`clave_invalida`](https://docs.opennexum.com/errores#clave_invalida) - **403** [`permiso_faltante`](https://docs.opennexum.com/errores#permiso_faltante) - **429** [`limite_uso`](https://docs.opennexum.com/errores#limite_uso) - **500** [`error_interno`](https://docs.opennexum.com/errores#error_interno) - **501** [`operacion_no_disponible`](https://docs.opennexum.com/errores#operacion_no_disponible) - **503** [`no_disponible`](https://docs.opennexum.com/errores#no_disponible) --- Fuente: https://docs.opennexum.com/referencia/mensajes/conversacion_ver/ # Consulta una conversación > Contacto, ventana de atención y mensajes sin leer de una conversación. `GET /v1/conecta/conversaciones/{id}` Contacto, ventana de atención y mensajes sin leer de una conversación. ## Ficha | Dato | Valor | |---|---| | Permiso | `conecta:leer` | | Cobro | No cobra. | | `Idempotency-Key` | No aplica | | Herramienta MCP | `conversacion_ver` (Próximamente) | ## Parámetros | Nombre | En | Requerido | Tipo | Descripción | |---|---|---|---|---| | `id` | path | Sí | string | Identificador que empieza con `cnv_`. | | `X-Request-Id` | header | No | string | Identificador de la petición. Va en cada respuesta; menciónalo al escribir a soporte. | ## Ejemplo Contra el sandbox, con una clave `onx_test_…`: ```bash curl "https://api-sandbox.opennexum.com/v1/conecta/conversaciones/cnv_8f2c1a7d9e" \ -H "Authorization: Bearer onx_test_…" ``` ## Respuestas ### 200 Conversación. | Campo | Tipo | Requerido | Descripción | |---|---|---|---| | `id` | string | Sí | Identificador que empieza con `cnv_`. | | `conexion_id` | string | Sí | Identificador que empieza con `con_`. | | `canal` | "whatsapp" \| "instagram" \| "messenger" | Sí | | | `contacto` | object | Sí | | | `contacto.nombre` | string \| null | Sí | | | `contacto.telefono` | string \| null | Sí | | | `contacto.usuario` | string \| null | Sí | Usuario de Instagram, si aplica. | | `ventana` | object | Sí | Ventana de atención: mientras está abierta puedes escribir libre; si no, solo plantillas. | | `ventana.abierta` | boolean | Sí | | | `ventana.cierra_en` | string (date-time) \| null | Sí | | | `ventana.tipo` | "24h" \| "72h" \| null | Sí | 72h cuando el contacto llegó por un anuncio. | | `no_leidos` | integer | Sí | | | `ultimo_mensaje_en` | string (date-time) \| null | Sí | | | `creada_en` | string (date-time) | Sí | Fecha y hora ISO 8601 con la zona de Lima (-05:00). | ### Errores Cada código tiene su explicación en [Errores](https://docs.opennexum.com/errores/). - **400** [`validacion`](https://docs.opennexum.com/errores#validacion) - **401** [`clave_invalida`](https://docs.opennexum.com/errores#clave_invalida) - **403** [`permiso_faltante`](https://docs.opennexum.com/errores#permiso_faltante) - **404** [`no_encontrado`](https://docs.opennexum.com/errores#no_encontrado) - **429** [`limite_uso`](https://docs.opennexum.com/errores#limite_uso) - **500** [`error_interno`](https://docs.opennexum.com/errores#error_interno) - **501** [`operacion_no_disponible`](https://docs.opennexum.com/errores#operacion_no_disponible) - **503** [`no_disponible`](https://docs.opennexum.com/errores#no_disponible) --- Fuente: https://docs.opennexum.com/referencia/mensajes/conversacion_mensajes/ # Lista los mensajes de una conversación > Mensajes enviados y recibidos, del más reciente al más antiguo. `GET /v1/conecta/conversaciones/{id}/mensajes` Mensajes enviados y recibidos, del más reciente al más antiguo. ## Ficha | Dato | Valor | |---|---| | Permiso | `conecta:leer` | | Cobro | No cobra. | | `Idempotency-Key` | No aplica | | Herramienta MCP | `conversacion_mensajes` (Próximamente) | ## Parámetros | Nombre | En | Requerido | Tipo | Descripción | |---|---|---|---|---| | `id` | path | Sí | string | Identificador que empieza con `cnv_`. | | `cursor` | query | No | string | Cursor opaco que devolvió la página anterior en `siguiente_cursor`. | | `limite` | query | No | integer | Cuántos elementos traer (1 a 100; por defecto 20). | | `X-Request-Id` | header | No | string | Identificador de la petición. Va en cada respuesta; menciónalo al escribir a soporte. | ## Ejemplo Contra el sandbox, con una clave `onx_test_…`: ```bash curl "https://api-sandbox.opennexum.com/v1/conecta/conversaciones/cnv_8f2c1a7d9e/mensajes" \ -H "Authorization: Bearer onx_test_…" ``` ## Respuestas ### 200 Página de mensajes. | Campo | Tipo | Requerido | Descripción | |---|---|---|---| | `elementos` | object[] | Sí | | | `elementos[].id` | string | Sí | Identificador que empieza con `msg_`. | | `elementos[].conexion_id` | string | Sí | Identificador que empieza con `con_`. | | `elementos[].conversacion_id` | string | Sí | Identificador que empieza con `cnv_`. | | `elementos[].canal` | "whatsapp" \| "instagram" \| "messenger" | Sí | | | `elementos[].direccion` | "saliente" \| "entrante" | Sí | | | `elementos[].tipo` | "texto" \| "media" \| "plantilla" \| "interactivo" \| "otro" | Sí | | | `elementos[].texto` | string \| null | Sí | | | `elementos[].media` | object \| null | Sí | En mensajes entrantes, la URL es nuestra y vence en unas horas. | | `elementos[].media.tipo` | "imagen" \| "video" \| "audio" \| "documento" | Sí | | | `elementos[].media.url` | string (uri) | Sí | | | `elementos[].media.nombre_archivo` | string \| null | Sí | | | `elementos[].media.leyenda` | string \| null | Sí | | | `elementos[].plantilla` | object \| null | Sí | | | `elementos[].plantilla.nombre` | string | Sí | | | `elementos[].plantilla.idioma` | string | Sí | | | `elementos[].estado` | "en_cola" \| "enviado" \| "entregado" \| "leido" \| "fallido" \| "incierto" \| "recibido" | Sí | `incierto`: el proveedor no confirmó; revisa antes de reenviar. `recibido`: mensaje entrante. | | `elementos[].error` | object \| null | Sí | | | `elementos[].error.codigo` | string | Sí | | | `elementos[].error.mensaje` | string | Sí | | | `elementos[].creado_en` | string (date-time) | Sí | Fecha y hora ISO 8601 con la zona de Lima (-05:00). | | `elementos[].actualizado_en` | string (date-time) | Sí | Fecha y hora ISO 8601 con la zona de Lima (-05:00). | | `siguiente_cursor` | string \| null | Sí | Pásalo como `cursor` para la página siguiente; `null` si ya no hay más. | ### Errores Cada código tiene su explicación en [Errores](https://docs.opennexum.com/errores/). - **400** [`validacion`](https://docs.opennexum.com/errores#validacion) - **401** [`clave_invalida`](https://docs.opennexum.com/errores#clave_invalida) - **403** [`permiso_faltante`](https://docs.opennexum.com/errores#permiso_faltante) - **404** [`no_encontrado`](https://docs.opennexum.com/errores#no_encontrado) - **429** [`limite_uso`](https://docs.opennexum.com/errores#limite_uso) - **500** [`error_interno`](https://docs.opennexum.com/errores#error_interno) - **501** [`operacion_no_disponible`](https://docs.opennexum.com/errores#operacion_no_disponible) - **503** [`no_disponible`](https://docs.opennexum.com/errores#no_disponible) --- Fuente: https://docs.opennexum.com/referencia/mensajes/comprobante_enviar/ # Envía un comprobante por mensaje > 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. `POST /v1/conecta/comprobantes/enviar` 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. ## Ficha | Dato | Valor | |---|---| | Permiso | `conecta:enviar` | | Cobro | Reserva el precio de tu saldo y lo cobra solo si el servicio confirma (por ejemplo, SUNAT acepta). | | `Idempotency-Key` | Obligatoria | | Aprobación humana | Según la configuración de tu clave puede responder `202` `requiere_confirmacion`. | | Herramienta MCP | `comprobante_enviar` (Próximamente) | ## Parámetros | Nombre | En | Requerido | Tipo | Descripción | |---|---|---|---|---| | `Idempotency-Key` | header | Sí | string | 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. | | `X-Request-Id` | header | No | string | Identificador de la petición. Va en cada respuesta; menciónalo al escribir a soporte. | ## Cuerpo `application/json`, obligatorio. Los campos anidados van con punto y los de listas con `[]`. No se aceptan campos desconocidos. | Campo | Tipo | Requerido | Descripción | |---|---|---|---| | `conexion_id` | string | Sí | Identificador que empieza con `con_`. | | `conversacion_id` | string | No | Responder en una conversación existente (cualquier canal). | | `telefono` | string | No | Solo WhatsApp: escribir a un número. | | `comprobante` | object | Sí | Comprobante de un emisor de tu cuenta. | | `comprobante.ruc` | string | Sí | RUC de 11 dígitos. Se valida el dígito verificador (módulo 11 de SUNAT). | | `comprobante.id` | string | Sí | Identificador que empieza con `cmp_`. | | `mensaje` | string | No | Texto que acompaña al PDF dentro de la ventana de atención. | | `plantilla` | object | No | 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. | | `plantilla.nombre` | string | Sí | | | `plantilla.idioma` | string | Sí | Código de idioma, por ejemplo es o es_PE. | | `formato_pdf` | "a4" \| "ticket80" | No | | ## Ejemplo Contra el sandbox, con una clave `onx_test_…`: ```bash curl -X POST "https://api-sandbox.opennexum.com/v1/conecta/comprobantes/enviar" \ -H "Authorization: Bearer onx_test_…" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "conexion_id": "con_8f2c1a7d9e", "comprobante": { "ruc": "20000000001", "id": "cmp_8f2c1a7d9e" } }' ``` ## Respuestas ### 201 Comprobante enviado. | Campo | Tipo | Requerido | Descripción | |---|---|---|---| | `id` | string | Sí | Identificador que empieza con `msg_`. | | `conexion_id` | string | Sí | Identificador que empieza con `con_`. | | `conversacion_id` | string | Sí | Identificador que empieza con `cnv_`. | | `canal` | "whatsapp" \| "instagram" \| "messenger" | Sí | | | `direccion` | "saliente" \| "entrante" | Sí | | | `tipo` | "texto" \| "media" \| "plantilla" \| "interactivo" \| "otro" | Sí | | | `texto` | string \| null | Sí | | | `media` | object \| null | Sí | En mensajes entrantes, la URL es nuestra y vence en unas horas. | | `media.tipo` | "imagen" \| "video" \| "audio" \| "documento" | Sí | | | `media.url` | string (uri) | Sí | | | `media.nombre_archivo` | string \| null | Sí | | | `media.leyenda` | string \| null | Sí | | | `plantilla` | object \| null | Sí | | | `plantilla.nombre` | string | Sí | | | `plantilla.idioma` | string | Sí | | | `estado` | "en_cola" \| "enviado" \| "entregado" \| "leido" \| "fallido" \| "incierto" \| "recibido" | Sí | `incierto`: el proveedor no confirmó; revisa antes de reenviar. `recibido`: mensaje entrante. | | `error` | object \| null | Sí | | | `error.codigo` | string | Sí | | | `error.mensaje` | string | Sí | | | `creado_en` | string (date-time) | Sí | Fecha y hora ISO 8601 con la zona de Lima (-05:00). | | `actualizado_en` | string (date-time) | Sí | Fecha y hora ISO 8601 con la zona de Lima (-05:00). | ### 202 Espera la aprobación de una persona. | Campo | Tipo | Requerido | Descripción | |---|---|---|---| | `estado` | "requiere_confirmacion" | Sí | | | `operacion_id` | string | Sí | Úsalo en `GET /v1/confirmaciones/{id}` para saber si se aprobó. | | `confirmacion_url` | string (uri) | Sí | Enlace del panel donde una persona aprueba o rechaza. Pásaselo tal cual. | | `consulta_url` | string | Sí | Ruta para consultar el estado. | | `expira_en` | string (date-time) | Sí | Si nadie aprueba antes, la operación vence y no se hace. | | `mensaje` | string | Sí | Qué falta, en palabras para una persona. | ### Errores Cada código tiene su explicación en [Errores](https://docs.opennexum.com/errores/). - **400** [`validacion`](https://docs.opennexum.com/errores#validacion) - **401** [`clave_invalida`](https://docs.opennexum.com/errores#clave_invalida) - **402** [`saldo_insuficiente`](https://docs.opennexum.com/errores#saldo_insuficiente) - **402** [`tope_alcanzado`](https://docs.opennexum.com/errores#tope_alcanzado) - **403** [`permiso_faltante`](https://docs.opennexum.com/errores#permiso_faltante) - **404** [`no_encontrado`](https://docs.opennexum.com/errores#no_encontrado) - **409** [`idempotencia_en_conflicto`](https://docs.opennexum.com/errores#idempotencia_en_conflicto) - **409** [`solicitud_en_curso`](https://docs.opennexum.com/errores#solicitud_en_curso) - **409** [`ventana_cerrada`](https://docs.opennexum.com/errores#ventana_cerrada) - **409** [`estado_no_permite`](https://docs.opennexum.com/errores#estado_no_permite) - **429** [`limite_uso`](https://docs.opennexum.com/errores#limite_uso) - **500** [`error_interno`](https://docs.opennexum.com/errores#error_interno) - **501** [`operacion_no_disponible`](https://docs.opennexum.com/errores#operacion_no_disponible) - **502** [`servicio_externo_no_disponible`](https://docs.opennexum.com/errores#servicio_externo_no_disponible) - **503** [`no_disponible`](https://docs.opennexum.com/errores#no_disponible) --- Fuente: https://docs.opennexum.com/referencia/plantillas/plantilla_listar/ # Lista plantillas > Plantillas de mensaje por conexión, con su estado de revisión. `GET /v1/conecta/plantillas` Plantillas de mensaje por conexión, con su estado de revisión. ## Ficha | Dato | Valor | |---|---| | Permiso | `conecta:leer` | | Cobro | No cobra. | | `Idempotency-Key` | No aplica | | Herramienta MCP | `plantilla_listar` (Próximamente) | ## Parámetros | Nombre | En | Requerido | Tipo | Descripción | |---|---|---|---|---| | `cursor` | query | No | string | Cursor opaco que devolvió la página anterior en `siguiente_cursor`. | | `limite` | query | No | integer | Cuántos elementos traer (1 a 100; por defecto 20). | | `conexion_id` | query | No | string | Identificador que empieza con `con_`. | | `estado` | query | No | string | | | `X-Request-Id` | header | No | string | Identificador de la petición. Va en cada respuesta; menciónalo al escribir a soporte. | ## Ejemplo Contra el sandbox, con una clave `onx_test_…`: ```bash curl "https://api-sandbox.opennexum.com/v1/conecta/plantillas" \ -H "Authorization: Bearer onx_test_…" ``` ## Respuestas ### 200 Página de plantillas. | Campo | Tipo | Requerido | Descripción | |---|---|---|---| | `elementos` | object[] | Sí | | | `elementos[].id` | string | Sí | Identificador que empieza con `plt_`. | | `elementos[].conexion_id` | string | Sí | Identificador que empieza con `con_`. | | `elementos[].nombre` | string | Sí | | | `elementos[].idioma` | string | Sí | | | `elementos[].categoria` | "utilidad" \| "marketing" \| "autenticacion" | Sí | | | `elementos[].estado` | "pendiente" \| "aprobada" \| "rechazada" \| "pausada" \| "deshabilitada" | Sí | | | `elementos[].encabezado` | string \| null | Sí | | | `elementos[].cuerpo` | string | Sí | | | `elementos[].pie` | string \| null | Sí | | | `elementos[].botones` | object[] | Sí | | | `elementos[].botones[].tipo` | "respuesta_rapida" \| "url" \| "telefono" | Sí | | | `elementos[].botones[].texto` | string | Sí | | | `elementos[].variables` | integer | Sí | Cuántas variables espera el cuerpo. | | `elementos[].motivo_rechazo` | string \| null | Sí | | | `elementos[].creada_en` | string (date-time) | Sí | Fecha y hora ISO 8601 con la zona de Lima (-05:00). | | `elementos[].actualizada_en` | string (date-time) | Sí | Fecha y hora ISO 8601 con la zona de Lima (-05:00). | | `siguiente_cursor` | string \| null | Sí | Pásalo como `cursor` para la página siguiente; `null` si ya no hay más. | ### Errores Cada código tiene su explicación en [Errores](https://docs.opennexum.com/errores/). - **400** [`validacion`](https://docs.opennexum.com/errores#validacion) - **401** [`clave_invalida`](https://docs.opennexum.com/errores#clave_invalida) - **403** [`permiso_faltante`](https://docs.opennexum.com/errores#permiso_faltante) - **429** [`limite_uso`](https://docs.opennexum.com/errores#limite_uso) - **500** [`error_interno`](https://docs.opennexum.com/errores#error_interno) - **501** [`operacion_no_disponible`](https://docs.opennexum.com/errores#operacion_no_disponible) - **503** [`no_disponible`](https://docs.opennexum.com/errores#no_disponible) --- Fuente: https://docs.opennexum.com/referencia/plantillas/plantilla_crear/ # Crea una plantilla > Crea una plantilla y la manda a revisión. Te avisamos con el evento `plantilla.estado`. `POST /v1/conecta/plantillas` Crea una plantilla y la manda a revisión. Te avisamos con el evento `plantilla.estado`. ## Ficha | Dato | Valor | |---|---| | Permiso | `conecta:administrar` | | Cobro | No cobra. | | `Idempotency-Key` | Opcional | | Herramienta MCP | `plantilla_crear` (Próximamente) | ## Parámetros | Nombre | En | Requerido | Tipo | Descripción | |---|---|---|---|---| | `Idempotency-Key` | header | No | string | 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. | | `X-Request-Id` | header | No | string | Identificador de la petición. Va en cada respuesta; menciónalo al escribir a soporte. | ## Cuerpo `application/json`, obligatorio. Los campos anidados van con punto y los de listas con `[]`. No se aceptan campos desconocidos. | Campo | Tipo | Requerido | Descripción | |---|---|---|---| | `conexion_id` | string | Sí | Identificador que empieza con `con_`. | | `nombre` | string | Sí | | | `idioma` | string | Sí | Código de idioma, por ejemplo es o es_PE. | | `categoria` | "utilidad" \| "marketing" \| "autenticacion" | Sí | Nunca uses plantillas para cobro de deudas: Meta no lo permite. | | `cuerpo` | string | Sí | Texto con variables {{1}}, {{2}}… | | `encabezado` | string | No | | | `pie` | string | No | | | `botones` | object[] | No | | | `botones[].tipo` | "respuesta_rapida" \| "url" \| "telefono" | Sí | | | `botones[].texto` | string | Sí | | | `botones[].url` | string (uri) | No | URL pública con https (sin IP literal, localhost, dominios internos ni usuario y clave). | | `botones[].telefono` | string | No | Teléfono en formato E.164, sin espacios. | | `ejemplos` | string[] | No | Valores de ejemplo para la revisión de Meta. | ## Ejemplo Contra el sandbox, con una clave `onx_test_…`: ```bash curl -X POST "https://api-sandbox.opennexum.com/v1/conecta/plantillas" \ -H "Authorization: Bearer onx_test_…" \ -H "Content-Type: application/json" \ -d '{ "conexion_id": "con_8f2c1a7d9e", "nombre": "texto", "idioma": "texto", "categoria": "utilidad", "cuerpo": "texto" }' ``` ## Respuestas ### 201 Plantilla creada, pendiente de revisión. | Campo | Tipo | Requerido | Descripción | |---|---|---|---| | `id` | string | Sí | Identificador que empieza con `plt_`. | | `conexion_id` | string | Sí | Identificador que empieza con `con_`. | | `nombre` | string | Sí | | | `idioma` | string | Sí | | | `categoria` | "utilidad" \| "marketing" \| "autenticacion" | Sí | | | `estado` | "pendiente" \| "aprobada" \| "rechazada" \| "pausada" \| "deshabilitada" | Sí | | | `encabezado` | string \| null | Sí | | | `cuerpo` | string | Sí | | | `pie` | string \| null | Sí | | | `botones` | object[] | Sí | | | `botones[].tipo` | "respuesta_rapida" \| "url" \| "telefono" | Sí | | | `botones[].texto` | string | Sí | | | `variables` | integer | Sí | Cuántas variables espera el cuerpo. | | `motivo_rechazo` | string \| null | Sí | | | `creada_en` | string (date-time) | Sí | Fecha y hora ISO 8601 con la zona de Lima (-05:00). | | `actualizada_en` | string (date-time) | Sí | Fecha y hora ISO 8601 con la zona de Lima (-05:00). | ### Errores Cada código tiene su explicación en [Errores](https://docs.opennexum.com/errores/). - **400** [`validacion`](https://docs.opennexum.com/errores#validacion) - **401** [`clave_invalida`](https://docs.opennexum.com/errores#clave_invalida) - **403** [`permiso_faltante`](https://docs.opennexum.com/errores#permiso_faltante) - **404** [`no_encontrado`](https://docs.opennexum.com/errores#no_encontrado) - **409** [`idempotencia_en_conflicto`](https://docs.opennexum.com/errores#idempotencia_en_conflicto) - **409** [`solicitud_en_curso`](https://docs.opennexum.com/errores#solicitud_en_curso) - **409** [`ya_registrado`](https://docs.opennexum.com/errores#ya_registrado) - **429** [`limite_uso`](https://docs.opennexum.com/errores#limite_uso) - **500** [`error_interno`](https://docs.opennexum.com/errores#error_interno) - **501** [`operacion_no_disponible`](https://docs.opennexum.com/errores#operacion_no_disponible) - **502** [`servicio_externo_no_disponible`](https://docs.opennexum.com/errores#servicio_externo_no_disponible) - **503** [`no_disponible`](https://docs.opennexum.com/errores#no_disponible) --- Fuente: https://docs.opennexum.com/referencia/webhooks/webhook_crear/ # Registra un webhook > 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`. `POST /v1/conecta/webhooks` 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`. ## Ficha | Dato | Valor | |---|---| | Permiso | `webhooks:administrar` | | Cobro | No cobra. | | `Idempotency-Key` | Obligatoria | | Aprobación humana | Siempre: una persona la aprueba en el panel, sin importar la configuración de la clave. | | Herramienta MCP | No se ofrece a agentes. | ## Parámetros | Nombre | En | Requerido | Tipo | Descripción | |---|---|---|---|---| | `Idempotency-Key` | header | Sí | string | 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. | | `X-Request-Id` | header | No | string | Identificador de la petición. Va en cada respuesta; menciónalo al escribir a soporte. | ## Cuerpo `application/json`, obligatorio. Los campos anidados van con punto y los de listas con `[]`. No se aceptan campos desconocidos. | Campo | Tipo | Requerido | Descripción | |---|---|---|---| | `url` | string (uri) | Sí | Tu endpoint. Debe responder 2xx en menos de 10 segundos. | | `eventos` | "mensaje.recibido" \| "mensaje.estado" \| "conexion.estado" \| "plantilla.estado"[] | Sí | | | `descripcion` | string | No | | ## Ejemplo Contra el sandbox, con una clave `onx_test_…`: ```bash curl -X POST "https://api-sandbox.opennexum.com/v1/conecta/webhooks" \ -H "Authorization: Bearer onx_test_…" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "url": "https://ejemplo.com", "eventos": [ "mensaje.recibido" ] }' ``` ## Respuestas ### 201 Webhook creado; guarda `secreto` ahora. | Campo | Tipo | Requerido | Descripción | |---|---|---|---| | `webhook` | object | Sí | Webhook de tu sistema. | | `webhook.id` | string | Sí | Identificador que empieza con `whk_`. | | `webhook.url` | string (uri) | Sí | URL pública con https (sin IP literal, localhost, dominios internos ni usuario y clave). | | `webhook.eventos` | "mensaje.recibido" \| "mensaje.estado" \| "conexion.estado" \| "plantilla.estado"[] | Sí | | | `webhook.descripcion` | string \| null | Sí | | | `webhook.estado` | "activo" \| "pausado" | Sí | Se pausa solo si tu endpoint falla muchas veces seguidas. | | `webhook.creado_en` | string (date-time) | Sí | Fecha y hora ISO 8601 con la zona de Lima (-05:00). | | `webhook.secreto_rotado_en` | string (date-time) \| null | Sí | | | `secreto` | string | Sí | Secreto para verificar `X-Nexum-Signature`. Se muestra solo esta vez. | ### 202 Espera la aprobación de una persona. | Campo | Tipo | Requerido | Descripción | |---|---|---|---| | `estado` | "requiere_confirmacion" | Sí | | | `operacion_id` | string | Sí | Úsalo en `GET /v1/confirmaciones/{id}` para saber si se aprobó. | | `confirmacion_url` | string (uri) | Sí | Enlace del panel donde una persona aprueba o rechaza. Pásaselo tal cual. | | `consulta_url` | string | Sí | Ruta para consultar el estado. | | `expira_en` | string (date-time) | Sí | Si nadie aprueba antes, la operación vence y no se hace. | | `mensaje` | string | Sí | Qué falta, en palabras para una persona. | ### Errores Cada código tiene su explicación en [Errores](https://docs.opennexum.com/errores/). - **400** [`validacion`](https://docs.opennexum.com/errores#validacion) - **401** [`clave_invalida`](https://docs.opennexum.com/errores#clave_invalida) - **403** [`permiso_faltante`](https://docs.opennexum.com/errores#permiso_faltante) - **409** [`idempotencia_en_conflicto`](https://docs.opennexum.com/errores#idempotencia_en_conflicto) - **409** [`solicitud_en_curso`](https://docs.opennexum.com/errores#solicitud_en_curso) - **409** [`ya_registrado`](https://docs.opennexum.com/errores#ya_registrado) - **429** [`limite_uso`](https://docs.opennexum.com/errores#limite_uso) - **500** [`error_interno`](https://docs.opennexum.com/errores#error_interno) - **501** [`operacion_no_disponible`](https://docs.opennexum.com/errores#operacion_no_disponible) - **503** [`no_disponible`](https://docs.opennexum.com/errores#no_disponible) --- Fuente: https://docs.opennexum.com/referencia/webhooks/webhook_listar/ # Lista tus webhooks > Webhooks registrados, sus eventos y su estado. Nunca devuelve el secreto. `GET /v1/conecta/webhooks` Webhooks registrados, sus eventos y su estado. Nunca devuelve el secreto. ## Ficha | Dato | Valor | |---|---| | Permiso | `conecta:leer` | | Cobro | No cobra. | | `Idempotency-Key` | No aplica | | Herramienta MCP | `webhook_listar` (Próximamente) | ## Parámetros | Nombre | En | Requerido | Tipo | Descripción | |---|---|---|---|---| | `cursor` | query | No | string | Cursor opaco que devolvió la página anterior en `siguiente_cursor`. | | `limite` | query | No | integer | Cuántos elementos traer (1 a 100; por defecto 20). | | `X-Request-Id` | header | No | string | Identificador de la petición. Va en cada respuesta; menciónalo al escribir a soporte. | ## Ejemplo Contra el sandbox, con una clave `onx_test_…`: ```bash curl "https://api-sandbox.opennexum.com/v1/conecta/webhooks" \ -H "Authorization: Bearer onx_test_…" ``` ## Respuestas ### 200 Página de webhooks. | Campo | Tipo | Requerido | Descripción | |---|---|---|---| | `elementos` | object[] | Sí | | | `elementos[].id` | string | Sí | Identificador que empieza con `whk_`. | | `elementos[].url` | string (uri) | Sí | URL pública con https (sin IP literal, localhost, dominios internos ni usuario y clave). | | `elementos[].eventos` | "mensaje.recibido" \| "mensaje.estado" \| "conexion.estado" \| "plantilla.estado"[] | Sí | | | `elementos[].descripcion` | string \| null | Sí | | | `elementos[].estado` | "activo" \| "pausado" | Sí | Se pausa solo si tu endpoint falla muchas veces seguidas. | | `elementos[].creado_en` | string (date-time) | Sí | Fecha y hora ISO 8601 con la zona de Lima (-05:00). | | `elementos[].secreto_rotado_en` | string (date-time) \| null | Sí | | | `siguiente_cursor` | string \| null | Sí | Pásalo como `cursor` para la página siguiente; `null` si ya no hay más. | ### Errores Cada código tiene su explicación en [Errores](https://docs.opennexum.com/errores/). - **400** [`validacion`](https://docs.opennexum.com/errores#validacion) - **401** [`clave_invalida`](https://docs.opennexum.com/errores#clave_invalida) - **403** [`permiso_faltante`](https://docs.opennexum.com/errores#permiso_faltante) - **429** [`limite_uso`](https://docs.opennexum.com/errores#limite_uso) - **500** [`error_interno`](https://docs.opennexum.com/errores#error_interno) - **501** [`operacion_no_disponible`](https://docs.opennexum.com/errores#operacion_no_disponible) - **503** [`no_disponible`](https://docs.opennexum.com/errores#no_disponible) --- Fuente: https://docs.opennexum.com/referencia/webhooks/webhook_borrar/ # Borra un webhook > Deja de enviar eventos a ese endpoint y cancela las entregas pendientes. Según tu clave, puede esperar la aprobación de una persona. `DELETE /v1/conecta/webhooks/{id}` Deja de enviar eventos a ese endpoint y cancela las entregas pendientes. Según tu clave, puede esperar la aprobación de una persona. ## Ficha | Dato | Valor | |---|---| | Permiso | `webhooks:administrar` | | Cobro | No cobra. | | `Idempotency-Key` | No aplica | | Aprobación humana | Según la configuración de tu clave puede responder `202` `requiere_confirmacion`. | | Herramienta MCP | `webhook_borrar` (Próximamente) | ## Parámetros | Nombre | En | Requerido | Tipo | Descripción | |---|---|---|---|---| | `id` | path | Sí | string | Identificador que empieza con `whk_`. | | `X-Request-Id` | header | No | string | Identificador de la petición. Va en cada respuesta; menciónalo al escribir a soporte. | ## Ejemplo Contra el sandbox, con una clave `onx_test_…`: ```bash curl -X DELETE "https://api-sandbox.opennexum.com/v1/conecta/webhooks/whk_8f2c1a7d9e" \ -H "Authorization: Bearer onx_test_…" ``` ## Respuestas ### 202 Espera la aprobación de una persona. | Campo | Tipo | Requerido | Descripción | |---|---|---|---| | `estado` | "requiere_confirmacion" | Sí | | | `operacion_id` | string | Sí | Úsalo en `GET /v1/confirmaciones/{id}` para saber si se aprobó. | | `confirmacion_url` | string (uri) | Sí | Enlace del panel donde una persona aprueba o rechaza. Pásaselo tal cual. | | `consulta_url` | string | Sí | Ruta para consultar el estado. | | `expira_en` | string (date-time) | Sí | Si nadie aprueba antes, la operación vence y no se hace. | | `mensaje` | string | Sí | Qué falta, en palabras para una persona. | ### 204 Webhook borrado. ### Errores Cada código tiene su explicación en [Errores](https://docs.opennexum.com/errores/). - **400** [`validacion`](https://docs.opennexum.com/errores#validacion) - **401** [`clave_invalida`](https://docs.opennexum.com/errores#clave_invalida) - **403** [`permiso_faltante`](https://docs.opennexum.com/errores#permiso_faltante) - **404** [`no_encontrado`](https://docs.opennexum.com/errores#no_encontrado) - **429** [`limite_uso`](https://docs.opennexum.com/errores#limite_uso) - **500** [`error_interno`](https://docs.opennexum.com/errores#error_interno) - **501** [`operacion_no_disponible`](https://docs.opennexum.com/errores#operacion_no_disponible) - **503** [`no_disponible`](https://docs.opennexum.com/errores#no_disponible) --- Fuente: https://docs.opennexum.com/referencia/webhooks/webhook_probar/ # Envía un evento de prueba > Envía un evento `webhook.prueba` firmado y devuelve cómo respondió tu endpoint. `POST /v1/conecta/webhooks/{id}/probar` Envía un evento `webhook.prueba` firmado y devuelve cómo respondió tu endpoint. ## Ficha | Dato | Valor | |---|---| | Permiso | `webhooks:administrar` | | Cobro | No cobra. | | `Idempotency-Key` | No aplica | | Herramienta MCP | `webhook_probar` (Próximamente) | ## Parámetros | Nombre | En | Requerido | Tipo | Descripción | |---|---|---|---|---| | `id` | path | Sí | string | Identificador que empieza con `whk_`. | | `X-Request-Id` | header | No | string | Identificador de la petición. Va en cada respuesta; menciónalo al escribir a soporte. | ## Ejemplo Contra el sandbox, con una clave `onx_test_…`: ```bash curl -X POST "https://api-sandbox.opennexum.com/v1/conecta/webhooks/whk_8f2c1a7d9e/probar" \ -H "Authorization: Bearer onx_test_…" ``` ## Respuestas ### 200 Resultado de la entrega de prueba. | Campo | Tipo | Requerido | Descripción | |---|---|---|---| | `id` | string | Sí | Identificador que empieza con `ent_`. | | `webhook_id` | string | Sí | Identificador que empieza con `whk_`. | | `evento_id` | string | Sí | Identificador que empieza con `evt_`. | | `tipo_evento` | "mensaje.recibido" \| "mensaje.estado" \| "conexion.estado" \| "plantilla.estado" \| "webhook.prueba" | Sí | | | `estado` | "pendiente" \| "entregada" \| "fallida" \| "pausada" | Sí | | | `intentos` | integer | Sí | | | `ultimo_codigo_http` | integer \| null | Sí | | | `ultimo_error` | string \| null | Sí | | | `proximo_intento_en` | string (date-time) \| null | Sí | Reintentamos hasta 8 veces con espera creciente. | | `creada_en` | string (date-time) | Sí | Fecha y hora ISO 8601 con la zona de Lima (-05:00). | | `entregada_en` | string (date-time) \| null | Sí | | ### Errores Cada código tiene su explicación en [Errores](https://docs.opennexum.com/errores/). - **400** [`validacion`](https://docs.opennexum.com/errores#validacion) - **401** [`clave_invalida`](https://docs.opennexum.com/errores#clave_invalida) - **403** [`permiso_faltante`](https://docs.opennexum.com/errores#permiso_faltante) - **404** [`no_encontrado`](https://docs.opennexum.com/errores#no_encontrado) - **429** [`limite_uso`](https://docs.opennexum.com/errores#limite_uso) - **500** [`error_interno`](https://docs.opennexum.com/errores#error_interno) - **501** [`operacion_no_disponible`](https://docs.opennexum.com/errores#operacion_no_disponible) - **503** [`no_disponible`](https://docs.opennexum.com/errores#no_disponible) --- Fuente: https://docs.opennexum.com/referencia/webhooks/webhook_rotar_secreto/ # Rota el secreto de un webhook > Genera un secreto nuevo. Durante 24 horas firmamos con los dos (dos `v1` en la cabecera) para que cambies el tuyo sin perder eventos. `POST /v1/conecta/webhooks/{id}/rotar-secreto` Genera un secreto nuevo. Durante 24 horas firmamos con los dos (dos `v1` en la cabecera) para que cambies el tuyo sin perder eventos. ## Ficha | Dato | Valor | |---|---| | Permiso | `webhooks:administrar` | | Cobro | No cobra. | | `Idempotency-Key` | Obligatoria | | Herramienta MCP | No se ofrece a agentes. | ## Parámetros | Nombre | En | Requerido | Tipo | Descripción | |---|---|---|---|---| | `id` | path | Sí | string | Identificador que empieza con `whk_`. | | `Idempotency-Key` | header | Sí | string | 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. | | `X-Request-Id` | header | No | string | Identificador de la petición. Va en cada respuesta; menciónalo al escribir a soporte. | ## Ejemplo Contra el sandbox, con una clave `onx_test_…`: ```bash curl -X POST "https://api-sandbox.opennexum.com/v1/conecta/webhooks/whk_8f2c1a7d9e/rotar-secreto" \ -H "Authorization: Bearer onx_test_…" \ -H "Idempotency-Key: $(uuidgen)" ``` ## Respuestas ### 200 Secreto nuevo; guárdalo ahora. | Campo | Tipo | Requerido | Descripción | |---|---|---|---| | `webhook` | object | Sí | Webhook de tu sistema. | | `webhook.id` | string | Sí | Identificador que empieza con `whk_`. | | `webhook.url` | string (uri) | Sí | URL pública con https (sin IP literal, localhost, dominios internos ni usuario y clave). | | `webhook.eventos` | "mensaje.recibido" \| "mensaje.estado" \| "conexion.estado" \| "plantilla.estado"[] | Sí | | | `webhook.descripcion` | string \| null | Sí | | | `webhook.estado` | "activo" \| "pausado" | Sí | Se pausa solo si tu endpoint falla muchas veces seguidas. | | `webhook.creado_en` | string (date-time) | Sí | Fecha y hora ISO 8601 con la zona de Lima (-05:00). | | `webhook.secreto_rotado_en` | string (date-time) \| null | Sí | | | `secreto` | string | Sí | Secreto para verificar `X-Nexum-Signature`. Se muestra solo esta vez. | | `secreto_anterior_vence_en` | string (date-time) | Sí | Hasta entonces firmamos con los dos secretos. | ### Errores Cada código tiene su explicación en [Errores](https://docs.opennexum.com/errores/). - **400** [`validacion`](https://docs.opennexum.com/errores#validacion) - **401** [`clave_invalida`](https://docs.opennexum.com/errores#clave_invalida) - **403** [`permiso_faltante`](https://docs.opennexum.com/errores#permiso_faltante) - **404** [`no_encontrado`](https://docs.opennexum.com/errores#no_encontrado) - **409** [`idempotencia_en_conflicto`](https://docs.opennexum.com/errores#idempotencia_en_conflicto) - **409** [`solicitud_en_curso`](https://docs.opennexum.com/errores#solicitud_en_curso) - **409** [`ya_registrado`](https://docs.opennexum.com/errores#ya_registrado) - **429** [`limite_uso`](https://docs.opennexum.com/errores#limite_uso) - **500** [`error_interno`](https://docs.opennexum.com/errores#error_interno) - **501** [`operacion_no_disponible`](https://docs.opennexum.com/errores#operacion_no_disponible) - **503** [`no_disponible`](https://docs.opennexum.com/errores#no_disponible) --- Fuente: https://docs.opennexum.com/referencia/webhooks/entrega_listar/ # Lista entregas de eventos > Intentos de entrega a tus webhooks, con el código HTTP que respondió tu endpoint. `GET /v1/conecta/entregas` Intentos de entrega a tus webhooks, con el código HTTP que respondió tu endpoint. ## Ficha | Dato | Valor | |---|---| | Permiso | `conecta:leer` | | Cobro | No cobra. | | `Idempotency-Key` | No aplica | | Herramienta MCP | `entrega_listar` (Próximamente) | ## Parámetros | Nombre | En | Requerido | Tipo | Descripción | |---|---|---|---|---| | `cursor` | query | No | string | Cursor opaco que devolvió la página anterior en `siguiente_cursor`. | | `limite` | query | No | integer | Cuántos elementos traer (1 a 100; por defecto 20). | | `webhook_id` | query | No | string | Identificador que empieza con `whk_`. | | `estado` | query | No | string | | | `X-Request-Id` | header | No | string | Identificador de la petición. Va en cada respuesta; menciónalo al escribir a soporte. | ## Ejemplo Contra el sandbox, con una clave `onx_test_…`: ```bash curl "https://api-sandbox.opennexum.com/v1/conecta/entregas" \ -H "Authorization: Bearer onx_test_…" ``` ## Respuestas ### 200 Página de entregas. | Campo | Tipo | Requerido | Descripción | |---|---|---|---| | `elementos` | object[] | Sí | | | `elementos[].id` | string | Sí | Identificador que empieza con `ent_`. | | `elementos[].webhook_id` | string | Sí | Identificador que empieza con `whk_`. | | `elementos[].evento_id` | string | Sí | Identificador que empieza con `evt_`. | | `elementos[].tipo_evento` | "mensaje.recibido" \| "mensaje.estado" \| "conexion.estado" \| "plantilla.estado" \| "webhook.prueba" | Sí | | | `elementos[].estado` | "pendiente" \| "entregada" \| "fallida" \| "pausada" | Sí | | | `elementos[].intentos` | integer | Sí | | | `elementos[].ultimo_codigo_http` | integer \| null | Sí | | | `elementos[].ultimo_error` | string \| null | Sí | | | `elementos[].proximo_intento_en` | string (date-time) \| null | Sí | Reintentamos hasta 8 veces con espera creciente. | | `elementos[].creada_en` | string (date-time) | Sí | Fecha y hora ISO 8601 con la zona de Lima (-05:00). | | `elementos[].entregada_en` | string (date-time) \| null | Sí | | | `siguiente_cursor` | string \| null | Sí | Pásalo como `cursor` para la página siguiente; `null` si ya no hay más. | ### Errores Cada código tiene su explicación en [Errores](https://docs.opennexum.com/errores/). - **400** [`validacion`](https://docs.opennexum.com/errores#validacion) - **401** [`clave_invalida`](https://docs.opennexum.com/errores#clave_invalida) - **403** [`permiso_faltante`](https://docs.opennexum.com/errores#permiso_faltante) - **429** [`limite_uso`](https://docs.opennexum.com/errores#limite_uso) - **500** [`error_interno`](https://docs.opennexum.com/errores#error_interno) - **501** [`operacion_no_disponible`](https://docs.opennexum.com/errores#operacion_no_disponible) - **503** [`no_disponible`](https://docs.opennexum.com/errores#no_disponible) --- Fuente: https://docs.opennexum.com/referencia/webhooks/entrega_reintentar/ # Reintenta una entrega > Vuelve a encolar una entrega fallida o pausada. El evento conserva su `id` para que no lo dupliques. `POST /v1/conecta/entregas/{id}/reintentar` Vuelve a encolar una entrega fallida o pausada. El evento conserva su `id` para que no lo dupliques. ## Ficha | Dato | Valor | |---|---| | Permiso | `webhooks:administrar` | | Cobro | No cobra. | | `Idempotency-Key` | Opcional | | Herramienta MCP | `entrega_reintentar` (Próximamente) | ## Parámetros | Nombre | En | Requerido | Tipo | Descripción | |---|---|---|---|---| | `id` | path | Sí | string | Identificador que empieza con `ent_`. | | `Idempotency-Key` | header | No | string | 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. | | `X-Request-Id` | header | No | string | Identificador de la petición. Va en cada respuesta; menciónalo al escribir a soporte. | ## Ejemplo Contra el sandbox, con una clave `onx_test_…`: ```bash curl -X POST "https://api-sandbox.opennexum.com/v1/conecta/entregas/ent_8f2c1a7d9e/reintentar" \ -H "Authorization: Bearer onx_test_…" ``` ## Respuestas ### 202 Entrega en cola. | Campo | Tipo | Requerido | Descripción | |---|---|---|---| | `id` | string | Sí | Identificador que empieza con `ent_`. | | `webhook_id` | string | Sí | Identificador que empieza con `whk_`. | | `evento_id` | string | Sí | Identificador que empieza con `evt_`. | | `tipo_evento` | "mensaje.recibido" \| "mensaje.estado" \| "conexion.estado" \| "plantilla.estado" \| "webhook.prueba" | Sí | | | `estado` | "pendiente" \| "entregada" \| "fallida" \| "pausada" | Sí | | | `intentos` | integer | Sí | | | `ultimo_codigo_http` | integer \| null | Sí | | | `ultimo_error` | string \| null | Sí | | | `proximo_intento_en` | string (date-time) \| null | Sí | Reintentamos hasta 8 veces con espera creciente. | | `creada_en` | string (date-time) | Sí | Fecha y hora ISO 8601 con la zona de Lima (-05:00). | | `entregada_en` | string (date-time) \| null | Sí | | ### Errores Cada código tiene su explicación en [Errores](https://docs.opennexum.com/errores/). - **400** [`validacion`](https://docs.opennexum.com/errores#validacion) - **401** [`clave_invalida`](https://docs.opennexum.com/errores#clave_invalida) - **403** [`permiso_faltante`](https://docs.opennexum.com/errores#permiso_faltante) - **404** [`no_encontrado`](https://docs.opennexum.com/errores#no_encontrado) - **409** [`idempotencia_en_conflicto`](https://docs.opennexum.com/errores#idempotencia_en_conflicto) - **409** [`solicitud_en_curso`](https://docs.opennexum.com/errores#solicitud_en_curso) - **409** [`estado_no_permite`](https://docs.opennexum.com/errores#estado_no_permite) - **429** [`limite_uso`](https://docs.opennexum.com/errores#limite_uso) - **500** [`error_interno`](https://docs.opennexum.com/errores#error_interno) - **501** [`operacion_no_disponible`](https://docs.opennexum.com/errores#operacion_no_disponible) - **503** [`no_disponible`](https://docs.opennexum.com/errores#no_disponible) --- Fuente: https://docs.opennexum.com/referencia/eventos-webhook/ # Eventos de webhook > Qué te enviamos desde Nexum Conecta y cómo verificar la firma X-Nexum-Signature. **Evento de Nexum Conecta hacia tu sistema** Enviamos cada evento con `POST` a la URL de tu webhook, con el cuerpo en JSON y la cabecera `X-Nexum-Signature`. **Cómo verificar la firma** 1. Lee la cabecera: `t=,v1=`. Durante una rotación de secreto llegan dos `v1`. 2. Arma el texto `.` con el cuerpo exacto, sin volver a serializarlo. 3. Calcula HMAC-SHA256 de ese texto con tu secreto `whsec_…` y pásalo a hexadecimal. 4. 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. **Cómo responder** Responde 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. ## Campos del evento | Campo | Tipo | Requerido | Descripción | |---|---|---|---| | `id` | string | Sí | Único por evento: úsalo para no procesar dos veces el mismo. | | `creado_en` | string (date-time) | Sí | Fecha y hora ISO 8601 con la zona de Lima (-05:00). | | `version` | "v1" | Sí | | | `conexion_id` | string \| null | Sí | | | `tipo` | "mensaje.recibido" | Sí | | | `datos` | object | Sí | | | `datos.mensaje` | object | No | Mensaje enviado o recibido. | | `datos.mensaje.id` | string | No | Identificador que empieza con `msg_`. | | `datos.mensaje.conexion_id` | string | No | Identificador que empieza con `con_`. | | `datos.mensaje.conversacion_id` | string | No | Identificador que empieza con `cnv_`. | | `datos.mensaje.canal` | "whatsapp" \| "instagram" \| "messenger" | No | | | `datos.mensaje.direccion` | "saliente" \| "entrante" | No | | | `datos.mensaje.tipo` | "texto" \| "media" \| "plantilla" \| "interactivo" \| "otro" | No | | | `datos.mensaje.texto` | string \| null | No | | | `datos.mensaje.media` | object \| null | No | En mensajes entrantes, la URL es nuestra y vence en unas horas. | | `datos.mensaje.media.tipo` | "imagen" \| "video" \| "audio" \| "documento" | No | | | `datos.mensaje.media.url` | string (uri) | No | | | `datos.mensaje.media.nombre_archivo` | string \| null | No | | | `datos.mensaje.media.leyenda` | string \| null | No | | | `datos.mensaje.plantilla` | object \| null | No | | | `datos.mensaje.plantilla.nombre` | string | No | | | `datos.mensaje.plantilla.idioma` | string | No | | | `datos.mensaje.estado` | "en_cola" \| "enviado" \| "entregado" \| "leido" \| "fallido" \| "incierto" \| "recibido" | No | `incierto`: el proveedor no confirmó; revisa antes de reenviar. `recibido`: mensaje entrante. | | `datos.mensaje.error` | object \| null | No | | | `datos.mensaje.error.codigo` | string | No | | | `datos.mensaje.error.mensaje` | string | No | | | `datos.mensaje.creado_en` | string (date-time) | No | Fecha y hora ISO 8601 con la zona de Lima (-05:00). | | `datos.mensaje.actualizado_en` | string (date-time) | No | Fecha y hora ISO 8601 con la zona de Lima (-05:00). | | `datos.conversacion` | object | No | Conversación con un contacto en un canal. | | `datos.conversacion.id` | string | No | Identificador que empieza con `cnv_`. | | `datos.conversacion.conexion_id` | string | No | Identificador que empieza con `con_`. | | `datos.conversacion.canal` | "whatsapp" \| "instagram" \| "messenger" | No | | | `datos.conversacion.contacto` | object | No | | | `datos.conversacion.contacto.nombre` | string \| null | No | | | `datos.conversacion.contacto.telefono` | string \| null | No | | | `datos.conversacion.contacto.usuario` | string \| null | No | Usuario de Instagram, si aplica. | | `datos.conversacion.ventana` | object | No | Ventana de atención: mientras está abierta puedes escribir libre; si no, solo plantillas. | | `datos.conversacion.ventana.abierta` | boolean | No | | | `datos.conversacion.ventana.cierra_en` | string (date-time) \| null | No | | | `datos.conversacion.ventana.tipo` | "24h" \| "72h" \| null | No | 72h cuando el contacto llegó por un anuncio. | | `datos.conversacion.no_leidos` | integer | No | | | `datos.conversacion.ultimo_mensaje_en` | string (date-time) \| null | No | | | `datos.conversacion.creada_en` | string (date-time) | No | Fecha y hora ISO 8601 con la zona de Lima (-05:00). | | `datos.mensaje_id` | string | No | Identificador que empieza con `msg_`. | | `datos.conversacion_id` | string | No | Identificador que empieza con `cnv_`. | | `datos.estado` | "en_cola" \| "enviado" \| "entregado" \| "leido" \| "fallido" \| "incierto" \| "recibido" | No | `incierto`: el proveedor no confirmó; revisa antes de reenviar. `recibido`: mensaje entrante. | | `datos.error` | object \| null | No | | | `datos.error.codigo` | string | No | | | `datos.error.mensaje` | string | No | | | `datos.actualizado_en` | string (date-time) | No | Fecha y hora ISO 8601 con la zona de Lima (-05:00). | | `datos.conexion` | object | No | Conexión de un número de WhatsApp, una cuenta de Instagram o una página de Messenger. | | `datos.conexion.id` | string | No | Identificador que empieza con `con_`. | | `datos.conexion.proveedor` | "zernio" \| "ycloud" \| "meta" | No | Por dónde sale la conexión. Puedes pasar un número de un proveedor a otro sin cambiar tu integración. | | `datos.conexion.canal` | "whatsapp" \| "instagram" \| "messenger" | No | | | `datos.conexion.nombre` | string | No | | | `datos.conexion.estado` | "pendiente" \| "activa" \| "desconectada" \| "error" | No | | | `datos.conexion.telefono` | string \| null | No | | | `datos.conexion.cuenta` | string \| null | No | Usuario de Instagram o página de Facebook, si aplica. | | `datos.conexion.alta_url` | string (uri) \| null | No | Mientras está `pendiente`: dónde termina el alta una persona. | | `datos.conexion.creada_en` | string (date-time) | No | Fecha y hora ISO 8601 con la zona de Lima (-05:00). | | `datos.conexion.ultima_prueba_en` | string (date-time) \| null | No | | | `datos.plantilla` | object | No | Plantilla de mensaje. | | `datos.plantilla.id` | string | No | Identificador que empieza con `plt_`. | | `datos.plantilla.conexion_id` | string | No | Identificador que empieza con `con_`. | | `datos.plantilla.nombre` | string | No | | | `datos.plantilla.idioma` | string | No | | | `datos.plantilla.categoria` | "utilidad" \| "marketing" \| "autenticacion" | No | | | `datos.plantilla.estado` | "pendiente" \| "aprobada" \| "rechazada" \| "pausada" \| "deshabilitada" | No | | | `datos.plantilla.encabezado` | string \| null | No | | | `datos.plantilla.cuerpo` | string | No | | | `datos.plantilla.pie` | string \| null | No | | | `datos.plantilla.botones` | object[] | No | | | `datos.plantilla.botones[].tipo` | "respuesta_rapida" \| "url" \| "telefono" | No | | | `datos.plantilla.botones[].texto` | string | No | | | `datos.plantilla.variables` | integer | No | Cuántas variables espera el cuerpo. | | `datos.plantilla.motivo_rechazo` | string \| null | No | | | `datos.plantilla.creada_en` | string (date-time) | No | Fecha y hora ISO 8601 con la zona de Lima (-05:00). | | `datos.plantilla.actualizada_en` | string (date-time) | No | Fecha y hora ISO 8601 con la zona de Lima (-05:00). | | `datos.webhook_id` | string | No | Identificador que empieza con `whk_`. |