Entrega al comprador

Configurar destinatarios, entregar documentos por correo, consultar recibos y recuperar entregas fallidas.

Canales

Canal	Qué hace
`local_test`	Guarda mensajes MIME en un receptor local. No envía correo real.
`aws_ses`	Envía correo real desde una identidad SES verificada. Lo configura el operador en el despliegue.

channel_status: configured indica que hay configuración, no que el proveedor esté disponible.

Configurar la empresa

La configuración inicial es mode: external, automatic: false, recipients: []. Los destinatarios son independientes del correo fiscal del comprador.

Consulta GET /v1/company/delivery-settings (company:read) y guarda su ETag.
Actualiza con PUT /v1/company/delivery-settings, con If-Match, Idempotency-Key y los permisos company:write y documents:deliver:

{
  "mode": "trifaco_email",
  "automatic": true,
  "recipients": ["comprador@example.com"],
  "reason": "Probar entrega automática con receptor local"
}

Hasta cinco direcciones distintas, sin nombres ni cabeceras libres. Se rechazan duplicados sin distinguir mayúsculas.
Las admisiones nuevas congelan la configuración por revisión. Cambiarla no modifica trabajos anteriores ni envía documentos históricos.
Por documento: delivery: {"mode":"external"} lo excluye; delivery: {"mode":"trifaco_email","recipients":[…]} elige sus destinatarios. La clave emisora necesita documents:deliver para admitir una entrega automática.

GET /v1/company/delivery-preflight comprueba la configuración y el permiso de tu clave antes de entregar. No consulta a AWS: provider_status=not_checked.

Qué se envía

Al validarse la revisión se programa la entrega y espera sus archivos:

Simulación: PDF y XML de ensayo.
Habilitación: PDF, XML firmado, respuesta DIAN y AttachedDocument firmado.

No se envían paquetes incompletos. Si se alcanza el límite al validar, la entrega queda fallida con DELIVERY_ADMISSION_LIMIT; la validación fiscal no se revierte.

Entrega manual

POST /v1/documents/{id}/deliveries (documents:deliver, Idempotency-Key):

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

Máximo diez solicitudes manuales por documento y revisión por hora, y cien destinatarios activos por empresa y ambiente.
Una segunda entrega al mismo destinatario con resultado pendiente o incierto devuelve conflicto.
No vuelve a emitir, firmar ni cobrar el documento.

Consultar

GET /v1/documents/{id}/deliveries, GET /v1/deliveries/{id} y GET /v1/deliveries/{id}/attempts (documents:read), con paginación. Document.delivery_status resume la entrega más reciente de la revisión.

Estado	Significado
`not_ready`	No hay entrega o faltan archivos del paquete.
`queued`	Trabajo pendiente o en curso.
`sent`	El proveedor aceptó el mensaje; aún sin confirmación.
`delivery_confirmed`	El servidor receptor confirmó la entrega. No acredita lectura ni aceptación comercial.
`failed`	Un destinatario con fallo definitivo o intentos agotados.
`action_required`	Hace falta intervención: archivos fallidos, proveedor cambiado o resultado incierto agotado.

Con SES, las quejas y rebotes posteriores aparecen como fallos. Un timeout conserva la incertidumbre y consulta el registro de eventos; no se reenvía automáticamente.

POST /v1/deliveries/{id}/retries con reason, Idempotency-Key y documents:deliver. Conserva destinatarios, identidad del proveedor y archivos; los confirmados no se reenvían. Guíate por recipient_results:

`recovery_action`	Qué hacer
`reconcile`	Reintentar para reanudar la conciliación. No vuelve a enviar.
`retry_after_fix`	Corregir la causa (por ejemplo `DELIVERY_SES_ACCESS_DENIED`) y reintentar.
`wait`	Hay trabajo en curso.
`none`	No hay nada que recuperar.
`new_delivery`	La reserva es terminal: crea una entrega manual nueva.

Para corregir una dirección, crea una entrega manual distinta.

Canal local de ensayo

Con el entorno local preparado y las migraciones aplicadas:

npm run dev:delivery
npm run start:delivery-receiver
npm run start:delivery
DELIVERY_TEST_URL=http://127.0.0.1:3081 npm run start:api

dev:delivery se ejecuta una sola vez: crea un token privado y .local/delivery.env. El receptor escucha solo en 127.0.0.1 y guarda mensajes y recibos en .local/delivery/inbox. Resultado predeterminado accepted; configura DELIVERY_TEST_OUTCOME=confirmed o bounced antes de arrancarlo. Límites: 8 MiB por adjunto, 48 MiB por mensaje, 64 MiB por solicitud y dos trabajos simultáneos. El worker fiscal debe estar activo para generar el paquete.

Operación de SES para operadores: SES-OPERATIONS. Validación: TRI-015.