Envío de documentos

Usa la operación de envío del tipo de documento que necesites, con su scope de envío y la cabecera de idempotencia declarada. Enviar, marcar como enviado, descargar un PDF y presentar en FACe son operaciones distintas. Una petición aceptada por la API no demuestra que el destinatario haya recibido el correo; consulta el registro de entrega de correos.

curl -X POST "https://api.factuarea.com/v1/companies/$COMPANY_ID/invoices/$INVOICE_ID/send" \
  -H "Authorization: Bearer $FACTUAREA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: send-fac-2026-00042" \
  --data '{
  "to": "facturacion@acme.example"
}'

Todas las rutas de esta guía cuelgan de /v1/companies/{company}/…: {company} es el id (UUID v7) del NIF con el que operas, y en los ejemplos curl es $COMPANY_ID. Alcanzar un NIF explica cómo resolverlo.

Cuándo cuenta una factura como enviada

En las facturas, enviar no es emitir. POST /v1/companies/{company}/invoices/{invoice}/send emite antes el borrador si hace falta y después lo envía por correo; la factura solo queda marcada como enviada cuando el servidor de correo acepta el email de entrega. Un correo en cola o fallido, un recordatorio de pago y el correo de un borrador que nunca se emitió no ponen la marca. La marca conserva la primera entrega: un reenvío no la mueve.

Campo (versión de la API `2026-10-01`)	Valor
`is_sent`	`true` en cuanto se registra una entrega.
`sent_at`	Instante de la primera entrega.
`sent_via`	`email` para un email de entrega aceptado, `manual` para una marca que pones tú.

Si entregas una factura emitida por un canal propio (WhatsApp, papel, un portal), regístralo con POST /v1/companies/{company}/invoices/{invoice}/mark-sent y Factuarea-Version: 2026-10-01; en las versiones anteriores esa operación emite un borrador. Borra una marca errónea con POST /v1/companies/{company}/invoices/{invoice}/unsend, que nunca cambia el estado ni el número. Suscríbete a invoice.marked_sent e invoice.unsent para seguir la marca y filtra las entregas pendientes con is_sent=false. Consulta Trabajar con facturas.

Identidad del remitente

Cuando se aplica la comprobación de identidad del remitente, una suscripción activa de Factuarea o una identificación censal aceptada acreditan su identidad. Introducir los datos de una tarjeta no es la condición que consulta el servicio. Una respuesta censal ausente o no disponible no acredita identidad; la suscripción activa sigue siendo una alternativa.

El rechazo usa 422 sender_identity_not_verified. Completa la verificación censal o activa la suscripción y después reintenta el envío previsto. Esta guía describe el comportamiento cuando la comprobación está activa; su aplicación depende de la configuración del servicio.

Identidad heredada de otra empresa

La identidad que se comprueba no siempre es la del NIF que envía. Un NIF toma su identidad de remitente, y el régimen de una cuenta nueva, de la empresa de la que hereda su confianza, con las señales y las reglas de esa empresa. Son tres reglas y un solo salto, las mismas que recoge identidad para el envío de documentos en la cartera de NIF:

Un NIF de una cuenta que no es gestionada, distinto de su empresa titular, porque la cuenta lo compró, lo recibió por traspaso o lo dio de alta, hereda de la empresa titular de su propia cuenta. La empresa titular no hereda de nadie, y una empresa sin cuenta tampoco.
Un NIF de una cuenta gestionada hereda de la empresa titular de la cuenta del proveedor mientras dure la gestión. Cuando la gestión termina, vuelve a la regla anterior, con su propia empresa titular, y nunca sigue heredando del proveedor.
Un NIF al que llegas por un acceso cedido no hereda nada de la cuenta receptora. Su confianza sigue siendo la de la empresa titular de su propia cuenta.

Heredar no es quedar exento: si la empresa de la que hereda un NIF está en el régimen de una cuenta nueva, el NIF recibe el mismo régimen. El salto es de un solo nivel, y una identidad que no se puede leer nunca acredita nada.

Un 422 sender_identity_not_verified se refiere a esa empresa. En error.details.resolved_against, own_company significa que la identidad se comprobó contra el propio NIF, y managing_company que se comprobó contra la empresa de la que hereda el NIF. En el segundo caso tiene que actuar la otra empresa: su suscripción activa o su identificación censal aceptada es lo que acredita la identidad, así que su titular registra un método de pago o verifica su NIF en el censo. No pidas al NIF, ni al cliente de una cuenta gestionada, que contrate una suscripción propia: un NIF de una cuenta no tiene ninguna que contratar, y la paga la cuenta.

Modo de prueba

Una empresa de sandbox, sobre la que opera una clave fact_test_, no la evalúa la comprobación de identidad, así que nunca recibe sender_identity_not_verified. Sigue sujeta a la supresión del modo de prueba: los correos de documentos no se entregan a destinatarios reales.

Gestiona los fallos de envío

La identidad acreditada no elimina las cuotas de correo ni los demás presupuestos de la cuenta. Un 429 requiere la actuación y el tiempo de reintento indicados en la respuesta de límites; los reintentos inmediatos no lo resuelven. Un error de validación requiere corregir su campo. Conserva request_id al investigar una petición aceptada con una entrega inesperada. autosend_enabled de la tienda usa las mismas garantías de envío.

El PDF al enviar

Enviar solo encola el correo. El PDF se prepara y se renderiza después de que tu petición se confirme, a partir del original capturado con el documento, y la respuesta es el documento actualizado. Su pdf_output_state puede seguir pendiente, así que no esperes por él: confirma la entrega en el registro de entrega de correos y, si necesitas el fichero, sigue el bucle de reintento de vistas previas y artefactos PDF.

Cuando la salida revisionada está activa para tu empresa (render_activation es revisioned en GET /v1/companies/{company}/pdf-templates/defaults), las operaciones que emiten, envían o aceptan un documento necesitan la precondición de presentación: el contexto revisado que aprobaste. Tiene exactamente siete campos, todos o ninguno:

Campo	Sale de
`expected_selection_version`	`selection_version` de la vista previa
`expected_source_token`	`source_token`
`expected_preview_context_fingerprint`	`expected_preview_context_fingerprint`
`expected_template_revision_id`	`template_revision_id` (debe estar presente, puede ser `null`)
`expected_commercial_identity_revision_id`	`commercial_identity_revision_id` (presente, puede ser `null`)
`purpose`, `format`	Los que previsualizaste

Obtén los valores previsualizando el borrador con source.kind: persisted_draft en vistas previas y artefactos PDF. Dónde van:

Operación	Dónde
`POST /v1/companies/{company}/invoices/{invoice}/send` y emitir una factura	Los siete campos en el nivel superior del cuerpo
Enviar y aceptar presupuestos y facturas proforma, enviar albaranes	Objeto `presentation_precondition`
Envío masivo y cambio de estado masivo	`presentation_preconditions`, un mapa indexado por UUID de documento

Sin ella la operación responde 428 pdf_presentation_precondition_required. Un contexto que cambió desde tu vista previa responde 409 (pdf_presentation_conflict o pdf_presentation_context_changed); una factura cuyos datos legales cambiaron responde 409 pdf_legal_source_changed y su envío queda bloqueado hasta que la revises; y un campo mal formado responde 422 pdf_presentation_invalid. Mientras la salida revisionada no esté activa para tu empresa, la precondición se ignora y la operación se comporta como antes. Vuelve a previsualizar, revisa y envía con los valores nuevos.

Adjuntar el XML FacturaE

POST /v1/companies/{company}/invoices/{invoice}/send puede adjuntar el XML FacturaE de la factura. Necesita el módulo FacturaE.

Campo	Significado
`attach_facturae`	`true` adjunta el XML. Sin `submission_id` se genera a partir de la factura en ese momento.
`submission_id`	UUID de un envío a FACe de esta factura. Solo se acepta con `attach_facturae: true`, y adjunta exactamente el XML retenido para ese intento, sin generar uno nuevo.

curl -X POST "https://api.factuarea.com/v1/companies/$COMPANY_ID/invoices/$INVOICE_ID/send" \
  -H "Authorization: Bearer fact_test_3pXnR2VbY7TcA9eFmN5z8KqW" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: send-fac-2026-00042-xml" \
  --data '{
  "to": "facturacion@acme.example",
  "attach_facturae": true,
  "submission_id": "0199f410-6a2b-7d31-8c5f-9e1a3b7d4c28"
}'

Publicar una versión en el enlace público

PATCH /v1/companies/{company}/invoices/{invoice}/public-link (y la misma operación de presupuestos, facturas proforma y albaranes) acepta action revoke, activate, extend (con extend_days), reset y publish. publish vincula el PDF capturado exacto al enlace público y exige publication_context; las demás acciones lo rechazan:

{
  "action": "publish",
  "publication_context": {
    "presentation_id": "0199f401-33de-7a8c-9e15-b7c4d2a60f38",
    "expected_binding_version": 3
  }
}

presentation_id es el id y expected_binding_version el binding_version del bloque presentation del documento. Si la versión está desfasada, la petición responde 409 y conserva la publicación anterior: vuelve a leer el documento. El PATCH no devuelve una URL utilizable; lee el enlace con GET /v1/companies/{company}/invoices/{invoice}/public-link y usa publication.public_url solo cuando publication.state es ready. Es null mientras el enlace está revocado o caducado, o tras un borrado por privacidad. Consulta las operaciones de facturas, presupuestos y albaranes.

Envío de documentos

En esta página