Versionat

L'API de Factuarea segueix una política d'URL amb versionat pla (/v1) combinada amb una capçalera de data opcional per a una evolució sense canvis incompatibles. El compromís és clar: un cop publicada, /v1 es manté estable. Els canvis incompatibles requereixen /v2.

Versió a l'URL

https://api.factuarea.com/v1/...

v1 és la nostra primera versió pública (maig de 2026). No hi ha versions anteriors accessibles.

Quan es dissenyi /v2:

• /v1 i /v2 coexisteixen durant almenys 12 mesos.
• Les rutes de /v1 no canvien en aquesta finestra (ni payloads, ni status codes, ni camps, ni semàntica).
• Avisos per email als desenvolupadors amb keys actives, banner a la documentació, capçaleres a les respostes (vegeu més avall).

Capçalera Factuarea-Version

Factuarea-Version: 2026-06-01

El date-versioning funciona a l'estil de Stripe. Hi ha un registre de versions suportades (dates YYYY-MM-DD): 2026-06-01, 2026-09-01 i 2026-10-01. La predeterminada és 2026-06-01, que no és l'última. La versió que aplica a una petició — la versió efectiva — es resol en aquest ordre:

1. La capçalera de petició Factuarea-Version, si l'envies.
2. Si no, la versió fixada a la teva API key (s'estableix en crear la key; null vol dir que no hi ha cap versió fixada).
3. Si no, la versió predeterminada, 2026-06-01.

La versió efectiva es retorna a cada resposta a la capçalera Factuarea-Version, així sempre saps quina versió per data ha servit la teva petició.

Factuarea-Version: 2026-06-01

Fixar una versió (per capçalera o a la key) congela el comportament del subconjunt d'endpoints que reben millores incrementals sense canvis incompatibles (nous camps a la resposta, nous paràmetres opcionals). Sense capçalera ni fixació, obtens la versió predeterminada, 2026-06-01. Cada data més recent és opcional i inclou els canvis de les dates anteriors.

Optar per 2026-09-01 canvia dues coses, i cap més:

Vocabulari de factures a 2026-10-01

2026-10-01 separa l'emissió d'una factura del seu lliurament al client. Canvia el contracte de factures, i res més:

La versió s'aplica a tot objecte factura de qualsevol resposta, incloses les conversions, les execucions de factures recurrents, GET /v1/companies/{company}/events i els lliuraments de webhook llistats. Algunes parts estan disponibles a totes les versions perquè són additives o àlies d'entrada: POST /v1/companies/{company}/invoices/{invoice}/issue, el filtre is_sent, generation_mode a les factures recurrents, i status=sent, new_status: "sent" i scheduled_action: "draft" com a àlies d'issued i issue. Consulta la publicació de Novetats.

Versions de payload dels webhooks

Els lliuraments de webhook segueixen l'api_version de cada endpoint, no la capçalera de la petició. Les versions de payload admeses són 2026-05-22, 2026-10-01 i 2026-10-05. Els endpoints que existien abans d'aquesta versió van quedar fixats a 2026-05-22 i reben els snapshots de factura amb el vocabulari anterior. Un endpoint creat sense api_version queda fixat en crear-se: sense capçalera ni versió fixada a la clau, o des de l'aplicació, es queda a 2026-05-22; si la petició fa servir la versió REST 2026-10-01, pren la versió de payload més recent (2026-10-05). Per rebre el vocabulari nou, crea'l amb Factuarea-Version: 2026-10-01 o amb "api_version": "2026-10-01". Consulta Webhooks.

Errors

La capçalera es valida contra el registre:

• Valor mal format (que no sigui YYYY-MM-DD, p. ex. 2026-05 o 15/05/2026) → 400 parameter_invalid_format amb param: "Factuarea-Version".
• Ben format però no suportat (una data vàlida que no és al registre) → 400 unsupported_api_version amb param: "Factuarea-Version".

Ometre la capçalera mai és un error — cau a la fixació de la key o a l'última versió.

Què és un canvi incompatible?

Considerem incompatible (prohibit a /v1):

• Reanomenar / eliminar camps de la resposta JSON.
• Canviar el tipus d'un camp (string → int).
• Canviar el type/code d'un embolcall d'error existent.
• Canviar status codes (p. ex. retornar 201 on abans era 200).
• Convertir en obligatori un camp de la petició que abans era opcional.
• Canviar el format d'un identificador (UUID v7 segueix sent UUID v7).
• Eliminar un endpoint sense un reemplaçament documentat i una finestra de migració.
• Canviar la semàntica de la màquina d'estats dels documents.

Considerem no incompatible (permès sense una nova versió):

• Afegir camps nous a les respostes.
• Afegir paràmetres opcionals a les peticions.
• Afegir endpoints nous.
• Relaxar restriccions (apujar un límit, acceptar més formats).
• Afegir valors d'enum nous a camps que no siguin crítics per a les màquines d'estats del costat del client.
• Millorar els missatges d'error (canvia message, no type/code).
• Reclassificar el type d'un envelope d'error existent darrere d'una versió per data: les keys fixades a una data anterior continuen rebent el type previ tal qual, i code/subcode/estat no es mouen. Així es van recategoritzar els errors de cobrament a 2026-09-01. Fer-ho sense versió per data és el cas incompatible que apareix a dalt.
• Canviar el nom d'un valor o el significat d'un camp darrere d'una versió per data, com fa 2026-10-01 amb l'estat de les factures: les dates anteriors conserven el contracte previ i els àlies d'entrada mantenen en funcionament les peticions existents.

Política de deprecació

Quan un endpoint o camp es marca com a deprecat dins de /v1 (p. ex. un àlies heretat reemplaçat per una versió canònica):

• Avís per email als desenvolupadors amb keys actives afectades.
• Banner a docs.factuarea.com amb el changelog.
• Capçaleres a cada resposta de l'endpoint deprecat durant almenys 12 mesos abans de la seva retirada (que només passa a /v2):

Deprecation: true
Sunset: Wed, 15 May 2027 00:00:00 GMT
Link: <https://docs.factuarea.com/changelog#v1-deprecations>; rel="deprecation"
Link: <https://docs.factuarea.com/guides/migration-from-holded>; rel="alternate"

• A /v1 l'endpoint segueix funcionant fins al llançament de /v2. Les capçaleres avisen.
• A /v2 l'endpoint es retira / reemplaça. La finestra entre el primer avís i /v2 és ≥ 12 mesos.

Migració entre versions

Cada migració (v1 → v2) ve acompanyada de:

• Una guia dedicada a docs.factuarea.com/guides/migration-v1-v2.
• Mapatge camp a camp i endpoint a endpoint.
• Recomanacions operatives (mantenir totes dues keys, escriptura dual durant la transició).
• Webhooks: els esdeveniments antics conserven la seva forma; els esdeveniments nous viuen en la seva pròpia versió declarada al payload.

Changelog

Cada canvi de /v1 (camp nou, deprecació, esdeveniment nou, correcció de validació) es publica a Changelog amb etiquetes:

• feature — camp / endpoint / esdeveniment nou.
• fix — correcció d'un bug.
• deprecation — camp o endpoint marcat com a obsolet (encara actiu a /v1).
• breaking — només apareix a /v2, mai dins de /v1.
• security — correcció amb implicacions de seguretat. Llegeix-la primer.

Subscriu-te al feed RSS a https://docs.factuarea.com/changelog.rss o segueix @factuarea a X per als anuncis.

Compromís d'estabilitat

Aquesta és la garantia. Qualsevol excepció es comunicarà amb terminis generosos.