Ir al contenido

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)
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

Contra el sandbox, con una clave onx_test_…:

Ventana de terminal
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"
}
}'

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.

Cada código tiene su explicación en Errores.