Versionat

Política de versionat pla /v1 amb la capçalera Factuarea-Version. Compromisos d'estabilitat i deprecació.

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); avui n'hi ha una de sola, 2026-06-01, que és també l'última. La versió que aplica a una petició — la versió efectiva — es resol en aquest ordre:

La capçalera de petició Factuarea-Version, si l'envies.
Si no, la versió fixada a la teva API key (s'estableix en crear la key; null vol dir "sempre l'última").
Si no, l'última versió del registre.

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 l'última versió.

El registre té avui dues dates: 2026-06-01 (la predeterminada, i la que obtens sense capçalera ni fixació) i 2026-09-01. Optar per la més recent canvia dues coses, i cap més:

Canvi a `2026-09-01`	Què obtens a `2026-06-01`
Les respostes d'esborrat massiu fan servir la forma transversal d'èxit parcial `{total, successful, failed, failures[{id, error_code, error_message}]}`.	La forma anterior `{object: "bulk_delete_result", deleted, failed[{id, reason}]}`.
Els cinc errors preexistents dels gates de cobrament (`payment_method_required`, `seat_charge_failed`, `gestoria_plan_required`, `employee_seat_payment_method_required`, `employee_seat_charge_failed`) porten `error.type: "payment_required_error"`.	`error.type: "invalid_request_error"` en aquests cinc, exactament com abans.

La reclassificació de l'error no toca error.code, error.subcode ni l'estat HTTP — són 402 amb el mateix codi a totes les versions. Si ramifiques per code (que és el que recomanem), no canvia res per a tu en cap cas. addon_required és un codi posterior i porta sempre payment_required_error.

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 cinc errors de cobrament a 2026-09-01. Fer-ho sense versió per data és el cas incompatible que apareix a dalt.

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

Una integració construïda avui contra /v1 seguirà funcionant a /v1 durant almenys 24 mesos des d'avui, sense tocar el teu codi. Finestra de suport per a v1 → mínim 12 mesos després del llançament de v2.

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

En aquesta pàgina