Uw eigen systeem koppelen aan FenoFin via de REST API

1. De korte versie

FenoFin is een volledig boekhoudsysteem, open via de REST API. Dat betekent dat uw eigen software — een webshop, kassasysteem, facturatiepakket of een eigen script — rechtstreeks met een FenoFin-administratie praat. U leest administraties, boekjaren, het rekeningschema, relaties en de saldibalans uit én levert relaties, facturen, journaalposten en dagomzet aan — met idempotente verwerking en webhooks.

Kernpunten in één blik:

• REST API op /api/v1/ met OpenAPI-documentatie — lezen én aanleveren
• Eigen API-sleutels per koppeling, begrensd per administratie en per scope
• Een sandbox-administratie om veilig in te testen — connector-gebruikers starten direct
• Test-sleutels werken nooit op een echte administratie, en andersom
• Verplichte Idempotency-Key: een herhaling met dezelfde key en dezelfde body boekt niet opnieuw; u krijgt het eerste antwoord terug
• Fouten in een vast, machineleesbaar formaat (RFC 9457)

2. API of Connector: wanneer gebruikt u wat

FenoFin heeft twee ingangen voor externe systemen, en ze bestaan met een reden naast elkaar.

De FenoFin Connector is gebouwd voor AI-assistenten zoals Claude. Een AI-agent werkt in gesprekvorm: hij kiest een administratie, stelt een boeking voor, en u bevestigt voordat er iets gebeurt. Die voorstel-en-bevestig-cyclus is precies wat u wilt als een taalmodel het werk doet.

De REST API is gebouwd voor software. Een kassasysteem dat elke avond de omzet doorzet heeft geen gesprek nodig — het heeft voorspelbare endpoints nodig, vaste foutcodes, en de garantie dat hetzelfde verzoek nooit twee keer wordt verwerkt. Machine praat met machine, zonder tussenkomst.

Vuistregel: laat u een AI met uw administratie werken, dan is de Connector uw ingang. Koppelt u een systeem dat automatisch data uitwisselt, dan is dat de REST API.

3. Wat u aanlevert en uitleest

Aanleveren — elke schrijfactie is idempotent en wordt volledig gevalideerd voordat er iets geboekt wordt:

• Relaties — afnemers en leveranciers aanmaken en bijwerken
• Verkoopfacturen — als concept, en met een aparte, bewuste aanroep definitief maken (factuurnummer, openstaande post en journaalpost in één transactie)
• Inkoopfacturen — direct geboekt, met documentupload in twee stappen en een 409 bij een dubbel factuurnummer
• Journaalposten — totaalboekingen rechtstreeks op grootboekrekeningen: afschrijvingen, correcties of periodieke totalen
• Loonjournaal — de loonjournaalpost per loonperiode uit elk loonpakket (Het Loonloket, AFAS, Loket, eigen script): FenoFin activeert de standaard RGS-loonrekeningen, boekt de memoriaalpost, weigert een dubbele periode en toont de aanlevering onder Lonen → Verloningen, naast de native Nmbrs-koppeling
• Kasboekregels — het kassascenario: contante dagomzet per btw-tarief per Z-afslag; pinomzet loopt via de bankkoppeling
• Bulk — honderden regels in één aanlevering, eerst asynchroon gevalideerd met een regel-voor-regel-rapport, geboekt na uw bevestiging

Uitlezen:

• Administraties — de administraties waartoe uw sleutel toegang geeft, met basisgegevens
• Boekjaren — per administratie, met begin- en einddatum
• Producten — actieve verkoopproducten met hun ID, interne code en verkoopprijs; kies bij de overgang naar live de producten van de live-administratie opnieuw
• Grootboekrekeningen — het RGS-gebaseerde rekeningschema, inclusief de markering welke rekeningen open staan voor directe boekingen
• Afnemers en leveranciers — met delta-synchronisatie (?gewijzigd_na=) zodat uw systeem alleen wijzigingen ophaalt
• Saldibalans — per boekjaar of periode, met totalen en resultaat

En webhooks melden uw systeem wat er geboekt is (verkoopfactuur.definitief, inkoopfactuur.aangemaakt, journaalpost.aangemaakt en aanleverings-events) — HMAC-ondertekend, met automatische retry en een afleverlogboek.

4. Uw eerste aanroep

Elke aanroep authenticeert met een API-sleutel als Bearer-token. De sleutel toont zijn omgeving in het formaat: fenofin_test_… voor de sandbox, fenofin_live_… voor productie.

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"

Het /status/-endpoint geeft de omgeving, scopes en vervaldatum van uw sleutel terug — handig als eerste controle. De volledige referentie staat als interactieve documentatie op /api/v1/docs/ en als OpenAPI-schema op /api/v1/schema/, geschikt voor het genereren van een client in uw eigen programmeertaal.

Elke respons bevat rate-limit-headers (X-RateLimit-Limit, -Remaining, -Reset) zodat uw systeem zijn tempo kan aanpassen; bij overschrijding volgt een nette 429 met wachttijd.

5. De sandbox: veilig testen zonder echte gevolgen

Een koppeling bouwt u nooit rechtstreeks tegen een echte administratie. Daarvoor bestaat de sandbox-administratie: een volwaardige FenoFin-administratie met een realistisch bedrijfsprofiel (bijvoorbeeld een BV, eenmanszaak of stichting, elk met het bijbehorende rekeningschema), die aantoonbaar niets naar buiten kan sturen.

De scheiding is hard, op drie niveaus:

• Sleutels zijn omgevingsgebonden. Een test-sleutel bereikt uitsluitend sandbox-administraties; een live-sleutel uitsluitend echte. Kruislings krijgt u altijd een 404 — de API laat niet eens weten dat de administratie bestaat.
• Uitgaande kanalen zijn geblokkeerd. E-mail, WhatsApp, ondertekenverzoeken en aangiften worden in een sandbox op de verzendlaag zelf geweigerd. Een testfactuur kan dus nooit bij een echte ontvanger landen.
• Geen facturatie. Een sandbox telt niet mee in uw abonnement. U zet hem op elk moment terug in de startstand met de knop Resetten (Mijn kantoor → Sandbox); uw sleutels en webhooks blijven werken.
• Live schrijven zet u zelf aan. In de sandbox schrijft een test-sleutel direct, voor zover zijn scopes dat toestaan. Bij het aanmaken van een live-sleutel met een schrijfscope bevestigt u expliciet dat de koppeling in uw echte administraties mag boeken; per sleutel zet u schrijven op elk moment weer uit. Test dus altijd eerst volledig in de sandbox.

Gebruikt u de FenoFin Connector als administratief dienstverlener? Dan kunt u direct starten — de sandbox hoort bij uw connector-toegang. Eén afspraak: gebruik in een sandbox nooit echte persoonsgegevens.

6. Beveiliging: hoe de grenzen werken

Een boekhoudkoppeling raakt gevoelige data; de API is daarom begrensd op drie assen die elkaar versterken:

• Administratiegrens. Elke sleutel is te beperken tot specifieke administraties. Elke aanvraag wordt tegen die grens getoetst — op de server, bij elk verzoek, zonder uitzonderingen.
• Functionele scopes. Een sleutel krijgt alleen de rechten die de koppeling nodig heeft: een rapportagekoppeling kan de saldibalans lezen maar geen relaties, en andersom. Ook schrijfrechten zijn per domein: een sleutel voor de kassa-koppeling hoeft geen verkoopfacturen te kunnen aanmaken.
• Sleutelbeheer. Sleutels (test en live) beheert u zelf onder Mijn kantoor → Sandbox: aanmaken, roteren en intrekken. Ze worden versleuteld opgeslagen (alleen een afgeleide hash staat in de database) en de volledige sleutel is maar één keer zichtbaar, direct na aanmaak.

Foutmeldingen volgen RFC 9457 (application/problem+json): elk probleem heeft een stabiele, machineleesbare code en een Nederlandse toelichting, zodat uw software er programmatisch op kan reageren. Meer over gegevensbescherming bij AI- en API-gebruik leest u in Dataretentie bij AI-gebruik.

7. Veelgestelde vragen

Kan ik facturen aanleveren via de API?
Ja — verkoopfacturen (concept en definitief) en inkoopfacturen inclusief het factuurdocument. Documenten aanleveren kan daarnaast via het persoonlijke documenten-mailadres van uw administratie of via de Connector; zie Documentenbeheer in FenoFin.

Werkt de API ook voor mijn klanten?
De sandbox en API-sleutels zijn beschikbaar voor administratief dienstverleners met connector-toegang. Softwareleveranciers met een geregistreerde applicatie kunnen daarnaast via OAuth 2.1 toegang vragen; u geeft die toestemming per administratie en kunt haar op elk moment intrekken onder Mijn kantoor → Verleende API-toegang. Bent u softwareleverancier, dan beschrijft het OAuth-recept aanmelden, toestemming en tokens.

Wat gebeurt er als mijn systeem hetzelfde verzoek twee keer stuurt?
Dan wordt het één keer verwerkt, mits de herhaling dezelfde Idempotency-Key draagt. Die header is verplicht op elke schrijfactie. Maak per handeling één key en bewaar hem: herhaalt uw systeem na een time-out exact hetzelfde verzoek met dezelfde key, dan krijgt het het oorspronkelijke antwoord terug en wordt niets dubbel geboekt (minimaal 24 uur, per API-sleutel). Een nieuwe key geldt als een nieuwe handeling. Loonjournaalposten zijn daarnaast per loonperiode beveiligd: dezelfde periode een tweede keer geeft een 409.

Kan ik mijn loonpakket koppelen?
Ja. Nmbrs is de ingebouwde koppeling; elk ander loonpakket levert de loonjournaalpost per loonperiode aan via POST …/loonjournaal/ (scope lonen:write) met bron, jaar, periode, datum en de regels op RGS-code of FenoFin-grootboeknummer. Dezelfde periode een tweede keer aanleveren geeft een 409 en boekt niets dubbel; met GET …/loonjournaal/?jaar= ziet uw koppeling welke periodes al geboekt zijn. Het volledige recept — inclusief een werkende referentie-implementatie die u aan een AI-assistent kunt geven — staat op /ontwikkelaars/loonjournaal.md; de samenvatting op de ontwikkelaarspagina.

Waar begin ik?
Op de ontwikkelaarspagina staat de quickstart; wilt u eerst zien wat de Connector voor uw kantoor doet, lees dan Starten met de FenoFin Connector.