Skip to main content
POST
Cada factura dice por qué canales le llegó al comprador y, si un canal falló, se puede reintentar.

El bloque delivery

Viene en la respuesta de POST /invoices y en la consulta de una factura (GET /invoices/{id}, por CUF, por Idempotency-Key y la herramienta MCP obtenerFactura). No viene en los listados ni en los lotes. Las notas de crédito-débito y los documentos rechazados por el SIN no lo traen. Siempre son tres elementos, en este orden: whatsapp, telegram, email.
La API nunca devuelve el teléfono, el correo ni el id de Telegram completos en este bloque.

Estados

La entrega corre después de responder la emisión: consultá la factura unos segundos más tarde para ver el resultado.

Recibido y leído (WhatsApp)

deliveredAt y readAt se actualizan cuando consultás la factura (GET /invoices/{id} u obtenerFactura). Para mostrarlo en vivo, consultá cada 3 segundos mientras el canal esté ENTREGADO sin readAt, y dejá de hacerlo a los pocos minutos. Si WhatsApp rechaza el mensaje después de aceptarlo (por ejemplo, el número no tiene WhatsApp), el canal pasa a FALLIDO con proveedor_<código> y retryable: true.

Motivos

La lista puede crecer: tratá un reason que no conozcas según su status.

Reintentar un canal

POST /api/v3/invoices/{id}/delivery/{channel}/retry Envía de nuevo la factura por ese canal y responde cómo quedó. Se puede cuando retryable es true, o cuando el canal está OMITIDO por sin_dato o destino_suprimido y mandás otro destino en to.

Path Parameters

Body (opcional)

to vale para ese envío y no cambia la factura. Si el reintento con to vuelve a fallar, el siguiente tiene que traer to otra vez.

Reglas

  • Un canal ENTREGADO responde 200 con su estado y no envía nada: repetir el pedido no repite el mensaje.
  • De dos pedidos simultáneos sobre el mismo canal, uno envía y el otro recibe 409.
  • PENDIENTE y ENVIANDO responden 409 mientras la entrega está en curso. Un ENVIANDO sin cambios por 15 minutos pasa a retryable: true.
  • Una factura anulada no se entrega (409).
  • El reintento cuenta en los mismos cupos de mensajes que la entrega automática.

Límites

Superado cualquiera, 429 con error.code = RATE_LIMITED y Retry-After.

Respuestas

Vincular Telegram

Telegram no deja que un bot le escriba a quien no lo abrió. Para entregarle facturas por Telegram, el comprador escanea un QR una sola vez. Tu empresa tiene que tener activa la entrega por Telegram (si no, 409).
  1. Pedí el enlace con una referencia tuya del comprador (el id de su ficha, sin datos personales).
  2. Mostrá deepLink como QR. Es de un solo uso y vence en expiresAt.
  3. Consultá cada 2 o 3 segundos hasta linked.
  4. Guardá telegramUserId en tu cliente y mandalo como clientTelegramUserId en sus facturas. Para una factura ya emitida, reintentá telegram con {"to": "<telegramUserId>"}.
ref: hasta 120 caracteres entre letras, números y : . _ -.
201
200 (vinculado)
Por MCP: vincularTelegram, consultarVinculoTelegram y desvincularTelegram, con ref como único argumento.