Naar de inhoud
Documentatie
Handleiding API Demo
Nederlands
De applicatie openen

Een dossier aanmaken

Use case stap voor stap om via de API een boekhouddossier aan te maken, met zijn rekeningenstelsel, dagboeken, boekjaar en bankrekeningen.

Bijgewerkt op 05-10-2026 Deze pagina bewerken

Deze gids maakt een Belgisch dossier aan dat klaar is om boekingen te ontvangen. Met één enkele aanroep installeert NovaFisko het rekeningenstelsel van het land, de dagboeken, de btw-codes, het boekjaar en zijn periodes.

Vereisten: een sessietoken of een integratietoken met de bevoegdheden read en write, in het bezit van een beheerder of een manager van het kantoor.

Stap 1: het kantoor identificeren

De public_token van het kantoor staat in het antwoord van auth/me.

curl https://api.novafisko.com/v1/auth/me \
  -H "Authorization: Bearer $NOVAFISKO_TOKEN"

{
  "id": 12,
  "name": "Claire Dumont",
  "email": "claire.dumont@fiduciaire-exemple.be",
  "locale": "fr",
  "is_platform_admin": false,
  "is_demo": false,
  "firms": [{"public_token": "Fd7hQ2mN8sXa", "name": "Fiduciaire Exemple", "role": "admin"}],
  "managed_firms": [{"public_token": "Fd7hQ2mN8sXa", "name": "Fiduciaire Exemple"}]
}

U kunt alleen een dossier aanmaken in een kantoor dat in managed_firms staat. Als de gebruiker er maar één beheert, wordt het veld firm van stap 3 optioneel.

Stap 2 (optioneel): vooraf invullen op basis van het ondernemingsnummer

De bedrijfsopzoeking bevraagt CompanySearch voor België en Frankrijk. Zo hoeft u het adres en de rechtsvorm niet in te voeren.

curl "https://api.novafisko.com/v1/lookup/search?q=0999.900.134&country=BE" \
  -H "Authorization: Bearer $NOVAFISKO_TOKEN"

Neem de identiteitsvelden van de teruggegeven fiche over in de body van stap 3. De beschikbare landenpakketten worden opgelijst door GET /v1/country-packs en de rechtsvormen door GET /v1/reference/legal-forms.

Stap 3: het dossier aanmaken

curl -X POST https://api.novafisko.com/v1/companies \
  -H "Authorization: Bearer $NOVAFISKO_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "firm": "Fd7hQ2mN8sXa",
    "country_pack": "BE",
    "code": "ATELIER",
    "name": "Atelier du Vélo SRL",
    "enterprise_number": "0999.900.134",
    "vat_number": "BE0999900134",
    "legal_form": "SRL",
    "street": "Rue des Carmes",
    "house_number": "18",
    "postal_code": "5000",
    "city": "Namur",
    "country": "BE",
    "vat_regime": "quarterly",
    "locale": "fr",
    "fiscal_year": {"code": "2026", "starts_on": "2026-01-01", "ends_on": "2026-12-31"},
    "banks": [
      {"code": "BNK1", "label": "Compte à vue Belfius", "iban": "BE68539007547034"}
    ]
  }'

Belangrijkste velden

Veld Verplicht Beschrijving
name ja Benaming, max. 200 tekens
firm nee public_token van het beherende kantoor (12 tekens)
country_pack nee Standaard BE. Bepaalt het rekeningenstelsel, de btw en de controles
code nee Korte code van het dossier, max. 20 tekens, letters, cijfers, koppeltekens. Omgezet in hoofdletters
enterprise_number nee Gecontroleerd volgens het land (modulo 97 voor België)
vat_number nee Formaat en controlegetal gecontroleerd volgens het land
legal_form, legal_form_code nee Vrije omschrijving of code uit de referentielijst
street, house_number, box, postal_code, city, country nee Gestructureerd adres
vat_regime nee monthly, quarterly, franchise, exempt of unit, afhankelijk van het pakket
locale nee fr, nl, en of de. Standaard de taal van de gebruiker
fiscal_year nee Indien aanwezig zijn starts_on en ends_on verplicht. Anders wordt het lopende kalenderjaar als boekjaar aangemaakt
banks nee Eén financieel dagboek per rekening: code (max. 6 tekens), label, iban

Antwoord 201

{
  "id": 318,
  "public_token": "Av4eLo7Nm2Sr",
  "firm_id": 4,
  "code": "ATELIER",
  "name": "Atelier du Vélo SRL",
  "legal_form": "SRL",
  "enterprise_number": "0999.900.134",
  "vat_number": "BE0999900134",
  "address": "Rue des Carmes 18, 5000 Namur",
  "street": "Rue des Carmes",
  "house_number": "18",
  "postal_code": "5000",
  "city": "Namur",
  "country": "BE",
  "country_pack": "BE",
  "vat_regime": "quarterly",
  "currency": "EUR",
  "locale": "fr",
  "is_active": true,
  "version": 1,
  "firm": {"id": 4, "public_token": "Fd7hQ2mN8sXa", "name": "Fiduciaire Exemple"},
  "fiscal_years": [
    {
      "id": 702,
      "code": "2026",
      "starts_on": "2026-01-01T00:00:00.000000Z",
      "ends_on": "2026-12-31T00:00:00.000000Z",
      "is_closed": false,
      "periods": [
        {"id": 9001, "number": 1, "label": "01/2026", "starts_on": "2026-01-01T00:00:00.000000Z", "ends_on": "2026-01-31T00:00:00.000000Z", "is_locked": false}
      ]
    }
  ],
  "journals": [
    {"id": 2101, "code": "ACH", "label": "Achats", "type": "purchase", "control_account": {"id": 55090, "number": "440000", "label": "Fournisseurs"}},
    {"id": 2102, "code": "VEN", "label": "Ventes", "type": "sale", "control_account": {"id": 55041, "number": "400000", "label": "Clients"}},
    {"id": 2105, "code": "BNK1", "label": "Compte à vue Belfius", "type": "financial", "iban": "BE68539007547034"}
  ]
}

Bewaar public_token: dat is de identificator van het dossier in alle volgende routes. De lijsten periods en journals zijn hier ingekort.

Stap 4: de installatie controleren

curl https://api.novafisko.com/v1/companies/Av4eLo7Nm2Sr/accounts?postable=1 \
  -H "Authorization: Bearer $NOVAFISKO_TOKEN"

curl https://api.novafisko.com/v1/companies/Av4eLo7Nm2Sr/vat-codes \
  -H "Authorization: Bearer $NOVAFISKO_TOKEN"

Deze twee aanroepen geven het rekeningenstelsel en de btw-codes van het dossier terug, met de id's die u nodig hebt om boekingen in te voeren.

Veelvoorkomende fouten

Status Oorzaak Oplossing
422, veld enterprise_number Ongeldig ondernemingsnummer voor het land Het controlegetal nakijken
422, veld vat_number Btw-nummer verkeerd opgebouwd Het landprefix toevoegen, bijvoorbeeld BE0999900134
422, veld firm Het kantoor wordt niet door de gebruiker beheerd Een public_token uit managed_firms gebruiken
422, code company_limit_reached Dossierplafond van de licentie bereikt Zie De licentie raadplegen
403, code token_ability_missing Token zonder de bevoegdheid write Een geschikt token aanmaken
Opmerking

Zonder kantoor (firm afwezig en geen enkel beheerd kantoor) wordt het dossier aangemaakt als zelfstandig dossier en wordt de gebruiker er de verantwoordelijke van. Dit geval betreft de zelfstandigen die hun boekhouding zelf voeren.

Tip

Een X-Client-Mutation-Id meesturen heeft hier geen zin: de route POST /v1/companies is niet aan een bestaand dossier gekoppeld. Om een dubbel dossier na een netwerkonderbreking te vermijden, leest u GET /v1/companies opnieuw en zoekt u uw code voordat u het opnieuw probeert.

Zie ook