Zum Inhalt springen
Dokumentation
Handbuch API Demo
Deutsch
App öffnen

Versionsrichtlinie

Wie sich die NovaFisko-API weiterentwickelt, was als kompatible oder als inkompatible Änderung gilt und die Ankündigungsfrist von sechs Monaten bei Abkündigungen.

Aktualisiert am 05.10.2026 Diese Seite bearbeiten

Eine Integration muss jahrelang unbeaufsichtigt laufen können. Diese Seite beschreibt die Zusagen von NovaFisko zur Weiterentwicklung seiner API und was wir im Gegenzug von Ihrem Code erwarten.

Die Version steht im Pfad

Die Hauptversion steht in der URL: https://api.novafisko.com/v1/.... Das Feld api_version der Webhooks trägt denselben Wert.

Solange Sie /v1/ aufrufen, sind Sie von keiner inkompatiblen Änderung betroffen. Eine inkompatible Weiterentwicklung führt zu einer neuen Hauptversion, /v2/, die neben der vorherigen veröffentlicht wird.

Es gibt keine Nebenversion, die per Header auszuwählen wäre. Kompatible Ergänzungen werden fortlaufend in v1 ausgerollt und im Änderungsprotokoll festgehalten.

Kompatible Änderungen

Diese Änderungen können jederzeit und ohne Vorankündigung eintreten. Ihre Integration muss sie tolerieren.

Änderung Was Ihr Code tun muss
Neue Route Nichts
Neues Feld in einer Antwort oder in einem Webhook Unbekannte Felder ignorieren
Neuer optionaler Parameter in einem Request Nichts
Neues Webhook-Ereignis Mit 200 antworten und unbekannte Ereignisse ignorieren
Neuer Wert in einer offenen Aufzählung (status, code, type) Einen Standardfall vorsehen
Neuer Fehler-code Sich zuerst auf den HTTP-Status stützen
Neuer Response-Header Nichts
Anhebung eines Rate- oder Größenlimits Nichts
Änderung des Textes einer message Meldungen niemals analysieren
Änderung der Reihenfolge der Schlüssel eines JSON-Objekts Nicht von dieser Reihenfolge abhängen
Achtung

Ein strikter Deserialisierer, der bei einem unbekannten Feld scheitert, bricht bei der ersten Ergänzung. Konfigurieren Sie Ihren Client so, dass er ignoriert, was er nicht kennt. Das ist die häufigste Ursache für den Ausfall einer Integration.

Inkompatible Änderungen

Diese Änderungen werden niemals in einer bestehenden Version vorgenommen.

  • Eine Route, ein Feld oder einen Parameter entfernen oder umbenennen.
  • Den Typ eines Feldes ändern, zum Beispiel von einer Zeichenfolge zu einer Zahl.
  • Einen bisher optionalen Parameter zur Pflicht machen.
  • Die Bedeutung eines bestehenden Feldes oder Status ändern.
  • Einen Aufzählungswert oder ein Webhook-Ereignis entfernen.
  • Das Format der Kennungen, der Datumsangaben oder der Beträge ändern.
  • Das Signaturschema der Webhooks ändern.
  • Den HTTP-Status eines dokumentierten Erfolgs- oder Fehlerfalls ändern.
  • Ein dokumentiertes Rate-Limit senken.

Ausnahmen

Drei Situationen können eine Änderung ohne Einhaltung der Ankündigungsfrist rechtfertigen:

  1. Sicherheit. Eine Schwachstelle wird sofort behoben, auch wenn die Korrektur ein Verhalten ändert.
  2. Gesetzliche Pflicht. Eine von der Verwaltung vorgeschriebene Änderung (MwSt., Intervat, Peppol, Jahresabschluss) gilt ab dem gesetzlich festgelegten Datum.
  3. Fehlerkorrektur. Ein Verhalten, das der Dokumentation widerspricht, wird korrigiert. Wenn sich Integrationen erkennbar darauf stützen, informieren wir vorab.

In jedem dieser Fälle wird die Änderung im Änderungsprotokoll angekündigt.

Abkündigung

Wenn eine Route oder ein Feld entfallen soll, folgt NovaFisko diesem Zeitplan.

Schritt Zeitpunkt Was geschieht
Ankündigung T Eintrag im Änderungsprotokoll, Hinweis in der Referenz und in der OpenAPI-Spezifikation (deprecated: true)
Kennzeichnung Ab T Die betroffenen Antworten tragen die Header Deprecation und Sunset
Erinnerung T + 3 Monate Nachricht an die Administratoren der Kanzleien, deren Tokens das Element noch verwenden
Entfernung Frühestens T + 6 Monate Das Element wird entfernt. Eine entfernte Route antwortet mit 410 Gone

Die Mindestfrist zwischen Ankündigung und Entfernung beträgt sechs Monate.

Abkündigungs-Header

HTTP/1.1 200 OK
Deprecation: @1798761600
Sunset: Wed, 30 Jun 2027 23:59:59 GMT
Link: <https://docs.novafisko.com/de/api/changelog>; rel="deprecation"
Header Bedeutung
Deprecation Datum, ab dem das Element abgekündigt ist, als Unix-Zeitstempel mit vorangestelltem @
Sunset Datum, ab dem das Element nicht mehr funktionieren kann
Link mit rel="deprecation" Seite, die den Ersatz beschreibt
Hinweis

Derzeit ist kein Element von v1 abgekündigt, und diese Header werden daher von keiner Route gesendet. Sie beschreiben, wie Ihnen eine künftige Abkündigung angezeigt wird.

Tipp

Protokollieren Sie jede Antwort, die einen Header Deprecation enthält, und lösen Sie einen Alarm aus. So werden Sie von Ihrem eigenen Monitoring gewarnt, Monate vor der Entfernung.

Neue Hauptversion

Sollte eine v2 entstehen:

  • v1 und v2 laufen mindestens zwölf Monate parallel;
  • ein Migrationsleitfaden erläutert jeden Unterschied im Einzelnen;
  • die Tokens bleiben in beiden Versionen gültig;
  • die Webhooks behalten das Format v1, solange Sie sich nicht für den Wechsel zu v2 entschieden haben.

Was nicht abgedeckt ist

Diese Elemente können sich ohne Vorankündigung ändern. Bauen Sie nichts darauf auf.

  • Routen, die in der Referenz und in der OpenAPI-Spezifikation fehlen.
  • Die Routen bridge/*, die der Anbindung an Novadesko vorbehalten sind.
  • Der genaue Inhalt der PDF-Dateien (Layout, Bezeichnungen).
  • Der Text der Fehlermeldungen und der übersetzten Bezeichnungen.
  • Das interne Format der signierten URLs. Behandeln Sie sie als opake Zeichenfolgen mit kurzer Lebensdauer.
  • Die Daten der Demo-Kanzlei, die jede Nacht zurückgesetzt werden.

Die seit Langem bestehenden CSV-Exporte (Journale, Hauptbuch, Saldenliste, Kundenliste, Prüfprotokoll) haben dagegen eine stabile Spaltenstruktur, die unter die Zusagen dieser Seite fällt.

Eine langlebige Integration schreiben

  • Ignorieren Sie Felder, Ereignisse und Aufzählungswerte, die Sie nicht kennen.
  • Entscheiden Sie anhand des HTTP-Status, dann anhand von code, niemals anhand von message.
  • Senden Sie einen User-Agent, der Ihre Integration und ihre Version kennzeichnet, zum Beispiel ERP-Atelier/2.4 (support@atelier.example). So können wir Sie bei Bedarf kontaktieren.
  • Sehen Sie bei jedem Versionssprung Ihres Produkts im Änderungsprotokoll nach.
  • Generieren Sie Ihren Client von Zeit zu Zeit neu aus der OpenAPI-Spezifikation, um von den Ergänzungen zu profitieren.

Siehe auch