Politique de version
Comment l'API NovaFisko évolue, ce qui constitue un changement compatible ou cassant, et le préavis de dépréciation de six mois.
Une intégration doit pouvoir tourner des années sans surveillance. Cette page décrit les engagements de NovaFisko sur l'évolution de son API, et ce que nous attendons de votre code en retour.
La version est dans le chemin
La version majeure figure dans l'URL : https://api.novafisko.com/v1/.... Le champ api_version des webhooks porte la même valeur.
Tant que vous appelez /v1/, vous ne subirez aucun changement cassant. Une évolution incompatible donnera lieu à une nouvelle version majeure, /v2/, publiée à côté de la précédente.
Il n'existe pas de version mineure à sélectionner par en-tête. Les ajouts compatibles sont déployés en continu dans v1 et consignés dans le journal des modifications.
Changements compatibles
Ces changements peuvent survenir à tout moment, sans préavis. Votre intégration doit les tolérer.
| Changement | Ce que votre code doit faire |
|---|---|
| Nouvelle route | Rien |
| Nouveau champ dans une réponse ou dans un webhook | Ignorer les champs inconnus |
| Nouveau paramètre facultatif dans une requête | Rien |
| Nouvel événement de webhook | Répondre 200 et ignorer les événements inconnus |
Nouvelle valeur dans une énumération ouverte (status, code, type) |
Prévoir un cas par défaut |
Nouveau code d'erreur |
S'appuyer d'abord sur le statut HTTP |
| Nouvel en-tête de réponse | Rien |
| Relèvement d'une limite de débit ou de taille | Rien |
Modification du texte d'un message |
Ne jamais analyser les messages |
| Changement de l'ordre des clés d'un objet JSON | Ne pas dépendre de cet ordre |
Un désérialiseur strict, qui échoue sur un champ inconnu, casse au premier ajout. Configurez votre client pour ignorer ce qu'il ne connaît pas. C'est la cause la plus fréquente de panne d'intégration.
Changements cassants
Ces changements ne sont jamais faits dans une version existante.
- Supprimer ou renommer une route, un champ ou un paramètre.
- Changer le type d'un champ, par exemple d'une chaîne vers un nombre.
- Rendre obligatoire un paramètre qui était facultatif.
- Changer la signification d'un champ ou d'un statut existant.
- Supprimer une valeur d'énumération ou un événement de webhook.
- Changer le format des identifiants, des dates ou des montants.
- Changer le schéma de signature des webhooks.
- Changer le statut HTTP d'un cas de succès ou d'erreur documenté.
- Abaisser une limite de débit documentée.
Exceptions
Trois situations peuvent justifier une modification sans respecter le préavis :
- Sécurité. Une faille est corrigée immédiatement, même si le correctif modifie un comportement.
- Obligation légale. Une évolution imposée par l'administration (TVA, Intervat, Peppol, comptes annuels) s'applique à la date réglementaire.
- Correction d'anomalie. Un comportement contraire à la documentation est corrigé. Si des intégrations s'appuient visiblement dessus, nous prévenons avant.
Dans chaque cas, le changement est annoncé dans le journal des modifications.
Dépréciation
Quand une route ou un champ doit disparaître, NovaFisko suit ce calendrier.
| Étape | Moment | Ce qui se passe |
|---|---|---|
| Annonce | J | Entrée dans le journal des modifications, mention dans la référence et dans la spécification OpenAPI (deprecated: true) |
| Signalement | À partir de J | Les réponses concernées portent les en-têtes Deprecation et Sunset |
| Rappel | J + 3 mois | Message aux administrateurs des cabinets dont les jetons utilisent encore l'élément |
| Retrait | J + 6 mois au plus tôt | L'élément est retiré. Une route retirée répond 410 Gone |
Le préavis minimal est de six mois entre l'annonce et le retrait.
En-têtes de dépréciation
HTTP/1.1 200 OK
Deprecation: @1798761600
Sunset: Wed, 30 Jun 2027 23:59:59 GMT
Link: <https://docs.novafisko.com/fr/api/changelog>; rel="deprecation"
| En-tête | Signification |
|---|---|
Deprecation |
Date à partir de laquelle l'élément est déprécié, sous forme d'horodatage Unix précédé de @ |
Sunset |
Date à partir de laquelle l'élément peut cesser de fonctionner |
Link avec rel="deprecation" |
Page qui décrit le remplacement |
À ce jour, aucun élément de v1 n'est déprécié et ces en-têtes ne sont donc émis par aucune route. Ils décrivent la manière dont une dépréciation future vous sera signalée.
Journalisez toute réponse qui contient un en-tête Deprecation et déclenchez une alerte. Vous serez prévenu par votre propre supervision, des mois avant le retrait.
Nouvelle version majeure
Si une v2 voit le jour :
v1etv2fonctionneront en parallèle pendant douze mois au minimum ;- un guide de migration détaillera chaque différence ;
- les jetons resteront valables sur les deux versions ;
- les webhooks conserveront le format
v1tant que vous n'aurez pas choisi de passer àv2.
Ce qui n'est pas couvert
Ces éléments peuvent changer sans préavis. Ne construisez rien dessus.
- Les routes absentes de la référence et de la spécification OpenAPI.
- Les routes
bridge/*, réservées à la liaison avec Novadesko. - Le contenu exact des fichiers PDF (mise en page, libellés).
- Le texte des messages d'erreur et des libellés traduits.
- Le format interne des URL signées. Traitez-les comme des chaînes opaques à durée de vie courte.
- Les données du cabinet de démonstration, réinitialisées chaque nuit.
Les exports CSV historiques (journaux, grand livre, balance, listing clients, piste d'audit) ont en revanche une structure de colonnes stable, qui relève des engagements de cette page.
Écrire une intégration durable
- Ignorez les champs, les événements et les valeurs d'énumération que vous ne connaissez pas.
- Décidez selon le statut HTTP, puis selon
code, jamais selonmessage. - Envoyez un
User-Agentqui identifie votre intégration et sa version, par exempleERP-Atelier/2.4 (support@atelier.example). Nous pourrons vous contacter en cas de besoin. - Consultez le journal des modifications à chaque montée de version de votre produit.
- Régénérez votre client à partir de la spécification OpenAPI de temps en temps pour profiter des ajouts.