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-05-15

Opcional. Si l'envies, fixes el comportament del subconjunt d'endpoints que reben millores incrementals sense canvis incompatibles (nous camps a la resposta, nous paràmetres opcionals). Sense la capçalera → obtens l'última versió per data.

Errors

• Valor mal format (que no sigui YYYY-MM-DD, p. ex. 2026-05 o 15/05/2026) → 422 invalid_param_format amb param: "Factuarea-Version".

A v1 la capçalera només valida el seu format i es registra per a auditoria; encara no canvia cap resposta. Una data ben formada però futura o passada s'accepta sense error.

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).

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.