Entrega al comprador

Cómo hacer que Cufy le envíe la factura por correo a tu cliente, cómo saber si llegó y qué hacer si rebotó.

Emitir una factura y entregársela al comprador son dos cosas distintas. Puedes encargarte tú —descargas el PDF y lo envías con tus medios— o dejar que Cufy mande el correo.

En el sandbox el correo solo llega a ti

Una cuenta del sandbox solo puede entregar a la dirección de la persona dueña de la cuenta. Cualquier otro destinatario recibe 403 SANDBOX_RECIPIENT_NOT_ALLOWED. Es para que nadie use el sandbox para mandar correo a terceros. Si quieres probar avisos hacia tu sistema, usa webhooks.

Elegir quién entrega

Tu cuenta nace con la entrega desactivada: mode: external, automatic: false, sin destinatarios. Es decir, te encargas tú.

Para que Cufy entregue, consulta primero GET /v1/company/delivery-settings y guarda su ETag; luego actualiza con PUT /v1/company/delivery-settings, mandando ese ETag en If-Match:

{
  "mode": "cufy_email",
  "automatic": true,
  "recipients": ["tu-correo@example.com"],
  "reason": "Activar la entrega automática"
}

Hasta cinco direcciones. Solo direcciones: ni nombres ni cabeceras. Los duplicados se rechazan sin mirar mayúsculas.
Estos destinatarios son independientes del correo fiscal del comprador (buyer.email).
Cambiar la configuración no afecta a lo ya emitido: cada admisión congela la configuración vigente. No hay forma de reenviar documentos viejos cambiando esto.

También puedes decidirlo factura por factura, con el campo delivery:

Qué envías	Qué pasa
`{"mode": "external"}`	Esta factura no se entrega. Te encargas tú.
`{"mode": "cufy_email", "recipients": […]}`	Esta factura va a esos destinatarios.
Nada	Se aplica la configuración de la empresa.

Para que una factura se admita con entrega automática, tu API key necesita el permiso documents:deliver.

GET /v1/company/delivery-preflight te dice si la configuración y tu clave alcanzan, antes de emitir nada.

Qué se envía y cuándo

La entrega se programa cuando la revisión se valida, y espera a que estén listos todos sus archivos. Nunca se manda un paquete incompleto.

En el sandbox, que emite en habilitación, el correo lleva el PDF, el XML firmado, la respuesta de la DIAN y el AttachedDocument firmado.

Enviar una copia a mano

{
  "revision": 1,
  "recipients": ["tu-correo@example.com"],
  "reason": "Solicitar copia de la revisión validada"
}

Va a POST /v1/documents/{id}/deliveries con su Idempotency-Key. No vuelve a emitir, ni a firmar, ni a cobrar: solo reenvía.

Límites: diez solicitudes manuales por documento y revisión cada hora, y cien destinatarios activos por empresa. Pedir una segunda entrega al mismo destinatario mientras la primera sigue pendiente devuelve conflicto.

Saber si llegó

Document.delivery_status resume la entrega más reciente. Para el detalle, GET /v1/documents/{id}/deliveries y GET /v1/deliveries/{id}/attempts.

Estado	Qué significa
`not_ready`	Todavía no hay entrega, o faltan archivos del paquete.
`queued`	Hay trabajo pendiente o en curso.
`sent`	El proveedor de correo aceptó el mensaje. Aún no hay confirmación de entrega.
`delivery_confirmed`	El servidor del destinatario confirmó que lo recibió. No significa que lo hayan leído ni aceptado.
`failed`	Un destinatario falló definitivamente, o se agotaron los intentos.
`action_required`	Hace falta que hagas algo; mira `recovery_action`.

Los rebotes y las quejas que llegan después aparecen como fallos. Un timeout deja el resultado incierto y no se reenvía solo: se concilia consultando.

Cuando algo no llegó

POST /v1/deliveries/{id}/retries, con reason e Idempotency-Key, conserva destinatarios y archivos y no reenvía a quien ya confirmó. Antes de llamarlo, mira recovery_action en recipient_results:

`recovery_action`	Qué hacer
`reconcile`	Reintenta para reanudar la conciliación. No vuelve a enviar nada.
`retry_after_fix`	Corrige la causa y luego reintenta.
`wait`	Hay trabajo en curso. Espera.
`none`	No hay nada que recuperar.
`new_delivery`	Este intento está muerto. Crea una entrega manual nueva.

Una dirección mal escrita no se arregla reintentando: crea una entrega manual con la dirección corregida.