Bouwen op een Europese boekhoud-API: btw, e-facturen, AVG, grootboek

Een boekhoud-API voor Europa moet acht dingen goed doen die een API voor één land kan negeren: btw die afhangt van het land en de status van beide partijen, btw-verlegging en de bijbehorende factuurvermelding, controle van btw-nummers via VIES, gestructureerde e-facturen in het nationale formaat, AVG-verplichtingen (GDPR) voor klantgegevens, idempotente schrijfacties met ondertekende webhooks, een echt dubbel grootboek en boekhouden in meerdere valuta's. Deze gids licht elke vereiste toe en laat zien hoe de API van KRONENWERK erop aansluit — inclusief waar de API ophoudt: ze maakt klanten, concepten en transacties aan en leest de boeken; ze reikt geen facturen uit, boekt geen journaalposten en dient geen aangiften in.

Btw in meerdere landen is een functie van feiten, niet van een tariefveld

In de EU volgt de btw-behandeling van een verkoop uit het land van de verkoper, het land van de koper, de vraag of de koper een onderneming of een consument is, en de vraag of het om goederen of diensten gaat. Richtlijn 2006/112/EG bepaalt het kader: voor B2B-diensten is de plaats van de dienst daar waar de afnemer gevestigd is (artikel 44); wanneer de dienstverrichter daar niet gevestigd is, voldoet de afnemer de btw via de verleggingsregeling (artikel 196); intracommunautaire leveringen van goederen aan een btw-plichtige onderneming in een andere lidstaat zijn vrijgesteld wanneer aan de voorwaarden is voldaan (artikel 138); en artikel 226 somt op wat een factuur moet vermelden, waaronder de woorden "Btw verlegd" waar dat van toepassing is. Tarieven, drempels en vrijstellingen zijn nationaal.

Het gevolg voor een API-ontwerp is dat een aanroeper nooit om een btw-tarief op zich gevraagd zou moeten worden. Een goed ontworpen Europese API neemt de feiten en geeft een oordeel terug — normaal tarief, nultarief, vrijgesteld, verlegd, buiten het toepassingsgebied — met het tarief en de factuurvermelding die daaruit volgen, en weigert te gokken wanneer een feit ontbreekt.

KRONENWERK: elke factuur draagt een fiscaal oordeel dat is afgeleid uit de feiten van de transactie (land van de verkoper, land van de koper, onderneming of consument, aard van de prestatie). Het oordeel is een van normaal tarief, nultarief, vrijgesteld, verlegd, buiten het toepassingsgebied, of "invoer vereist" / "professionele bevestiging vereist" wanneer de feiten het niet beslissen. Het wordt bij de factuur opgeslagen en nooit later uit stamgegevens afgeleid. Via de API is het oordeel geen veld dat u instelt: een concept dat met POST /invoices/drafts wordt aangemaakt, erft het rechtsgebied van de verkoper, en het oordeel wordt vastgelegd wanneer een persoon de factuur in het product uitreikt. Of een specifieke prestatie voor een vrijstelling in aanmerking komt, is een vraag voor een professional, en het product zegt dat ook in plaats van zelf te beslissen.

Verlegging vereist beide btw-nummers en de juiste woorden

Een factuur met verlegde btw verschilt op drie punten van een binnenlandse: er wordt geen btw aangerekend, het btw-nummer van de koper moet naast dat van de verkoper vermeld staan, en het document moet vermelden dat de koper de belasting voldoet. In EN 16931-termen is de btw-categorie AE, is een vrijstellingsreden verplicht, en dwingen de regels BR-AE-01 tot en met BR-AE-10 de uitsplitsing en de identificaties af. Een gestructureerde e-factuur met de verkeerde categorie wordt door de validator van de ontvanger geweigerd; een pdf met de verkeerde vermelding is een nalevingsprobleem voor beide partijen.

KRONENWERK: wanneer het oordeel verlegging is, wordt de factuur uitgereikt met 0 % btw, categorie AE in het gestructureerde document, het btw-nummer van de koper en de wettelijke vermelding in de taal van het document. De API leest het resultaat via GET /invoices/{number}, waar tax nul is en net gelijk is aan gross. Er is geen API-parameter om verlegging af te dwingen; ze volgt uit het land en het btw-nummer van de klant, die u kunt meegeven met POST /customers:

POST https://kronenwerk.org/api/extern/v1/customers
Authorization: Bearer greif_test_XXXXXXXXXXXXXXXX
Idempotency-Key: 6f1c2f4e-3c0a-4b8f-9d61-2a7c1c2e9b10
Content-Type: application/json

{
  "name": "Atelier Dupont SARL",
  "email": "compta@example.fr",
  "street": "12 rue de la Paix",
  "postalCode": "75002",
  "city": "Paris",
  "country": "FR",
  "vatId": "FR12345678901",
  "currency": "EUR"
}

VIES-controle, op het juiste moment

VIES is het VAT Information Exchange System van de Commissie. De webservice checkVat neemt een landcode en een nummer en geeft terug of het nummer op de datum van het verzoek geldig is, plus de naam en het adres waar de lidstaat die vrijgeeft; checkVatApprox vergelijkt daarnaast de gegevens van de handelaar en geeft een requestIdentifier terug — het raadplegingsnummer dat de controle documenteert. De Commissie biedt ook een REST-interface met dezelfde semantiek. De systemen van de lidstaten zijn soms niet beschikbaar; in dat geval meldt de dienst een status zoals MS_UNAVAILABLE in plaats van een geldigheid. De dienst bestaat voor intracommunautaire transacties op grond van Verordening (EG) nr. 904/2010 van de Raad.

Daaruit volgen twee ontwerpregels. Controleer op het moment dat de beslissing ervan afhangt — de uitreiking — en niet alleen bij het aanmaken van de klant, want registraties vervallen. En sla het resultaat bij het document op, want de vraag later is "was het geldig toen wij factureerden", niet "is het vandaag geldig".

KRONENWERK: het btw-nummer van een koper wordt bij de uitreiking tegen VIES gecontroleerd en het resultaat wordt samen met het oordeel bij de factuur opgeslagen. Als VIES of het systeem van de lidstaat niet antwoordt, wordt de controle op de factuur vastgelegd als niet bereikbaar en bij de uitreiking als melding getoond; een storing wordt nooit als een geldig resultaat behandeld en wordt niet gecachet, terwijl een echt resultaat één dag wordt onthouden zodat het register niet bij elke toetsaanslag wordt bevraagd. De gratis btw-nummercontrole voert dezelfde controle uit op één nummer zonder het op te slaan. De API biedt geen eigen VIES-endpoint; ze toont het opgeslagen resultaat op de uitgereikte factuur.

Gestructureerde e-facturen zijn nationaal, niet Europees

De EU-richtlijn inzake elektronische facturering (2014/55/EU) verplicht overheidsinstanties om EN 16931-facturen te ontvangen; B2B-verplichtingen zijn nationaal en verschillen in formaat, netwerk en timing. Duitsland verplicht ondernemingen gestructureerde facturen te ontvangen en voert het uitreiken gefaseerd in (XRechnung of ZUGFeRD); België verplicht Peppol BIS Billing 3.0 via het Peppol-netwerk voor B2B vanaf 1 januari 2026; Polen laat facturen via KSeF in FA(3) passeren; Frankrijk werkt met erkende platformen (plateformes agréées) met Factur-X als een van de aanvaarde formaten. Canada en de Verenigde Staten kennen geen verplichting voor gestructureerde facturen. Zie de tijdlijn en de formaten.

Voor een API betekent dit dat het formaat een eigenschap is van het land van de verkoper en het kanaal van de koper, bepaald bij de uitreiking, en dat het document met de nationale artefacten (de CEN-Schematron plus de profielregels) gevalideerd moet worden voordat het bestaat. Een API die willekeurige XML van aanroepers zou aanvaarden, zou die toch moeten valideren en zou het moeilijkste deel van het probleem naar elke aanroeper verschuiven.

KRONENWERK: het gestructureerde bestand wordt bij de uitreiking gegenereerd en gevalideerd voor het land van de verkoper — XRechnung en ZUGFeRD (KoSIT-Schematron, tegengecontroleerd met Mustang), Factur-X, Peppol BIS UBL, FA(3). De API maakt het concept aan; het formaat, de validatie en de verzending zijn zaak van het product. Dit is de grootste eerlijke kloof voor ontwikkelaars die verwachtten een factuur te POSTen en XML terug te krijgen: er is geen "issue"-endpoint en geen XML in de API. De pagina over de e-factuur-API beschrijft precies wat beschikbaar is, en de EN 16931-ontwikkelaarsgids behandelt de regels als u zelf documenten genereert.

AVG: klantgegevens zijn persoonsgegevens

De naam, het adres, het e-mailadres en het btw-nummer van een eenmanszaak zijn persoonsgegevens, dus een boekhoudintegratie is een verwerkingsactiviteit. De AVG (GDPR) vereist een overeenkomst tussen verwerkingsverantwoordelijke en verwerker waarin onderwerp, duur, aard, doel en gegevenscategorieën worden vastgelegd (artikel 28, lid 3); een register van verwerkingsactiviteiten (artikel 30); beveiliging die past bij het risico, inclusief versleuteling waar passend (artikel 32); en, voor doorgiften buiten de EU/EER, een geldig doorgiftemechanisme (hoofdstuk V, vanaf artikel 44). Wat een ontwikkelaar van een boekhoudaanbieder nodig heeft, is dus concreet: een verwerkersovereenkomst, een verklaring over waar de gegevens worden opgeslagen en welke subverwerkers worden gebruikt, en een manier om de gegevens van een betrokkene te verwijderen of te exporteren.

KRONENWERK: de verwerkingsvoorwaarden en hostingafspraken staan op de privacypagina en de beveiligingspagina; lees die en niet deze gids voor de bindende verklaring. KRONENWERK bezit geen beveiligingscertificering en maakt geen aanspraak op "AVG-gecertificeerd", omdat een dergelijke certificering niet bestaat. Via de API zijn sleutels zo afgebakend dat een integratie die alleen reports:read nodig heeft, nooit klantrecords ontvangt, en elke sleutel is aan één onderneming gebonden.

Idempotentie en webhooks

Netwerkfouten maken elke schrijfactie dubbelzinnig: een POST die door een time-out is afgebroken, kan het record al dan niet hebben aangemaakt. Het standaardantwoord is een idempotentiesleutel — een door de client gekozen unieke waarde per logische bewerking die de server samen met het resultaat opslaat, zodat een nieuwe poging met dezelfde sleutel hetzelfde resultaat teruggeeft in plaats van een duplicaat. Aan de uitgaande kant moeten webhooks ondertekend zijn zodat de ontvanger de herkomst kan controleren, een gebeurtenis-ID dragen zodat duplicaten kunnen worden weggegooid, en bij mislukking opnieuw worden geprobeerd.

KRONENWERK: elke POST vereist een Idempotency-Key-header; een herhaling met dezelfde sleutel en body geeft het oorspronkelijke resultaat terug, en een herhaling met een andere body antwoordt met 409 IDEMPOTENZ_KONFLIKT. Fouten zijn JSON met een machinecode en een zin: UNAUTHENTICATED, ANFRAGE, PLAN_ERFORDERLICH, KEINE_BERECHTIGUNG, NICHT_GEFUNDEN, IDEMPOTENZ_KONFLIKT, FALSCHER_ZUSTAND, ABGELEHNT, ZU_VIELE_ANFRAGEN. De rate limit is een budget van 240 verzoeken per sleutel dat continu wordt aangevuld met ongeveer twee per seconde, beantwoord met 429 en Retry-After. Uitgaande webhooks zijn ondertekend (KRONENWERK-Signature) en dragen KRONENWERK-Event-Id, KRONENWERK-Event, KRONENWERK-Delivery, KRONENWERK-Attempt en een Idempotency-Key; de gebeurtenissen zijn invoice.issued, invoice.paid, invoice.cancelled, purchase.recorded en payment.recorded; de levering verloopt uitsluitend via HTTPS, wordt opnieuw geprobeerd en volgt nooit redirects. Details: idempotentie, webhooks, fouten, limieten.

Het grootboek is dubbel, en de API leest het

Een boekhoudsysteem is geen lijst van facturen. Elke factuur, betaling en uitgave levert sluitende journaalposten op — debet vorderingen, credit omzet en verschuldigde btw; debet bank, credit vorderingen — en de rapporten zijn sommen over rekeningen, niet over documenten. Een API die op zo'n grootboek is gebouwd, kan beloven dat "openstaande vorderingen" aansluit bij de rekening handelsdebiteuren, en dat een winst-en-verliescijfer pas definitief is wanneer de onderliggende periodes zijn afgesloten. Een API die op een documentenlijst is gebouwd, kan dat niet.

KRONENWERK: het grootboek is dubbel, met periodes die worden afgesloten. De REST-API leest de openstaande posten met GET /reports/outstanding; de MCP-server biedt daarnaast get_profit_and_loss, get_balance_sheet, list_receivables en list_payables uit hetzelfde grootboek, met een is_final-vlag op de winst-en-verliesrekening. Niets in de API boekt een journaalpost; posten ontstaan uit handelingen die een persoon in het product verricht — uitreiken, een betaling registreren, een inkoopfactuur goedkeuren. Een antwoord van het rapport openstaande posten, verkort:

{
  "asOf": "2026-09-03",
  "currency": "EUR",
  "booksOpen": true,
  "receivables": { "outstanding": { "minor": 1284050, "currency": "EUR" },
                   "due":         { "minor": 412000,  "currency": "EUR" },
                   "overdue":     { "minor": 105910,  "currency": "EUR" },
                   "count": 9 },
  "payables":    { "outstanding": { "minor": 336000,  "currency": "EUR" },
                   "due":         { "minor": 0,       "currency": "EUR" },
                   "overdue":     { "minor": 0,       "currency": "EUR" },
                   "count": 3 }
}

Valuta: kleinste eenheden, één boekvaluta, opgeslagen koersen

Bedragen als drijvendekommagetallen verliezen centen; bedragen als opgemaakte tekst zijn dubbelzinnig over locales heen ("1.059,10" tegenover "1,059.10"). De robuuste weergave is een geheel aantal kleinste eenheden met een ISO 4217-code. Een onderneming met meerdere valuta's factureert in de valuta van de klant, voert haar boeken in één boekvaluta en moet de op elk document gebruikte koers opslaan, zodat latere rapporten niet meebewegen met de koers van vandaag.

KRONENWERK: elk bedrag op de API is {"minor": 105910, "currency": "EUR"}, nooit een decimaal getal of een tekst. Een onderneming heeft één boekvaluta; klanten kunnen een voorkeursvaluta voor facturatie hebben; de cijfers die op een uitgereikte factuur zijn bevroren, zijn wat de API teruggeeft, niet de stamgegevens van vandaag. Opstellingen met meerdere ondernemingen gebruiken één sleutel per onderneming. Zie meerdere ondernemingen, meerdere valuta's en de productpagina over meerdere ondernemingen.

Hoe KRONENWERK dit aanpakt

Ondersteund met beperkingen De publieke API op https://kronenwerk.org/api/extern/v1 omvat GET /me, klanten (GET, GET /{id}, POST), facturen (GET, GET /{number}, POST /invoices/drafts), transacties (GET, POST) en GET /reports/outstanding, met afgebakende sleutels, verplichte idempotentie bij schrijfacties, een verzoekbudget per sleutel, JSON-fouten met machinecodes, ondertekende webhooks en een MCP-server op dezelfde sleutel. De beperkingen zijn bewust en u moet er rekening mee houden: de API maakt alleen concepten en transacties aan — ze reikt geen facturen uit, produceert of aanvaardt geen gestructureerde XML, boekt geen grootboekposten, registreert geen betalingen, voert geen VIES-controles op verzoek uit en dient geen belasting in of draagt ze af. Die handelingen gebeuren in het product, waar de landmodules ze valideren, en de API en webhooks rapporteren de resultaten. Dit alles maakt deel uit van het Enterprise-plan; zie prijzen, het overzicht van de boekhoud-API, de snelstart en de gids voor de SaaS-koppeling.