Naar de inhoud
Documentatie
Handleiding API Demo
Nederlands
De applicatie openen

Conventies

Formaten van datums en bedragen, identificatoren public_token en numerieke id, taal van de berichten en headers die de NovaFisko-API herkent.

Bijgewerkt op 05-10-2026 Deze pagina bewerken

Deze pagina bundelt de regels die voor alle routes gelden. Wie ze naleeft, vermijdt de meeste 422-fouten.

Requests

  • Stuur Accept: application/json mee bij elke aanroep. De host api.novafisko.com antwoordt altijd in JSON, maar deze header garandeert hetzelfde gedrag achter een proxy.
  • De body's zijn in JSON (Content-Type: application/json), gecodeerd in UTF-8.
  • Het uploaden van bestanden (document-imports) gebruikt multipart/form-data.
  • De veldnamen zijn in het Engels en in snake_case. De URL-segmenten zijn in kebab-case (third-parties, vat-declarations).

Datums en tijdstippen

Aard Formaat Voorbeeld
Boekhouddatum (entry_date, due_date, starts_on, from, to) JJJJ-MM-DD 2026-03-31
Tijdstempel (created_at, posted_at, server_time) ISO 8601 met tijdzone, in UTC 2026-10-05T08:30:11+00:00
Facturatiemaand JJJJ-MM 2026-10

Een boekhouddatum heeft geen tijdzone: 31 maart blijft 31 maart, waar u ook vandaan aanroept. De tijdstempels worden in UTC opgeslagen en teruggegeven. Zet ze bij de weergave om naar de tijdzone van uw gebruiker.

Opmerking

In de antwoorden kan een boekhouddatum van een model in de lange vorm 2026-03-31T00:00:00.000000Z verschijnen. Houd alleen rekening met de eerste tien tekens. Stuur als invoer altijd JJJJ-MM-DD.

Bedragen

De bedragen worden uitgedrukt in euro, als decimale strings met een punt en twee decimalen: "1250.00", "0.21", "-48.40".

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

Deze keuze vermijdt de afrondingsfouten van floating-pointgetallen. Gebruik in uw code een decimaal type (BigDecimal, decimal, Decimal, bcmath) of werk in gehele centen.

Als invoer aanvaardt de API zowel "1250.00" als 1250 of 1250.5. Ze zet alles om in centen voordat ze rekent. Wij raden aan strings te versturen.

Let op

Enkele beheerantwoorden (licentie, tarieftabel, simulator) geven JSON-getallen terug, bijvoorbeeld "total": 149.0. Dat zijn commerciële bedragen, geen boekhoudkundige bedragen. Alle boekhoudkundige staten (proef- en saldibalans, grootboek, boekingen, btw) gebruiken strings.

Een boeking moet tot op de cent in evenwicht zijn: de som van de debetbedragen is gelijk aan de som van de creditbedragen, anders wordt de request geweigerd met 422.

Identificatoren

NovaFisko gebruikt twee families van identificatoren.

Resource Identificator in de URL Vorm Voorbeeld
Kantoor (firm) public_token 12 alfanumerieke tekens Fd7hQ2mN8sXa
Dossier (company) public_token 12 alfanumerieke tekens k3Jd9fPq2LmX
Alles wat in een dossier leeft (boeking, derde, rekening, dagboek, document, boekjaar...) numerieke id geheel getal 1842

De public_token is ondoorzichtig, stabiel en niet te raden. Die moet u opslaan om naar een kantoor of een dossier te verwijzen. De numerieke id's hebben alleen betekenis binnen hun dossier: een route companies/{company}/entries/{id} antwoordt 404 als de boeking tot een ander dossier behoort.

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

Sommige velden aanvaarden een leesbare vorm in plaats van de id. In een boeking kan een lijn bijvoorbeeld haar rekening aanduiden met account_id (geheel getal) of met account (rekeningnummer, "604000"). Op dezelfde manier aanvaardt een factuurlijn vat_code_id of vat_code.

Geïmporteerde gegevens

De records die uit een andere bron komen, dragen drie velden: source (bijvoorbeeld novadesko), external_id (de identificator in de bron) en synced_at. Gebruik external_id om een record terug te vinden dat u zelf hebt doorgestuurd.

Versie van een record

De resources die door de geschiedenis worden gevolgd, tonen een geheel getal version dat bij elke wijziging toeneemt. Stuur het terug in X-Base-Version om de optimistische vergrendeling te activeren die beschreven staat in Idempotentie.

Taal van de berichten

De omschrijvingen en foutberichten bestaan in het Frans, Nederlands, Engels en Duits. De taal wordt als volgt gekozen:

  1. de queryparameter locale (routes voor geschiedenis, prullenbak en synchronisatie) of lang (exports, licentie) wanneer die is opgegeven;
  2. anders de taal van het profiel van de gebruiker die eigenaar is van het token;
  3. anders de header Accept-Language;
  4. anders de standaardtaal van het platform.
GET /v1/firms/Fd7hQ2mN8sXa/licence?lang=nl HTTP/1.1
Accept-Language: nl-BE,nl;q=0.9,fr;q=0.6
Tip

Laat uw logica nooit afhangen van de tekst van message, die per taal verschilt. Steun op de HTTP-status en op het veld code.

Request-headers

Header Rol
Authorization Bearer <token>
Accept application/json
Accept-Language Gewenste taal voor de berichten
X-Client-Mutation-Id Idempotentiesleutel van een schrijfbewerking, max. 64 tekens. Zie Idempotentie
X-Base-Version Gekende versie van het gewijzigde record (optimistische vergrendeling)
X-Operation-Id UUID die alle wijzigingen van eenzelfde actie groepeert. Gegenereerd door de server als hij ontbreekt
X-Device-Id Stabiele identificator van de installatie of de connector, max. 64 tekens
X-Device-Name Leesbare naam van het toestel, procentgecodeerd, max. 120 tekens
X-Device-Platform Platform (web, macos, linux, integration...)
X-Occurred-At ISO 8601-datum van de actie aan clientzijde, begrensd tot plus of min 24 uur rond de servertijd
X-Origin offline_sync wanneer de request een offline uitgevoerde actie opnieuw afspeelt

De headers X-Device-* zijn optioneel maar nuttig: ze verschijnen in het tabblad Geschiedenis, zodat een boekhouder kan zien dat een wijziging van uw connector komt.

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-headers

Header Betekenis
X-Operation-Id Identificator van de bewerking wanneer er iets in de geschiedenis is vastgelegd. Hij dient voor het terugdraaien: POST history/operations/{operation}/revert
X-Trashed: 1 De DELETE heeft het record in de prullenbak geplaatst in plaats van het te vernietigen. Het blijft herstelbaar
X-Idempotent-Replay: 1 Het antwoord is het opgeslagen resultaat van een request die al is uitgevoerd
X-Export-Fingerprint SHA-256-vingerafdruk van de geëxporteerde dataset
Content-Disposition Bestandsnaam voor de exports
Retry-After Wachttijd in seconden voordat u het opnieuw probeert na een 429

Verwijderingen

Een verwijdering vernietigt bijna nooit iets onmiddellijk:

  • een derde, een rekening, een dagboek, een regel of een vast actief gaat naar de prullenbak (X-Trashed: 1) en kan worden hersteld gedurende de bewaartermijn van het dossier, standaard 90 dagen;
  • een gevalideerde boeking wordt niet verwijderd: ze wordt tegengeboekt met POST entries/{id}/reverse, wat de doorlopende nummering vrijwaart.

Zie ook