Beta privada · apertura 23 de diciembre
Envía un comprobante por mensaje
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.
| 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
Sección titulada «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. |
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
Sección titulada «Ejemplo»Contra el sandbox, con una clave onx_test_…:
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
Sección titulada «Respuestas»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). |
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í | Antes de esta hora hay que aprobarla Y repetir la petición; si no, vence y no se hace. |
mensaje |
string | Sí | Qué falta, en palabras para una persona. |
Errores
Sección titulada «Errores»Cada código tiene su explicación en Errores.
- 400
validacion - 401
clave_invalida - 402
saldo_insuficiente - 402
tope_alcanzado - 403
permiso_faltante - 404
no_encontrado - 409
idempotencia_en_conflicto - 409
solicitud_en_curso - 409
ventana_cerrada - 409
estado_no_permite - 429
limite_uso - 500
error_interno - 501
operacion_no_disponible - 502
servicio_externo_no_disponible - 503
no_disponible