Emesa no vol dir enviada: versió de l’API 2026-10-01

Fins ara l’API anomenava «enviar» l’acte fiscal d’emetre una factura: draft → sent assignava el número de sèrie, congelava les dades de l’emissor i del client, donava d’alta el registre VeriFactu i descomptava stock, però no enviava cap correu. I l’enviament real per email no deixava rastre a la factura. Aquesta publicació separa els dos fets. Emetre és un estat; lliurar la factura al client és una marca pròpia, independent de l’estat i del cobrament.

El vocabulari nou viu darrere la versió per data 2026-10-01. La versió predeterminada continua sent 2026-06-01: una integració que no envia la capçalera Factuarea-Version i no té la clau fixada continua rebent exactament el contracte anterior.

Dos eixos: emesa i enviada

Una factura issued o overdue pot estar enviada o no, i cobrar-la no la marca com a enviada. La marca només es posa de dues maneres:

• Email: quan el servidor de correu accepta un email de lliurament de la factura (POST /v1/invoices/{invoice}/send, bulk-send, execucions recurrents i programades, automatitzacions, l’app i el MCP). Un correu en cua o fallit i un recordatori de pagament mai no la posen. Tampoc no es marca un esborrany enviat per correu abans d’emetre’l.
• Manual: amb POST /v1/invoices/{invoice}/mark-sent a 2026-10-01, per a factures que vas lliurar per un canal propi (WhatsApp, paper, un portal).

Què canvia amb 2026-10-01

Envia Factuarea-Version: 2026-10-01 a cada petició o fixa aquesta versió a l’API key. Tot objecte factura de qualsevol resposta v1 segueix la versió efectiva, també dins de les conversions de pressupostos, factures proforma i albarans, les execucions de factures recurrents, GET /v1/events i els lliuraments de webhook que llista GET /v1/webhook_endpoints/{webhook_endpoint}/deliveries.

Dos canvis del costat de la petició són additius i s’apliquen a totes les versions: el filtre is_sent de GET /v1/invoices i la nova operació issue.

Nou: emetre una factura

POST /v1/invoices/{invoice}/issue emet un draft sense enviar-lo. Necessita l’scope invoices:write i, com que emetre consumeix un número de sèrie i no es pot desfer, accepta un Idempotency-Key. Qualsevol estat diferent de draft respon 422 invalid_status_transition.

curl -X POST "https://api.factuarea.com/v1/invoices/$INVOICE_ID/issue" \
  -H "Authorization: Bearer $FACTUAREA_API_KEY" \
  -H "Factuarea-Version: 2026-10-01" \
  -H "Idempotency-Key: issue-fac-2026-00042"

{
  "data": {
    "number": "FAC-2026-00042",
    "status": "issued",
    "issued_at": "2026-03-15T11:45:00Z",
    "sent_at": null,
    "sent_via": null,
    "is_sent": false
  }
}

L’extracte mostra només els camps d’aquesta publicació. Sense la capçalera, la mateixa crida respon amb status: "sent" i sent_at igual a l’instant d’emissió.

mark-sent depèn de la versió

POST /v1/invoices/{invoice}/mark-sent conserva el seu significat anterior a les versions prèvies: emet un esborrany sense enviar-lo per correu. Des de 2026-10-01 només registra un lliurament manual: is_sent: true, sent_via: "manual" i sent_at, sense tocar l’estat, el número ni el registre VeriFactu.

A 2026-10-01 admet factures issued i overdue i és idempotent: una factura ja enviada conserva la data i el canal originals. Sobre un esborrany respon:

{
  "error": {
    "type": "invalid_request_error",
    "code": "business_rule_violation",
    "subcode": "invoice_cannot_be_marked_as_sent",
    "message": "La factura FAC-2026-BORRADOR es un borrador y todavía no puede marcarse como enviada: emítela antes.",
    "doc_url": "https://docs.factuarea.com/guides/errors#business_rule_violation",
    "request_id": "req_5e99aabe287e78db589da44c56"
  }
}

Ramifica segons error.subcode. Emet abans la factura amb POST /v1/invoices/{invoice}/issue o envia-la per correu amb POST /v1/invoices/{invoice}/send.

Les factures programades s’emeten amb la seva programació

Canvi de comportament a totes les versions. Només es pot emetre un draft. Una factura scheduled ja no s’emet pels camins genèrics: POST /v1/invoices/{invoice}/mark-sent en versions anteriors a 2026-10-01 i POST /v1/invoices/{invoice}/issue responen 422 invalid_status_transition, sigui quina sigui la versió que enviïs. Abans d’aquesta publicació, mark-sent l’emetia com si fos un esborrany.

Per emetre una factura programada abans de la seva data, desprograma-la primer amb POST /v1/invoices/{invoice}/unschedule i després emet-la. Si no, deixa que s’executi la programació: emet la factura a scheduled_for.

send, unsend i bulk-status

• POST /v1/invoices/{invoice}/send emet un esborrany i l’envia per correu, com abans. La resposta encara pot mostrar is_sent: false: la marca apareix quan el servidor de correu accepta el missatge, juntament amb l’esdeveniment invoice.marked_sent.
• POST /v1/invoices/{invoice}/unsend esborra la marca d’enviament (sent_at i sent_via tornen a null) d’una factura issued o overdue i emet invoice.unsent. L’estat, el número, el registre VeriFactu i l’stock no es mouen mai. Una factura amb cobraments vigents respon 422, i una segona crida no té efecte. Canvi observable a les versions anteriors: en aquestes sent_at porta l’instant d’emissió, de manera que ja no passa a null després d’unsend. Llegeix is_sent amb 2026-10-01 per saber si la marca hi és.
• POST /v1/invoices/bulk-status accepta new_status: "issued" per emetre esborranys sense enviar-los per correu. sent encara s’accepta com a àlies i mai no marca una factura com a lliurada.

Àlies d’entrada a totes les versions

Les teves peticions actuals continuen funcionant, facis servir la versió que facis servir:

Un valor fora del catàleg continua rebutjant-se amb 422 i la llista de valors admesos. scheduled_action accepta ara issue (emetre sense enviar) o issue_and_send (emetre i enviar per correu).

Factures recurrents: generation_mode

Les factures recurrents guanyen generation_mode, disponible a totes les versions a POST /v1/recurring_invoices, PUT /v1/recurring_invoices/{recurring_invoice}, POST /v1/invoices/{invoice}/create-recurring i a totes les respostes de factures recurrents:

send_automatically es conserva com a camp de compatibilitat derivat: true només amb issue_and_send. Sense generation_mode, send_automatically: true continua seleccionant issue_and_send i false selecciona draft; enviar tots dos amb valors contradictoris respon 422. Les factures recurrents existents conserven el seu comportament: les que enviaven les factures per correu passen a issue_and_send i la resta a draft. Consulta Factures recurrents.

Esdeveniments i webhooks

Un endpoint subscrit a invoice.sent el continua rebent i es pot continuar editant amb aquesta subscripció. Subscriu les integracions noves a invoice.issued; la retirada de l’àlies s’anunciarà amb una data Sunset. Les regles d’automatització ja no accepten invoice.sent com a activador: crear o actualitzar una regla amb ell respon 422 automation_trigger_type_invalid indicant invoice.issued.

Els payloads de webhook es versionen per endpoint amb el seu api_version. Les versions de payload admeses són 2026-05-22 i 2026-10-01:

• Els endpoints que ja existien abans d’aquesta publicació van quedar fixats a 2026-05-22: els seus snapshots de factura conserven el vocabulari anterior (status: "sent", sent_at igual a l’instant d’emissió, sense issued_at, is_sent ni sent_via).
• Un endpoint creat sense api_version queda fixat en crear-se: rep la versió de payload més recent que no sigui posterior a la versió REST efectiva de la petició que el crea. Sense capçalera Factuarea-Version ni versió fixada a la clau, o des de l’aplicació, aquesta és la versió per defecte, de manera que l’endpoint queda fixat a 2026-05-22. Per rebre el vocabulari nou, crea’l amb Factuarea-Version: 2026-10-01 o amb "api_version": "2026-10-01".
• L’api_version del sobre lliurat és la versió d’aquell lliurament. L’esdeveniment desat no es reescriu mai: la projecció es fa en lliurar.

Canvia la versió d’un endpoint amb PUT /v1/webhook_endpoints/{webhook_endpoint} quan el teu receptor entengui el vocabulari nou. Consulta Webhooks.

MCP

El servidor MCP no té versions i sempre parla el contracte més recent:

• Nova tool issue_invoice (invoices:write), el mirall de POST /v1/invoices/{invoice}/issue.
• mark_invoice_as_sent registra ara un lliurament manual. Sobre un esborrany retorna invoice_cannot_be_marked_as_sent i remet a issue_invoice o send_invoice.
• search_invoices accepta issued (i sent com a àlies) i el filtre is_sent; bulk_change_invoice_status i schedule_invoice accepten els valors nous.
• create_recurring_invoice, update_recurring_invoice i create_recurring_invoice_from_invoice accepten generation_mode.
• Tota tool que retorna una factura fa servir el vocabulari nou.

Si un agent feia servir mark_invoice_as_sent per emetre factures, canvia’l a issue_invoice.

Com adoptar-la

1. Accepta issued allà on llegeixis l’status d’una factura, i llegeix l’enviament d’is_sent, sent_at i sent_via.
2. Substitueix l’emissió mitjançant mark-sent per POST /v1/invoices/{invoice}/issue, que funciona a totes les versions.
3. Envia Factuarea-Version: 2026-10-01, o fixa-la a la clau, i executa les teves proves contra el sandbox.
4. Subscriu els teus endpoints de webhook a invoice.issued i, quan et convingui, a invoice.marked_sent i invoice.unsent; després passa cada endpoint a la versió de payload 2026-10-01.