Enviament de documents

Fes servir l’operació d’enviament del tipus de document que necessitis, amb el seu scope d’enviament i la capçalera d’idempotència declarada. Enviar, marcar com a enviat, descarregar un PDF i presentar a FACe són operacions diferents. Una petició acceptada per l’API no demostra que el destinatari hagi rebut el correu; consulta el registre de lliurament de correus.

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"
}'

Totes les rutes d’aquesta guia pengen de /v1/companies/{company}/…: {company} és l’id (UUID v7) del NIF amb què operes, i als exemples curl és $COMPANY_ID. Arribar a un NIF explica com resoldre’l.

Quan compta una factura com a enviada

A les factures, enviar no és emetre. POST /v1/companies/{company}/invoices/{invoice}/send emet abans l’esborrany si cal i després l’envia per correu; la factura només queda marcada com a enviada quan el servidor de correu accepta l’email de lliurament. Un correu en cua o fallit, un recordatori de pagament i el correu d’un esborrany que mai no es va emetre no posen la marca. La marca conserva el primer lliurament: un reenviament no la mou.

Camp (versió de l’API `2026-10-01`)	Valor
`is_sent`	`true` tan bon punt es registra un lliurament.
`sent_at`	Instant del primer lliurament.
`sent_via`	`email` per a un email de lliurament acceptat, `manual` per a una marca que poses tu.

Si lliures una factura emesa per un canal propi (WhatsApp, paper, un portal), registra-ho amb POST /v1/companies/{company}/invoices/{invoice}/mark-sent i Factuarea-Version: 2026-10-01; a les versions anteriors aquesta operació emet un esborrany. Esborra una marca errònia amb POST /v1/companies/{company}/invoices/{invoice}/unsend, que mai no canvia l’estat ni el número. Subscriu-te a invoice.marked_sent i invoice.unsent per seguir la marca i filtra els lliuraments pendents amb is_sent=false. Consulta Treballar amb factures.

Identitat del remitent

Quan s’aplica la comprovació d’identitat del remitent, una subscripció activa de Factuarea o una identificació censal acceptada n’acrediten la identitat. Introduir les dades d’una targeta no és la condició que consulta el servei. Una resposta censal absent o no disponible no acredita identitat; la subscripció activa continua sent una alternativa.

El rebuig fa servir 422 sender_identity_not_verified. Completa la verificació censal o activa la subscripció i després reintenta l’enviament previst. Aquesta guia descriu el comportament quan la comprovació està activa; l’aplicació depèn de la configuració del servei.

Identitat heretada d’una altra empresa

La identitat que es comprova no sempre és la del NIF que envia. Un NIF pren la seva identitat de remitent, i el règim d’un compte nou, de l’empresa de la qual hereta la seva confiança, amb els senyals i les regles d’aquesta empresa. Són tres regles i un sol salt, les mateixes que recull identitat per a l’enviament de documents a la cartera de NIF:

Un NIF d’un compte que no és gestionat, diferent de la seva empresa titular, perquè el compte el va comprar, el va rebre per traspàs o el va donar d’alta, hereta de l’empresa titular del seu propi compte. L’empresa titular no hereta de ningú, i una empresa sense compte tampoc.
Un NIF d’un compte gestionat hereta de l’empresa titular del compte del proveïdor mentre duri la gestió. Quan la gestió acaba, torna a la regla anterior, amb la seva pròpia empresa titular, i mai no continua heretant del proveïdor.
Un NIF al qual arribes per un accés cedit no hereta res del compte receptor. La seva confiança continua sent la de l’empresa titular del seu propi compte.

Heretar no és quedar exempt: si l’empresa de la qual hereta un NIF és en el règim d’un compte nou, el NIF rep el mateix règim. El salt és d’un sol nivell, i una identitat que no es pot llegir no acredita mai res.

Un 422 sender_identity_not_verified es refereix a aquesta empresa. A error.details.resolved_against, own_company vol dir que la identitat es va comprovar contra el mateix NIF, i managing_company que es va comprovar contra l’empresa de la qual hereta el NIF. En el segon cas ha d’actuar l’altra empresa: la seva subscripció activa o la seva identificació censal acceptada és el que acredita la identitat, així que el seu titular registra un mètode de pagament o verifica el seu NIF al cens. No demanis al NIF, ni al client d’un compte gestionat, que contracti una subscripció pròpia: un NIF d’un compte no en té cap per contractar, i el compte el paga.

Mode de prova

Una empresa de sandbox, sobre la qual opera una clau fact_test_, no l’avalua la comprovació d’identitat, així que mai no rep sender_identity_not_verified. Continua subjecta a la supressió del mode de prova: els correus de documents no es lliuren a destinataris reals.

Gestiona els errors d’enviament

La identitat acreditada no elimina les quotes de correu ni la resta de pressupostos del compte. Un 429 requereix l’actuació i el temps de reintent indicats a la resposta de límits; els reintents immediats no ho resolen. Un error de validació requereix corregir-ne el camp. Conserva request_id quan investiguis una petició acceptada amb un lliurament inesperat. L’autosend_enabled de la botiga fa servir les mateixes garanties d’enviament.

El PDF en enviar

Enviar només posa a la cua el correu. El PDF es prepara i es renderitza després que la teva petició es confirmi, a partir de l’original capturat amb el document, i la resposta és el document actualitzat. El seu pdf_output_state pot continuar pendent, així que no hi esperis: confirma el lliurament al registre de lliurament de correus i, si necessites el fitxer, segueix el bucle de reintent de vistes prèvies i artefactes PDF.

Quan la sortida revisionada està activa per a la teva empresa (render_activation és revisioned a GET /v1/companies/{company}/pdf-templates/defaults), les operacions que emeten, envien o accepten un document necessiten la precondició de presentació: el context revisat que vas aprovar. Té exactament set camps, tots o cap:

Camp	Surt de
`expected_selection_version`	`selection_version` de la vista prèvia
`expected_source_token`	`source_token`
`expected_preview_context_fingerprint`	`expected_preview_context_fingerprint`
`expected_template_revision_id`	`template_revision_id` (ha d’estar present, pot ser `null`)
`expected_commercial_identity_revision_id`	`commercial_identity_revision_id` (present, pot ser `null`)
`purpose`, `format`	Els que vas previsualitzar

Obtén els valors previsualitzant l’esborrany amb source.kind: persisted_draft a vistes prèvies i artefactes PDF. On van:

Operació	On
`POST /v1/companies/{company}/invoices/{invoice}/send` i emetre una factura	Els set camps al nivell superior del cos
Enviar i acceptar pressupostos i factures proforma, enviar albarans	Objecte `presentation_precondition`
Enviament massiu i canvi d’estat massiu	`presentation_preconditions`, un mapa indexat per UUID de document

Sense ella l’operació respon 428 pdf_presentation_precondition_required. Un context que ha canviat des de la teva vista prèvia respon 409 (pdf_presentation_conflict o pdf_presentation_context_changed); una factura les dades legals de la qual han canviat respon 409 pdf_legal_source_changed i el seu lliurament queda bloquejat fins que la revisis; i un camp mal format respon 422 pdf_presentation_invalid. Mentre la sortida revisionada no estigui activa per a la teva empresa, la precondició s'ignora i l'operació es comporta com abans. Torna a previsualitzar, revisa i envia amb els valors nous.

Adjuntar l’XML FacturaE

POST /v1/companies/{company}/invoices/{invoice}/send pot adjuntar l’XML FacturaE de la factura. Necessita el mòdul FacturaE.

Camp	Significat
`attach_facturae`	`true` adjunta l’XML. Sense `submission_id` es genera a partir de la factura en aquell moment.
`submission_id`	UUID d’un enviament a FACe d’aquesta factura. Només s’accepta amb `attach_facturae: true`, i adjunta exactament l’XML retingut per a aquell intent, sense generar-ne un de nou.

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ó a l’enllaç públic

PATCH /v1/companies/{company}/invoices/{invoice}/public-link (i la mateixa operació de pressupostos, factures proforma i albarans) accepta action revoke, activate, extend (amb extend_days), reset i publish. publish vincula el PDF capturat exacte a l’enllaç públic i exigeix publication_context; les altres accions el rebutgen:

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

presentation_id és l’id i expected_binding_version el binding_version del bloc presentation del document. Si la versió està desfasada, la petició respon 409 i conserva la publicació anterior: torna a llegir el document. El PATCH no retorna cap URL utilitzable; llegeix l’enllaç amb GET /v1/companies/{company}/invoices/{invoice}/public-link i fes servir publication.public_url només quan publication.state és ready. És null mentre l’enllaç està revocat o caducat, o després d’un esborrat per privacitat. Consulta les operacions de factures, pressupostos i albarans.

Enviament de documents

En aquesta pàgina