Skip to content
Documentation
Guide API Demo
English
Open the app

Versioning policy

How the NovaFisko API evolves, what counts as a compatible or a breaking change, and the six-month deprecation notice.

Updated on 10/05/2026 Edit this page

An integration must be able to run for years unattended. This page describes NovaFisko's commitments on the evolution of its API, and what we expect from your code in return.

The version is in the path

The major version is in the URL: https://api.novafisko.com/v1/.... The api_version field of webhooks carries the same value.

As long as you call /v1/, you will not be subject to any breaking change. An incompatible evolution will result in a new major version, /v2/, published alongside the previous one.

There is no minor version to select through a header. Compatible additions are deployed continuously in v1 and recorded in the changelog.

Compatible changes

These changes can occur at any time, without notice. Your integration must tolerate them.

Change What your code must do
New route Nothing
New field in a response or in a webhook Ignore unknown fields
New optional parameter in a request Nothing
New webhook event Respond 200 and ignore unknown events
New value in an open enumeration (status, code, type) Provide a default case
New error code Rely on the HTTP status first
New response header Nothing
Raising of a rate or size limit Nothing
Change to the text of a message Never parse messages
Change in the key order of a JSON object Do not depend on that order
Warning

A strict deserialiser, which fails on an unknown field, breaks at the first addition. Configure your client to ignore what it does not know. This is the most common cause of integration outages.

Breaking changes

These changes are never made in an existing version.

  • Removing or renaming a route, a field or a parameter.
  • Changing the type of a field, for example from a string to a number.
  • Making a parameter required when it was optional.
  • Changing the meaning of an existing field or status.
  • Removing an enumeration value or a webhook event.
  • Changing the format of identifiers, dates or amounts.
  • Changing the webhook signature scheme.
  • Changing the HTTP status of a documented success or error case.
  • Lowering a documented rate limit.

Exceptions

Three situations can justify a change that does not respect the notice period:

  1. Security. A vulnerability is fixed immediately, even if the fix changes a behaviour.
  2. Legal obligation. A change imposed by the authorities (VAT, Intervat, Peppol, annual accounts) applies on the regulatory date.
  3. Bug fix. A behaviour that contradicts the documentation is corrected. If integrations visibly rely on it, we give warning beforehand.

In each case, the change is announced in the changelog.

Deprecation

When a route or a field has to disappear, NovaFisko follows this schedule.

Stage When What happens
Announcement D Entry in the changelog, mention in the reference and in the OpenAPI specification (deprecated: true)
Signalling From D The responses concerned carry the Deprecation and Sunset headers
Reminder D + 3 months Message to the administrators of the firms whose tokens still use the item
Removal D + 6 months at the earliest The item is removed. A removed route responds 410 Gone

The minimum notice is six months between the announcement and the removal.

Deprecation headers

HTTP/1.1 200 OK
Deprecation: @1798761600
Sunset: Wed, 30 Jun 2027 23:59:59 GMT
Link: <https://docs.novafisko.com/en/api/changelog>; rel="deprecation"
Header Meaning
Deprecation Date from which the item is deprecated, as a Unix timestamp preceded by @
Sunset Date from which the item may stop working
Link with rel="deprecation" Page that describes the replacement
Note

To date, no item of v1 is deprecated and these headers are therefore not emitted by any route. They describe how a future deprecation will be signalled to you.

Tip

Log every response that contains a Deprecation header and raise an alert. You will be warned by your own monitoring, months before the removal.

New major version

If a v2 comes into being:

  • v1 and v2 will run in parallel for at least twelve months;
  • a migration guide will detail every difference;
  • tokens will remain valid on both versions;
  • webhooks will keep the v1 format until you choose to move to v2.

What is not covered

These items can change without notice. Do not build anything on them.

  • Routes absent from the reference and from the OpenAPI specification.
  • The bridge/* routes, reserved for the link with Novadesko.
  • The exact content of PDF files (layout, labels).
  • The text of error messages and translated labels.
  • The internal format of signed URLs. Treat them as short-lived opaque strings.
  • The data of the demo firm, reset every night.

The long-standing CSV exports (journals, general ledger, trial balance, customer listing, audit trail), on the other hand, have a stable column structure, which falls under the commitments of this page.

Writing a durable integration

  • Ignore the fields, events and enumeration values you do not know.
  • Decide according to the HTTP status, then according to code, never according to message.
  • Send a User-Agent that identifies your integration and its version, for example ERP-Atelier/2.4 (support@atelier.example). We will be able to contact you if needed.
  • Check the changelog at each version upgrade of your product.
  • Regenerate your client from the OpenAPI specification from time to time to benefit from the additions.

See also