Envío por email

Envía una factura emitida a tu cliente por email, con su PDF y los formatos electrónicos que tenga configurados.

Todas las rutas cuelgan de https://app.faxtal.com/api/v1.1 y se autentican con la cabecera X-API-Key (ver Autenticación).

Enviar una factura

POST /api/v1.1/issued-invoices/{invoice_id}/send

Permiso de la clave: invoices:write.

Llama a este endpoint solo con facturas en estado issued o sent. Para reenviar una factura ya enviada, vuelve a llamarlo.

Qué enviar

El cuerpo es opcional.

Campo	Tipo	Descripción
`to`	array de emails (máx. 20) \| `null`	Destinatarios de este envío. Si lo omites, se resuelven automáticamente.

No admite otros campos: el asunto, el cuerpo y los adjuntos no se eligen por petición.

curl -s -X POST "https://app.faxtal.com/api/v1.1/issued-invoices/00000000-0000-0000-0000-000000000001/send" \
  -H "X-API-Key: fctXXXXXXXX_YYYYYYYYYYYYYYYY" \
  -H "Content-Type: application/json" \
  -d '{"to": ["facturacion@cliente-prueba.es"]}'

Respuesta

{
  "invoice_id": "00000000-0000-0000-0000-000000000001",
  "sent_to": ["facturacion@cliente-prueba.es"]
}

sent_to son las direcciones a las que ha salido el email.

Destinatarios

Si no envías to, se usan, por este orden, los primeros que existan:

Los destinatarios fijados para esa factura en la aplicación.
El email del cliente de la factura (invoice.customer.electronic_mail), junto con los contactos del cliente marcados para recibir facturas.
El email del contacto principal del cliente.

El cliente se localiza entre tus terceros por el NIF de la factura. Las direcciones repetidas se envían una vez, sin distinguir mayúsculas. Si no queda ninguna, la API responde 422 no_recipient_email.

Adjuntos

PDF, siempre. Si la factura ya tiene un PDF guardado, se reutiliza. Si no, se genera con la plantilla de la empresa y se guarda en los documentos de la factura.
Formatos electrónicos configurados en la ficha del cliente, en la aplicación: facturae_3_2_1, facturae_3_2_2, ubl_2_1 o cii_d16b. También se reutilizan si ya existen o se generan y se guardan.

Si un formato configurado no se puede generar, no sale el email. Por ejemplo, UBL de una factura con retención (ver Formatos y exportación).

Los ficheros generados quedan en GET /api/v1.1/issued-invoices/{invoice_id}/documents.

Asunto, cuerpo y remitente

El asunto y el cuerpo salen de la plantilla de email de facturas de la empresa, con su marca. Se configuran en la aplicación.
El nombre del remitente y la dirección de respuesta son los de la plantilla o, si no los fija, los de la empresa.
El email se envía en español.

Efecto en la factura

El estado pasa a sent. Si ya era sent, sigue igual.
Se registra el evento sent, con los destinatarios en details.sent_to. Consúltalo en GET /api/v1.1/issued-invoices/{invoice_id}/events.

Errores

Los errores llegan con el formato {"detail": {"code": "...", "message": "...", "request_id": "..."}} (ver Errores).

HTTP	`code`	Causa
`403`	`scope_missing`	La clave no tiene `invoices:write`.
`404`	`invoice_not_found`	La factura no existe en la empresa de la clave o es una recibida.
`422`	`no_recipient_email`	No has enviado `to` y no hay ningún email que resolver.
`422`	`request_validation_error`	`to` trae un email no válido o más de 20 direcciones, o el cuerpo lleva campos desconocidos.

Envío masivo y seguimiento

La API no tiene endpoint para enviar varias facturas en bloque ni para consultar el seguimiento de entregas. Para varias facturas, llama a send una vez por factura. El envío masivo y su historial están en la aplicación.