Facturino / Documentation / Versions de l'API

Versions de l'API

L'API Facturino utilise un schéma de versioning par date (CalVer) inspiré de Stripe. Chaque changement non-rétrocompatible déclenche la publication d'une nouvelle version, identifiée par sa date de sortie. Votre intégration reste figée sur la version contre laquelle elle a été développée, sauf si vous décidez explicitement de migrer.

Version actuelle

La version courante est 2026-09-01 — le premier contrat stable de l'API, et la seule version servie. Elle s'applique à toutes les requêtes tant que vous n'épinglez pas explicitement une version via le header Facturino-Version (ou API-Version).

Comment ça fonctionne

Chaque réponse renvoie le header Facturino-Version annonçant la version contractuelle réellement utilisée. Une version inconnue est refusée par un 400 qui liste les versions servies — jamais un repli silencieux sur une autre.

Exemple — épingler explicitement une version sur une requête :

$ curl https://facturino.com/api/v1/invoices \
  -H "Authorization: Bearer fac_test_..." \
  -H "Facturino-Version: 2026-09-01"

La réponse inclut systématiquement la version utilisée :

HTTP/1.1 200 OK
Facturino-Version: 2026-09-01
X-Request-Id: req_8a3b9f2e1d
Content-Type: application/json

Contrat de stabilité

Au sein d'une même version, vous pouvez compter sur les garanties suivantes :

  • Ajouts de champs optionnels dans les réponses — votre code doit tolérer les champs inconnus.
  • Ajouts d'endpoints, de scopes ou de types d'événements webhook — sans impact sur l'existant.
  • Ajouts de codes d'erreur dans les types existants — votre code doit avoir un fallback générique.
  • Nouveaux paramètres optionnels sur les endpoints existants — ignorés s'ils ne sont pas envoyés.

Sont en revanche considérés comme breaking et imposent une nouvelle version :

  • Suppression ou renommage d'un champ, d'un endpoint ou d'un type d'événement
  • Modification du type, du format ou de la sémantique d'un champ existant
  • Changement du comportement d'un endpoint (nouvelle valeur par défaut, transition d'état différente)
  • Modification des règles de validation (un champ devient requis, une contrainte se durcit)

Versions publiées

VersionDateStatutNotes
2026-09-01 1er septembre 2026 Courante Premier contrat stable. Cycle de décision fiscale complet : deux sources fiscales de même niveau (facturino et integration), factures adossées à une décision finale, acompte intégralement réglé avant déduction, garde fiscale de /send, reprise d'une déclaration e-reporting refusée.

Les deux sources fiscales

  • TVA déterminée par Facturino (taxSource: facturino) — vous décrivez l'opération (nature, catégorie de taux demandée, preuves territoriales) et les moteurs fiscaux Facturino décident le taux, le code de catégorie, le code VATEX, les mentions légales, les montants et les trois axes d'obligation.
  • TVA fournie par l'intégration (taxSource: integration) — votre propre moteur a conclu la TVA : vous la fournissez par ligne (vatRate, vatCode, vatexCode). Facturino valide la cohérence des valeurs, refuse explicitement toute contradiction détectable, et décide lui-même les montants, les mentions légales et les trois axes d'obligation. Il ne corrige jamais un taux en silence.

Les deux parcours sont de même niveau fonctionnel : dans les deux cas, toute facture fiscalisée naît d'une décision immuable (POST /v1/tax-decisions), et une décision finale adosse exactement une facture.

Une date publiée ne change jamais rétroactivement. Quand le contrat REST évoluera, une nouvelle date sera introduite et servie à côté de 2026-09-01 : les versions datées sont immuables et coexistent. Votre intégration reste épinglée sur la version qu'elle a validée.

Adopter une future version

Le processus recommandé, quand une nouvelle date existera :

  1. Lire le changelog de la version cible — chaque changement y est listé avec des exemples avant/après.
  2. Dans votre code, ajouter le header Facturino-Version: YYYY-MM-DD pour cibler la nouvelle version.
  3. Vérifier les endpoints concernés en mode test (fac_test_).
  4. Adapter votre code, puis déployer avec le header explicite pointant la nouvelle version.

Changelog

Le détail des changements par version est publié sur la page dédiée Changelog et notifié par email aux administrateurs ayant souscrit aux notifications développeur.

Versioning des webhooks

Chaque événement webhook est sérialisé avec la version active (2026-09-01), indiquée dans le champ apiVersion du payload (camelCase — convention ressources Stripe-style hybride). Lorsque de nouvelles versions existeront, l'apiVersion d'un événement restera fixe une fois émis, pour que votre récepteur sache toujours quel format il reçoit.

Étapes suivantes