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-03-01 — la seule version publiée à ce jour. Elle s'applique à toutes les requêtes tant que vous n'épinglez pas explicitement une autre version via le header Facturino-Version.

Comment ça fonctionne

Une seule version est active aujourd'hui : 2026-03-01. Toutes les requêtes sont traitées avec cette version, et chaque réponse renvoie le header Facturino-Version annonçant la version contractuelle utilisée.

Vous pouvez déjà envoyer le header Facturino-Version: YYYY-MM-DD sur vos requêtes : c'est le mécanisme d'épinglage qui prendra effet dès la publication d'une seconde version. Tant qu'une seule version existe, le header est simplement renvoyé tel quel.

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-03-01"

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

HTTP/1.1 200 OK
Facturino-Version: 2026-03-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-03-01 1er mars 2026 Courante Première version publique stable. Réforme française e-invoicing 2026 (Factur-X EN16931 + CIUS-FR).

Lancement public. Facturino est en phase de pré-production jusqu'au 1er septembre 2026 (entrée en vigueur de l'obligation DGFiP). Les futures versions seront publiées avec un préavis minimum de 90 jours pour les changements breaking.

Migrer vers une nouvelle version

Dès qu'une nouvelle version sera publiée, le processus recommandé sera :

  1. Lire le changelog de la version cible — chaque breaking change 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.

Politique de dépréciation

  • Une version reste supportée au moins 12 mois après sa date de sortie.
  • Une version dépréciée continue de fonctionner, mais retourne le header Facturino-Deprecation: sunset=YYYY-MM-DD avec la date de fin de support.
  • Le support proactif (alertes par email aux admins) commence 6 mois avant la fin de support.
  • Après la sunset date, l'API retourne 410 Gone avec instruction de migrer.

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-03-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