Voor ontwikkelaars

REST API

Koppel uw software aan FenoFin

FenoFin is een volledig boekhoudsysteem, open via de REST API. Uw software levert relaties, verkoopfacturen, inkoopfacturen (met documenten), journaalposten en kasboekregels aan, en leest administraties, het rekeningschema en de saldibalans uit. U test veilig in een sandbox-administratie: een testomgeving binnen FenoFin waarin uitgaande e-mail, WhatsApp en aangiften hard geblokkeerd zijn.

  • Versioneerde API (/api/v1/) met OpenAPI-specificatie
  • Verplichte Idempotency-Key: een herhaling met dezelfde key en dezelfde body boekt niet opnieuw; u krijgt het eerste antwoord terug
  • Webhooks met HMAC-ondertekening en retry melden wat er geboekt is
  • Fouten volgens RFC 9457 met stabiele, machineleesbare codes
Open de API-documentatie
Sandbox-administratie aanmaken vanuit Mijn kantoor — daar sluit u uw eigen systemen direct aan via de REST API
Quickstart

In drie stappen aan de slag

1. Sandbox & sleutel

Gebruikt u de FenoFin Connector als administratief dienstverlener? Dan kunt u direct starten: maak onder Mijn kantoor → Sandbox met één knop een sandbox-administratie aan (vijf profielen, van bv tot eenmanszaak). U ontvangt direct een test-API-sleutel (fenofin_test_…) die uitsluitend op sandbox-administraties werkt — kruislings met een echte administratie krijgt u altijd een 404. Op dezelfde pagina beheert u al uw sleutels (test én live): aanmaken, roteren en intrekken. Is uw koppeling klaar, dan maakt u op dezelfde pagina een live-sleutel (fenofin_live_…) voor uw echte administraties. Stel die sleutel in uw software in en kies de live-administratie en bijbehorende product-ID's opnieuw. De basis-URL blijft gelijk; sandboxgegevens worden niet overgezet.

2. Eerste aanroep

Controleer de sleutel, haal uw administraties op en lever een afnemer aan:

curl https://www.fenofin.nl/api/v1/status/ \ -H "Authorization: Bearer fenofin_test_UW_SLEUTEL" curl https://www.fenofin.nl/api/v1/administraties/ \ -H "Authorization: Bearer fenofin_test_UW_SLEUTEL" KEY=$(uuidgen) curl -X POST https://www.fenofin.nl/api/v1/administraties/ID/afnemers/ \ -H "Authorization: Bearer fenofin_test_UW_SLEUTEL" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $KEY" \ -d '{"naam": "Eerste Klant BV"}'

Vervang ID door het id van uw sandbox uit de administratielijst; hetzelfde nummer staat tussen haakjes achter de naam op Mijn kantoor → Sandbox. Maak per handeling één Idempotency-Key en bewaar hem: herhaalt u na een time-out exact hetzelfde verzoek met dezelfde key, dan krijgt u het oorspronkelijke antwoord terug (X-Idempotent-Replay: true) en wordt niets dubbel geboekt. Dat geldt minimaal 24 uur en per sleutel (bij OAuth per toestemming). Dezelfde key met een andere body na een geslaagd verzoek geeft 409. Eindigde een verzoek in een fout, dan is niets vastgelegd en mag de gecorrigeerde herhaling dezelfde key gebruiken.

3. Bouwen met de referentie

De volledige API-referentie is beschikbaar als OpenAPI-document met interactieve documentatie:

API-documentatie (ReDoc)
OpenAPI-schema (YAML)

Webshop-recept: van productkeuze tot definitieve factuur en live-controle. Inclusief scopes, idempotency en de betekenis van een geslaagde koppeling.

OAuth-recept voor softwareleveranciers: toestemming, tokens en foutafhandeling.

Verdieping in de kennisbank: Uw eigen systeem koppelen via de REST API.

Loonpakketten

Loonjournaal uit uw loonpakket, automatisch geboekt

Gebruikt u een ander loonpakket dan Nmbrs — Het Loonloket, AFAS, Loket of een eigen script? Lever na iedere verloning de loonjournaalpost aan op één endpoint. FenoFin activeert de standaard RGS-loonrekeningen, boekt de memoriaalpost, weigert een dubbele loonperiode en toont de aanlevering onder Lonen → Verloningen, naast de Nmbrs-runs.

Zo werkt het

  1. Sleutel met de scopes grootboek:read, lonen:read en lonen:write.
  2. Koppel de rubrieken van uw loonpakket éénmalig aan een RGS-code of FenoFin-nummer — een regel accepteert rgs óf grootboeknummer. Het rekeningschema is RGS-gebaseerd en voor alle administraties gelijk: brutoloon WPerLesLon (4001040), premies sociale verzekeringen WPerSolPsv (4002010), pensioenpremies WPerPenPen (4003010), nettoloon BSchSalNet (1204010), loonheffing BSchBepLhe (1205036), pensioenafdracht BSchStz (1204089). Overige rekeningen vindt u met grootboekrekeningen/?actief=true.
  3. Stuur per loonperiode één POST …/loonjournaal/ met bron, jaar, periode, datum en de regels.
  4. Dezelfde bron + jaar + periode nogmaals? Dan 409 loonperiode_al_geboekt — behandel dat als “al gedaan”. Met GET …/loonjournaal/?jaar= ziet u welke periodes al geboekt zijn.

Voorbeeld

KEY=$(uuidgen) curl -X POST https://www.fenofin.nl/api/v1/administraties/ID/loonjournaal/ \ -H "Authorization: Bearer fenofin_test_UW_SLEUTEL" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $KEY" \ -d '{"bron": "loonloket", "jaar": 2026, "periode": 9, "datum": "2026-09-30", "regels": [ {"rgs": "WPerLesLon", "debet": "12500.00"}, {"rgs": "WPerSolPsv", "debet": "2350.00"}, {"rgs": "BSchSalNet", "credit": "9870.00"}, {"rgs": "BSchBepLhe", "credit": "4980.00"} ]}'

Bouwt u met een AI-assistent? Geef hem deze URL — één document met het volledige recept, de foutafhandeling en een werkende referentie-implementatie:
https://www.fenofin.nl/ontwikkelaars/loonjournaal.md

Volledige veldbeschrijving en foutcodes: API-documentatie (Loonjournaalpost aanleveren).

Mogelijkheden

Wat de API kan

  • Aanleveren: afnemers en leveranciers, verkoopfacturen (concept → definitief met factuurnummer en journaalpost), inkoopfacturen met documentupload, memoriaal-journaalposten (totaalboekingen rechtstreeks op grootboek) en kasboekregels voor de kassa-/dagomzetkoppeling
  • Loonjournaal: elk loonpakket levert de loonjournaalpost per loonperiode aan; FenoFin activeert de RGS-loonrekeningen, boekt de memoriaalpost, weigert een dubbele periode en toont de aanlevering bij Lonen — zie loonjournaal/ in de API-referentie
  • Bulk: honderden regels in één aanlevering — eerst asynchroon gevalideerd met een regel-voor-regel-rapport, geboekt na uw bevestiging
  • Uitlezen: administraties, boekjaren, het RGS-rekeningschema (incl. welke rekeningen direct boekbaar zijn), relaties met delta-synchronisatie, en de saldibalans per boekjaar of periode
  • Webhooks: verkoopfactuur.definitief, inkoopfactuur.aangemaakt, journaalpost.aangemaakt en aanleverings-events, HMAC-ondertekend met automatische retry
  • Veiligheid: sleutels per koppeling met scopes en administratiegrenzen, rate limits via X-RateLimit-*-headers, volledig auditlogboek

Voor softwareleveranciers: laat uw klanten zelf per administratie toestemming geven via OAuth 2.1 (authorization code + PKCE), zonder sleutels uit te wisselen. Vier begrippen:

  • Eigen API-sleutel: voor software die u op uw eigen administraties aansluit; u maakt hem zelf aan op Mijn kantoor → Sandbox
  • Leveranciersregistratie: FenoFin registreert uw applicatie na uw aanmelding via contact; u ontvangt eenmalig een client_id en client_secret
  • Goedkeuring en schrijfvrijgave: FenoFin keurt uw applicatie goed en geeft schrijven in echte administraties apart vrij
  • Toestemming per gebruiker: uw klant kiest op het toestemmingsscherm welke administraties uw applicatie mag bereiken en trekt dat op elk moment in onder Mijn kantoor → Verleende API-toegang

Het OAuth-recept beschrijft de hele route: aanmelden, toestemming, tokens en foutafhandeling. Neem contact op om uw applicatie te registreren.

Sandbox

Veilig testen, nooit echte gevolgen

  • Een sandbox is een volwaardige FenoFin-administratie met een realistisch profiel (BV, eenmanszaak, stichting, VOF of holding) en een lopend boekjaar
  • Test-sleutels werken uitsluitend op sandbox-administraties; live-sleutels uitsluitend op echte — kruislings krijgt u altijd een 404
  • Een test-sleutel schrijft in de sandbox direct, voor zover zijn scopes dat toestaan: een sleutel zonder schrijfscope kan alleen lezen
  • Schrijven in de live-omgeving zet u zelf aan: bij het aanmaken van een live-sleutel met een schrijfscope bevestigt u expliciet dat de koppeling in uw echte administraties mag boeken — en per sleutel zet u schrijven op elk moment weer uit. Stel de sleutel daarna in uw software in; geautoriseerde verzoeken werken direct. Sleutelaanmaak start zelf geen synchronisatie of verzending
  • Uitgaande e-mail, WhatsApp, ondertekenverzoeken en aangiften zijn in een sandbox hard geblokkeerd; alleen uw eigen webhooks vuren (met X-FenoFin-Omgeving: test)
  • Een sandbox valt buiten facturatie. Met de knop Resetten op Mijn kantoor → Sandbox zet u hem op elk moment terug in de startstand; uw sleutels en webhooks blijven werken
  • Gebruik nooit echte persoonsgegevens in een sandbox

Koppeling bespreken?

Bouwt u software en wilt u een koppeling met FenoFin aanbieden aan uw klanten? Neem contact op — we denken graag mee over de opzet.

Neem contact op Lees over de FenoFin Connector