Versiebeleid
Hoe de NovaFisko-API evolueert, wat een compatibele of een brekende wijziging is, en de uitfaseringstermijn van zes maanden.
Een integratie moet jarenlang zonder toezicht kunnen draaien. Deze pagina beschrijft de verbintenissen van NovaFisko over de evolutie van zijn API, en wat wij in ruil van uw code verwachten.
De versie staat in het pad
De hoofdversie staat in de URL: https://api.novafisko.com/v1/.... Het veld api_version van de webhooks draagt dezelfde waarde.
Zolang u /v1/ aanroept, krijgt u met geen enkele brekende wijziging te maken. Een incompatibele evolutie leidt tot een nieuwe hoofdversie, /v2/, die naast de vorige wordt gepubliceerd.
Er bestaat geen subversie die u via een header kiest. Compatibele toevoegingen worden doorlopend uitgerold in v1 en genoteerd in de changelog.
Compatibele wijzigingen
Deze wijzigingen kunnen op elk moment plaatsvinden, zonder vooraankondiging. Uw integratie moet ze verdragen.
| Wijziging | Wat uw code moet doen |
|---|---|
| Nieuwe route | Niets |
| Nieuw veld in een antwoord of in een webhook | Onbekende velden negeren |
| Nieuwe optionele parameter in een request | Niets |
| Nieuwe webhookgebeurtenis | 200 antwoorden en onbekende gebeurtenissen negeren |
Nieuwe waarde in een open enumeratie (status, code, type) |
Een standaardgeval voorzien |
Nieuwe fout-code |
Eerst op de HTTP-status steunen |
| Nieuwe response-header | Niets |
| Verhoging van een snelheids- of groottelimiet | Niets |
Wijziging van de tekst van een message |
De berichten nooit analyseren |
| Wijziging van de volgorde van de sleutels van een JSON-object | Niet van die volgorde afhangen |
Een strikte deserializer, die faalt op een onbekend veld, breekt bij de eerste toevoeging. Stel uw client zo in dat hij negeert wat hij niet kent. Dat is de meest voorkomende oorzaak van een integratiestoring.
Brekende wijzigingen
Deze wijzigingen worden nooit in een bestaande versie doorgevoerd.
- Een route, een veld of een parameter verwijderen of hernoemen.
- Het type van een veld wijzigen, bijvoorbeeld van een string naar een getal.
- Een parameter die optioneel was verplicht maken.
- De betekenis van een bestaand veld of een bestaande status wijzigen.
- Een enumeratiewaarde of een webhookgebeurtenis verwijderen.
- Het formaat van de identificatoren, de datums of de bedragen wijzigen.
- Het ondertekeningsschema van de webhooks wijzigen.
- De HTTP-status van een gedocumenteerd succes- of foutgeval wijzigen.
- Een gedocumenteerde snelheidslimiet verlagen.
Uitzonderingen
Drie situaties kunnen een wijziging rechtvaardigen zonder dat de aankondigingstermijn wordt nageleefd:
- Veiligheid. Een lek wordt onmiddellijk gedicht, ook als de correctie een gedrag wijzigt.
- Wettelijke verplichting. Een evolutie die door de administratie wordt opgelegd (btw, Intervat, Peppol, jaarrekening) gaat in op de reglementaire datum.
- Correctie van een anomalie. Een gedrag dat in strijd is met de documentatie wordt gecorrigeerd. Als integraties er zichtbaar op steunen, verwittigen wij vooraf.
In elk geval wordt de wijziging aangekondigd in de changelog.
Uitfasering
Wanneer een route of een veld moet verdwijnen, volgt NovaFisko deze kalender.
| Stap | Moment | Wat er gebeurt |
|---|---|---|
| Aankondiging | D | Vermelding in de changelog, in de referentie en in de OpenAPI-specificatie (deprecated: true) |
| Signalering | Vanaf D | De betrokken antwoorden dragen de headers Deprecation en Sunset |
| Herinnering | D + 3 maanden | Bericht aan de beheerders van de kantoren waarvan de tokens het element nog gebruiken |
| Verwijdering | Ten vroegste D + 6 maanden | Het element wordt verwijderd. Een verwijderde route antwoordt 410 Gone |
De minimale termijn tussen de aankondiging en de verwijdering bedraagt zes maanden.
Uitfaseringsheaders
HTTP/1.1 200 OK
Deprecation: @1798761600
Sunset: Wed, 30 Jun 2027 23:59:59 GMT
Link: <https://docs.novafisko.com/nl/api/changelog>; rel="deprecation"
| Header | Betekenis |
|---|---|
Deprecation |
Datum vanaf wanneer het element is uitgefaseerd, als Unix-tijdstempel voorafgegaan door @ |
Sunset |
Datum vanaf wanneer het element kan ophouden te werken |
Link met rel="deprecation" |
Pagina die de vervanging beschrijft |
Tot op heden is geen enkel element van v1 uitgefaseerd en deze headers worden dus door geen enkele route verstuurd. Ze beschrijven hoe een toekomstige uitfasering u zal worden gemeld.
Log elk antwoord dat een header Deprecation bevat en laat een waarschuwing afgaan. Zo wordt u door uw eigen monitoring verwittigd, maanden vóór de verwijdering.
Nieuwe hoofdversie
Als er een v2 komt:
- werken
v1env2minstens twaalf maanden naast elkaar; - beschrijft een migratiegids elk verschil;
- blijven de tokens geldig op beide versies;
- behouden de webhooks het formaat
v1zolang u niet voor de overstap naarv2hebt gekozen.
Wat niet gedekt is
Deze elementen kunnen zonder vooraankondiging wijzigen. Bouw er niets op.
- De routes die ontbreken in de referentie en in de OpenAPI-specificatie.
- De routes
bridge/*, voorbehouden aan de koppeling met Novadesko. - De exacte inhoud van de pdf-bestanden (opmaak, omschrijvingen).
- De tekst van de foutberichten en van de vertaalde omschrijvingen.
- Het interne formaat van de ondertekende URL's. Behandel ze als ondoorzichtige strings met een korte levensduur.
- De gegevens van het demokantoor, die elke nacht worden gereset.
De historische CSV-exports (dagboeken, grootboek, proef- en saldibalans, klantenlisting, audittrail) hebben daarentegen een stabiele kolomstructuur, die onder de verbintenissen van deze pagina valt.
Een duurzame integratie schrijven
- Negeer de velden, gebeurtenissen en enumeratiewaarden die u niet kent.
- Beslis op basis van de HTTP-status, daarna op basis van
code, nooit op basis vanmessage. - Stuur een
User-Agentmee die uw integratie en haar versie identificeert, bijvoorbeeldERP-Atelier/2.4 (support@atelier.example). Zo kunnen wij u indien nodig contacteren. - Raadpleeg de changelog bij elke nieuwe versie van uw product.
- Genereer uw client af en toe opnieuw uit de OpenAPI-specificatie om van de toevoegingen te profiteren.