App koppelen aan boekhoudsoftware: CSV, integraties, API, MCP

Er zijn vier manieren om gegevens vanuit uw applicatie in boekhoudsoftware te krijgen: een CSV exporteren en importeren, een kant-en-klare integratie van de leverancier gebruiken, een publieke API aanroepen vanuit uw eigen code, of een AI-assistent laten werken via een MCP-server. Voor alles wat dagelijks draait is de API de eerlijke keuze, en een goede API-koppeling komt neer op vijf beslissingen: wat u synchroniseert, in welke richting, hoe u herhaalde pogingen veilig maakt (idempotentie), hoe u van wijzigingen op de hoogte raakt (webhooks) en waar de sleutel bewaard wordt.

De vier opties, en wanneer elk volstaat

CSV volstaat voor een overdracht aan de accountant of boekhouder eens per kwartaal. Een kant-en-klare integratie volstaat wanneer de twee producten die u gebruikt toevallig de twee producten zijn die de leverancier heeft gekoppeld. Een API hebt u nodig wanneer de gegevens in uw eigen systeem ontstaan en elke dag volledig moeten aankomen, zonder dat er een persoon tussen zit. MCP is een vijfde laag bovenop de API voor mensen die een assistent vragen stellen in plaats van code te schrijven.

De opties sluiten elkaar niet uit. Een gangbare opzet is API voor de dagelijkse stroom, MCP voor de oprichter die vraagt "wie heeft nog niet betaald?", en een CSV-export aan het einde van het jaar voor de eigen software van de accountant.

Wat u synchroniseert: klanten, facturen, betalingen — in die volgorde

Synchroniseer de objecten die het grootboek nodig heeft om een correcte factuur op te stellen en een betaling af te letteren, en niets meer. In de praktijk zijn dat drie objecten met een onderlinge afhankelijkheid: een klant moet bestaan voordat een factuur ernaar kan verwijzen, en een factuur moet bestaan voordat een betaling ze kan vereffenen.

Klanten

Naam, adres, land, btw-nummer, onderneming of consument, en uw eigen externe identificatie. Het land en de btw-status bepalen de fiscale behandeling; zorg dat die bij het aanmaken kloppen, niet pas op de factuur.

Facturen

Regels met omschrijving, hoeveelheid, eenheidsprijs en de aard van de prestatie; de valuta; de vervaldatum; een verwijzing naar uw bestelling of abonnement. Stuur geen btw-tarief mee — stuur de feiten en laat het grootboek beslissen, anders bouwt u de btw-wetgeving opnieuw in uw app.

Betalingen

Bedrag, datum, valuta en de factuur of facturen die ermee worden vereffend. Als er een betaaldienstverlener bij betrokken is, is diens transactie-ID de sleutel waarmee de uitbetaling later wordt afgestemd.

De richting is van belang. Klanten en facturen stromen doorgaans van uw app naar het grootboek. De betaalstatus stroomt vaak terug — het grootboek ziet de bankfeed, uw app wil weten dat de factuur betaald is. Rapporten (openstaande vorderingen, winst en verlies) stromen alleen terug. Bepaal per object welk systeem de bron van de waarheid is en schrijf hetzelfde veld nooit vanuit beide kanten.

Wat u niet synchroniseert: de interne gebeurtenissen van uw product (aanmeldingen, functiegebruik), conceptbestellingen die misschien nooit gefactureerd worden, en alles waar het grootboek niets mee kan. Elk object dat u doorstuurt, is er een dat u consistent moet houden.

Idempotentie: het antwoord dat nooit aankomt

Een verbinding valt weg nadat het grootboek de klant heeft aangemaakt, maar voordat uw app het antwoord kreeg. Zonder bescherming verliest u het record of maakt u het twee keer aan, en een dubbele klant duikt weken later op wanneer een factuur bij de verkeerde kopie terechtkomt. De oplossing is een idempotentiesleutel: een waarde die u per bedoelde schrijfactie kiest en in een header meestuurt, zodat de server een herhaling herkent.

De Internet-Draft van de IETF voor deze header verwoordt het doel helder: "The HTTP Idempotency-Key request header field can be used to make non-idempotent HTTP methods such as POST or PATCH fault-tolerant." De draft is verlopen zonder RFC te worden, maar het patroon is de conventie in de sector en de headernaam is wat de meeste API's gebruiken. De regels die het aan de serverkant laten werken:

1. Het eerste verzoek onder een sleutel doet het werk en slaat het resultaat op.
2. Een herhaling met dezelfde sleutel en dezelfde body geeft het opgeslagen resultaat terug — hetzelfde record, geen nieuw.
3. Een herhaling met dezelfde sleutel en een andere body wordt geweigerd, omdat een sleutel voor één bedoeling staat.
4. Sleutels verlopen na een bepaalde periode; daarna telt de waarde als nieuw werk.

Aan de clientkant: genereer de sleutel op het moment dat de bedoeling ontstaat (een UUID die u bij uw eigen bestelregel opslaat), niet op het moment dat het verzoek verstuurd wordt, zodat een nieuwe poging na een crash dezelfde sleutel hergebruikt. Probeer opnieuw met backoff bij netwerkfouten en bij 5xx; probeer niet opnieuw bij 4xx, met uitzondering van 429.

Webhooks: wijzigingen vernemen zonder te pollen

Een webhook is een HTTP-verzoek dat de boekhoudsoftware naar uw URL stuurt wanneer er iets gebeurt — een factuur is uitgereikt, een betaling is geboekt. Het vervangt pollen, maar brengt drie verplichtingen mee: de handtekening controleren, rekening houden met dubbele leveringen en snel antwoorden.

De richtlijnen van Stripe zijn de referentie die de meeste ontwikkelaars kennen en ze gelden voor elke aanbieder: "Always verify that webhook events originate from Stripe before acting on them"; "webhook endpoints might occasionally receive the same event more than once", waartegen u zich beschermt "by logging the event IDs you've processed"; en uw endpoint "must quickly return a successful status code (2xx) before any complex logic that could cause a timeout". Stripe merkt ook op dat het "doesn't guarantee the delivery of events in the order that they're generated" — behandel elke gebeurtenis dus als een verwijzing en haal de actuele toestand op als de volgorde ertoe doet.

Handtekeningcontrole volgt doorgaans één patroon: een header met een tijdstempel en een HMAC over timestamp.raw_body; weiger als het tijdstempel buiten een tolerantievenster valt (bescherming tegen replay), bereken de HMAC opnieuw met het endpointgeheim over de ruwe bytes en vergelijk in constante tijd. Frameworks die JSON parsen en opnieuw serialiseren voordat u de body kunt lezen, breken dit; lees de ruwe body.

De sleutel veilig bewaren

Een API-sleutel voor de boekhouding kan elke klant en elke factuur van de onderneming lezen en concepten aanmaken. Behandel hem als een databasewachtwoord: bewaar hem in een secrets manager of omgevingsvariabele, nooit in versiebeheer of een mobiele app, en geef hem alleen de scopes die de integratie gebruikt.

• Minimale scope. Een dashboard dat alleen vorderingen leest, heeft een leesscope nodig, geen schrijfscope. Lezen en schrijven zijn afzonderlijke rechten.
• Eén sleutel per integratie. Zodat er één kan worden ingetrokken zonder de andere te breken, en zodat de audittrail vermeldt welk systeem wat heeft gedaan.
• Testsleutels in test, live-sleutels in productie. Het voorvoegsel van de sleutel moet de omgeving in een logregel meteen duidelijk maken.
• Rotatie. Een aanbieder die alleen een hash van de sleutel opslaat, kan hem u niet opnieuw tonen — en dat is het juiste ontwerp. Plan rotatie vanaf het begin: geef de nieuwe sleutel uit, schakel over, trek de oude in.
• Webhookgeheimen zijn ook sleutels. Dezelfde opslag, dezelfde rotatie.

De MCP-specificatie voegt een punt over assistenten toe: "Hosts must obtain explicit user consent before invoking any tool", en tools "represent arbitrary code execution and must be treated with appropriate caution". Een MCP-server voor een boekhoudkundig grootboek zou dus leesacties en voorbereiding moeten aanbieden, geen onomkeerbare handelingen, en de persoon achter het toetsenbord blijft verantwoordelijk.

Hoe KRONENWERK dit aanpakt

KRONENWERK biedt alle vier de wegen; de API, webhooks, MCP-server en integratiecatalogus maken deel uit van het Enterprise-plan (zie abonnementen). Ondersteund met beperkingen

• API. https://kronenwerk.org/api/extern/v1, Bearer-API-sleutel met voorvoegsel greif_live_ of greif_test_, scopes zoals customers:write, invoices:write, transactions:write en reports:read. Endpoints voor klanten (GET/POST /customers), facturen (GET /invoices, POST /invoices/drafts), transacties (GET/POST /transactions) en GET /reports/outstanding. Eén onderneming per sleutel; GET /me noemt ze. KRONENWERK slaat alleen een hash van een sleutel op; sleutels worden op het ontwikkelaarsscherm ingetrokken of geroteerd.
• Idempotentie. Idempotency-Key is verplicht bij elke POST. Dezelfde sleutel en body: hetzelfde record komt terug; dezelfde sleutel en een andere body: geweigerd; sleutels blijven 24 uur geldig. Details op idempotentie.
• Webhooks. Gebeurtenissen invoice.issued, invoice.paid, invoice.cancelled, purchase.recorded, payment.recorded. Elke levering bevat KRONENWERK-Signature (t=<unix seconds>,v1=<hex HMAC-SHA256 over t.raw_body>, tolerantie van 5 minuten), KRONENWERK-Event-Id, KRONENWERK-Event, KRONENWERK-Delivery, KRONENWERK-Attempt en een Idempotency-Key voor deduplicatie. Alleen HTTPS, herhaalde pogingen tot de levering is aanvaard, redirects worden niet gevolgd. Zie webhooks.
• MCP. Een server op /api/extern/mcp (Streamable HTTP, dezelfde sleutel) met leestools zoals list_receivables en get_profit_and_loss, en concepttools create_invoice_draft, create_transaction, add_transaction_note. Geen enkele tool reikt een factuur uit, verstuurt e-mail, verplaatst geld of wijzigt instellingen.
• Rate limit. Een budget van 240 verzoeken per sleutel, dat continu wordt aangevuld (ongeveer twee per seconde); 429 met Retry-After bij overschrijding.

POST /api/extern/v1/customers HTTP/1.1
Host: kronenwerk.org
Authorization: Bearer greif_test_…
Idempotency-Key: 6f1c2a8e-4b3d-4a21-9d77-0c5e1f9b2a44
Content-Type: application/json

{"name": "Example SRL", "country": "BE", "vatId": "BE0123456789", "email": "ap@example.be"}

Een uitgewerkt voorbeeld van de drie stromen vindt u op een SaaS koppelen aan de boekhouding; het volledige aanbod wordt beschreven op de pagina over de boekhoud-API en in de referentie.