Zum Inhalt springen
Dokumentation
Handbuch API Demo
Deutsch
App öffnen

Konventionen

Datums- und Betragsformate, Kennungen public_token und numerische id, Sprache der Meldungen und von der NovaFisko-API erkannte Header.

Aktualisiert am 05.10.2026 Diese Seite bearbeiten

Diese Seite fasst die Regeln zusammen, die für alle Routen gelten. Wer sie einhält, vermeidet die meisten 422-Fehler.

Requests

  • Senden Sie bei jedem Aufruf Accept: application/json. Der Host api.novafisko.com antwortet immer in JSON, doch dieser Header gewährleistet dasselbe Verhalten hinter einem Proxy.
  • Bodys sind JSON (Content-Type: application/json), in UTF-8 kodiert.
  • Der Datei-Upload (document-imports) verwendet multipart/form-data.
  • Feldnamen sind englisch und in snake_case. URL-Segmente sind in kebab-case (third-parties, vat-declarations).

Datum und Uhrzeit

Art Format Beispiel
Buchungsdatum (entry_date, due_date, starts_on, from, to) JJJJ-MM-TT 2026-03-31
Zeitstempel (created_at, posted_at, server_time) ISO 8601 mit Zeitzone, in UTC 2026-10-05T08:30:11+00:00
Abrechnungsmonat JJJJ-MM 2026-10

Ein Buchungsdatum hat keine Zeitzone: Der 31. März bleibt der 31. März, gleichgültig, von wo aus Sie aufrufen. Zeitstempel werden in UTC gespeichert und zurückgegeben. Rechnen Sie sie bei der Anzeige in die Zeitzone Ihres Benutzers um.

Hinweis

In den Antworten kann das Buchungsdatum eines Modells in der Langform 2026-03-31T00:00:00.000000Z erscheinen. Berücksichtigen Sie nur die ersten zehn Zeichen. In der Eingabe senden Sie immer JJJJ-MM-TT.

Beträge

Beträge werden in Euro angegeben, als Dezimalzeichenfolgen mit Punkt und zwei Nachkommastellen: "1250.00", "0.21", "-48.40".

{
  "debit": "1250.00",
  "credit": "0.00",
  "balance": "1250.00"
}

Diese Wahl vermeidet die Rundungsfehler von Gleitkommazahlen. Verwenden Sie in Ihrem Code einen Dezimaltyp (BigDecimal, decimal, Decimal, bcmath) oder rechnen Sie in ganzen Cent.

In der Eingabe akzeptiert die API "1250.00" ebenso wie 1250 oder 1250.5. Sie rechnet alles in Cent um, bevor sie rechnet. Wir empfehlen, Zeichenfolgen zu senden.

Achtung

Einige Verwaltungsantworten (Lizenz, Preistabelle, Simulator) liefern JSON-Zahlen, zum Beispiel "total": 149.0. Das sind kaufmännische Beträge, keine Buchhaltungsbeträge. Alle Buchhaltungsauswertungen (Saldenliste, Hauptbuch, Buchungen, MwSt.) verwenden Zeichenfolgen.

Eine Buchung muss auf den Cent genau ausgeglichen sein: Die Summe der Sollbeträge entspricht der Summe der Habenbeträge, andernfalls wird der Request mit 422 abgelehnt.

Kennungen

NovaFisko verwendet zwei Familien von Kennungen.

Ressource Kennung in der URL Form Beispiel
Kanzlei (firm) public_token 12 alphanumerische Zeichen Fd7hQ2mN8sXa
Mandat (company) public_token 12 alphanumerische Zeichen k3Jd9fPq2LmX
Alles, was in einem Mandat liegt (Buchung, Geschäftspartner, Konto, Journal, Beleg, Geschäftsjahr...) numerische id Ganzzahl 1842

Das public_token ist opak, stabil und nicht erratbar. Speichern Sie dieses, um eine Kanzlei oder ein Mandat zu bezeichnen. Die numerischen id haben nur innerhalb ihres Mandats eine Bedeutung: Eine Route companies/{company}/entries/{id} antwortet mit 404, wenn die Buchung zu einem anderen Mandat gehört.

/v1/companies/k3Jd9fPq2LmX/entries/1842
              └─ public_token       └─ id

Einige Felder akzeptieren anstelle der id eine lesbare Form. In einer Buchung kann eine Zeile ihr Konto zum Beispiel über account_id (Ganzzahl) oder über account (Kontonummer, "604000") bezeichnen. Ebenso akzeptiert eine Rechnungszeile vat_code_id oder vat_code.

Importierte Daten

Datensätze aus einer anderen Quelle tragen drei Felder: source (zum Beispiel novadesko), external_id (die Kennung in der Quelle) und synced_at. Nutzen Sie external_id, um einen Datensatz wiederzufinden, den Sie selbst übermittelt haben.

Version eines Datensatzes

Die vom Verlauf erfassten Ressourcen stellen eine Ganzzahl version bereit, die sich bei jeder Änderung erhöht. Senden Sie sie in X-Base-Version zurück, um die optimistische Sperre zu aktivieren, die unter Idempotenz beschrieben ist.

Sprache der Meldungen

Bezeichnungen und Fehlermeldungen gibt es auf Französisch, Niederländisch, Englisch und Deutsch. Die Sprache wird wie folgt gewählt:

  1. der Query-Parameter locale (Routen für Verlauf, Papierkorb und Synchronisierung) oder lang (Exporte, Lizenz), sofern er angegeben ist;
  2. andernfalls die Sprache im Profil des Benutzers, dem das Token gehört;
  3. andernfalls der Header Accept-Language;
  4. andernfalls die Standardsprache der Plattform.
GET /v1/firms/Fd7hQ2mN8sXa/licence?lang=nl HTTP/1.1
Accept-Language: nl-BE,nl;q=0.9,fr;q=0.6
Tipp

Machen Sie Ihre Logik niemals vom Text in message abhängig, der je nach Sprache variiert. Stützen Sie sich auf den HTTP-Status und das Feld code.

Request-Header

Header Aufgabe
Authorization Bearer <Token>
Accept application/json
Accept-Language Gewünschte Sprache der Meldungen
X-Client-Mutation-Id Idempotenzschlüssel eines Schreibzugriffs, max. 64 Zeichen. Siehe Idempotenz
X-Base-Version Bekannte Version des geänderten Datensatzes (optimistische Sperre)
X-Operation-Id UUID, die alle Änderungen ein und derselben Aktion zusammenfasst. Wird vom Server erzeugt, wenn sie fehlt
X-Device-Id Stabile Kennung der Installation oder des Konnektors, max. 64 Zeichen
X-Device-Name Lesbarer Name des Geräts, prozentkodiert, max. 120 Zeichen
X-Device-Platform Plattform (web, macos, linux, integration...)
X-Occurred-At ISO-8601-Datum der Aktion auf Client-Seite, begrenzt auf plus oder minus 24 Stunden um die Serverzeit
X-Origin offline_sync, wenn der Request eine offline ausgeführte Aktion erneut abspielt

Die Header X-Device-* sind optional, aber nützlich: Sie erscheinen im Reiter Verlauf, sodass ein Buchhalter sehen kann, dass eine Änderung von Ihrem Konnektor stammt.

curl -X POST https://api.novafisko.com/v1/companies/k3Jd9fPq2LmX/third-parties \
  -H "Authorization: Bearer $NOVAFISKO_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Device-Id: erp-atelier-prod" \
  -H "X-Device-Name: ERP%20Atelier" \
  -H "X-Client-Mutation-Id: 6f1c2f0e-7a53-4f0b-9c58-0b8a4a7c2d11" \
  -d '{"type": "supplier", "name": "Brasserie des Collines SA", "vat_number": "BE0999900134"}'

Response-Header

Header Bedeutung
X-Operation-Id Kennung des Vorgangs, wenn etwas im Verlauf festgehalten wurde. Sie dient dem Rückgängigmachen: POST history/operations/{operation}/revert
X-Trashed: 1 Das DELETE hat den Datensatz in den Papierkorb verschoben, statt ihn zu vernichten. Er bleibt wiederherstellbar
X-Idempotent-Replay: 1 Die Antwort ist das gespeicherte Ergebnis eines bereits ausgeführten Requests
X-Export-Fingerprint SHA-256-Prüfsumme des exportierten Datenbestands
Content-Disposition Dateiname bei Exporten
Retry-After Wartezeit in Sekunden vor einem erneuten Versuch nach einem 429

Löschungen

Eine Löschung vernichtet fast nie etwas sofort:

  • ein Geschäftspartner, ein Konto, ein Journal, eine Regel oder eine Anlage wandert in den Papierkorb (X-Trashed: 1) und kann während der Aufbewahrungsdauer des Mandats, standardmäßig 90 Tage, wiederhergestellt werden;
  • eine gebuchte Buchung lässt sich nicht löschen: Sie wird mit POST entries/{id}/reverse storniert, wodurch die fortlaufende Nummerierung erhalten bleibt.

Siehe auch