e-Boekhouden API uitgelegd: SOAP of REST v1

e-Boekhouden.nl heeft twee werkende API's tegelijk: de oude SOAP-API op soap.e-boekhouden.nl en de nieuwe REST-API v1 op api.e-boekhouden.nl. Beide zijn live, en in de officiële SOAP-handleiding (versie 5.7) staat geen enkele einddatum of uitfaseringsmelding (e-Boekhouden, Handleiding Soap 5.7{target="_blank" rel="noopener noreferrer"}).

Dat maakt de keuze tussen die twee een ontwerpbeslissing, geen deadline — precies andersom dan bij Nmbrs, waar de SOAP-API op 1 maart 2027 stopt.

Hieronder de beslisinformatie voor wie daadwerkelijk bouwt: authenticatie, de endpoints die ertoe doen, de harde limieten, en de velden waarop boekingen in productie stuklopen. Waar dit artikel op de techniek inzoomt, behandelt onze gids over maatwerk software de bouw- en kostenkant.

Waarom er twee API's naast elkaar staan#

De SOAP-API stamt uit het tijdperk waarin een koppeling een sessie opende, wat calls deed en weer afsloot. De REST-API v1 doet hetzelfde werk met JSON, een API-token en filterbare querystrings.

Het praktische verschil zit in wat ze kunnen, niet in het protocol. De REST-API heeft resources die SOAP niet heeft: e-mailsjablonen, factuursjablonen en leden, plus schrijftoegang op producten en kostenplaatsen waar SOAP die alleen kan uitlezen (e-Boekhouden API-documentatie{target="_blank" rel="noopener noreferrer"}).

Andersom heeft SOAP één functie die REST mist: AutoLogin, waarmee je een gebruiker rechtstreeks de webomgeving in stuurt.

Onze vuistregel bij nieuwbouw: REST, tenzij je een bestaande SOAP-koppeling onderhoudt die werkt. Een werkende integratie herbouwen zonder functionele aanleiding is kosten maken zonder opbrengst.

Van token naar sessie: de REST-authenticatie in één call#

De REST-API gebruikt geen OAuth. Je maakt in de accountinstellingen een API-token aan, wisselt dat token in voor een kortlevend sessietoken, en stuurt dát token mee als Authorization-header.

curl -X POST https://api.e-boekhouden.nl/v1/session \
  -H "Content-Type: application/json" \
  -d '{ "accessToken": "JOUW_API_TOKEN", "source": "CleverTech" }'

Het veld source is verplicht en mag maximaal tien tekens lang zijn, met alleen letters, cijfers, underscores en spaties. Een waarde buiten dat patroon levert foutcode API_SESSION_002 op.

Support gebruikt die code om jouw verkeer terug te vinden, dus kies iets herkenbaars.

Daarna gaat het sessietoken mee bij elke call:

curl "https://api.e-boekhouden.nl/v1/relation?limit=100&offset=0" \
  -H "Authorization: SESSIETOKEN"

Sluit de sessie af met DELETE /v1/session; dat trekt het sessietoken in. Krijg je API_SESSION_004 terug, dan is je API-token verlopen en moet je een nieuw token aanmaken.

Eén verschil met Exact Online is hier belangrijk. Waar de Exact Online API elke call naar een division routeert, hangt een e-Boekhouden-token aan de administratie waarin het is aangemaakt.

Meerdere administraties bedienen betekent dus meerdere tokens — behalve voor accountants, die via GET /v1/administration de beheerde administraties opvragen.

De SOAP-variant, en de valkuil die niemand verwacht#

SOAP werkt met OpenSession(Username, SecurityCode1, SecurityCode2), geeft een sessie-ID terug, en verwacht dat ID plus SecurityCode2 bij elke volgende call. Die gegevens vind je onder Beheer > Instellingen > API/SOAP.

De valkuil staat in de FAQ van de handleiding zelf: beveiligingscode 1 verandert zodra het wachtwoord van het account wordt aangepast. Een gebruiker die netjes zijn wachtwoord roteert, legt daarmee de koppeling stil.

Dit is de e-Boekhouden-storing die we het vaakst terugzien, en hij is niet te onderscheiden van een ongeldige login. Bouw je op SOAP, monitor dan expliciet op foutcode E001.1 ("verkeerde sessiegegevens").

De endpoints die er in de praktijk toe doen#

REST v1 kent twaalf resources, verdeeld over 24 endpoints. Vier daarvan dragen vrijwel elke koppeling.

Voor debiteurenbewaking is er /v1/mutation/invoice/outstanding: alle openstaande facturen, filterbaar op debiteur of crediteur. Dat scheelt het zelf reconstrueren van de openstaande post uit mutaties, de rekensom waar in maatwerkkoppelingen de meeste afwijkingen ontstaan.

Bij de zoek-endpoints werkt paginering overal hetzelfde: limit staat standaard op 100 en mag tussen 1 en 2000 liggen, offset begint op 0. Een limit daarbuiten geeft PAGE_001 terug.

Mutatiesoorten: het veld waarop boekingen stuklopen#

type is een code van 1 tot en met 7, als string meegestuurd. De betekenis bepaalt wat er verder verplicht is.

Twee regels uit de specificatie kosten de meeste debugtijd. De eerste: bij de typen 1, 2, 5 en 6 mag het grootboek op een regel niet in de categorie FIN, CRED of DEB vallen, terwijl bij type 7 elk grootboek mag.

Doe je dat toch, dan volgt MUT_106.

De tweede: bij de typen 3 en 4 is invoiceNumber op de regel verplicht, want dat veld koppelt de betaling aan de juiste factuur. Afletteren is bij e-Boekhouden dus geen apart endpoint maar een regelveld.

{
  "type": "2",
  "date": "2026-10-28",
  "ledgerId": 42,
  "invoiceNumber": "F-2026-0042",
  "relationId": 5012,
  "inExVat": "EX",
  "description": "Webshoporder 8841",
  "rows": [
    { "ledgerId": 57, "vatCode": "HOOG_VERK_21", "amount": 250.00 }
  ]
}

Verwar ledgerId niet met je grootboekcode. De API adresseert grootboekrekeningen op hun eigen id, terwijl code — het nummer dat je in je rekeningschema ziet — een apart veld is.

Haal die mapping één keer op via GET /v1/ledger en cache hem.

Let op description: dat veld mag maximaal vijftig tekens lang zijn, net als invoiceNumber. Een omschrijving die je uit een orderregel samenstelt, past daar zelden in, dus kort hem in je eigen code af op een betekenisvol punt.

Een mutatie mag maximaal 500 regels bevatten (MUT_101 daarboven), en dezelfde grens geldt voor factuurregels. Voor een maandelijkse verzamelboeking is dat ruim, voor een jaarimport in één call niet.

Btw-codes: zestien in de enum, twintig in de tabel#

De btw-code op een regel is een string, geen percentage. Voor Nederland gelden onder meer HOOG_VERK_21 (21% verkoop), LAAG_VERK_9 (9% verkoop), VERL_VERK (verlegd 21%), BI_EU_VERK_D (diensten binnen de EU, 0%) en GEEN.

Hier zit een subtiliteit die je alleen ziet als je de documentatie helemaal leest. De formele enum in de API-specificatie telt zestien codes, terwijl de NL-tabel in diezelfde documentatie er twintig noemt.

Het verschil bestaat uit vier codes, waarvan er drie een afkapdatum van 1 januari 2019 dragen: LAAG_VERK, LAAG_INK en VERL_INK_L. Dat zijn de oude 6%-codes: boek je met een datum vóór 2019, dan geldt 6%, daarna 9%.

Voor een historische import is dat precies het verschil tussen een kloppende en een niet-kloppende btw-aangifte.

Twee codes hebben een eigen regel. AFW en AFW_VERK betekenen "afwijkend tarief" en werken alleen samen met een expliciet vatAmount op de regel, want de API rekent dan niets uit.

Gebruik dat niet als vangnet voor codes die je niet kent; je haalt er de btw-controle mee onderuit.

Het veld inExVat bepaalt of de bedragen inclusief (IN) of exclusief (EX) btw zijn. Eén verkeerde waarde in een import van duizend regels is 21% verschil over de hele boeking.

Limieten: wat er wél en niet gedocumenteerd is#

Dit is het punt waarop e-Boekhouden afwijkt van wat je van een moderne API verwacht.

De SOAP-limieten staan zwart op wit in de handleiding. Voor REST publiceert e-Boekhouden geen callplafond, en de specificatie noemt geen HTTP 429 bij de mogelijke antwoorden.

Behandel dat niet als "geen limiet" maar als "onbekende limiet": bouw hoe dan ook backoff en retry in, en meet je eigen callvolume. Een koppeling die onder een ongedocumenteerde grens duikt, doet dat stil.

Geen webhooks, dus je pollt#

De SOAP-handleiding is er ondubbelzinnig over: e-Boekhouden kan geen URL's aanroepen wanneer er iets in de boekhouding verandert, de actie start altijd vanuit een call naar de API. De REST-specificatie bevat evenmin webhook-endpoints.

Dat heeft directe gevolgen voor je architectuur. Waar een Exact-koppeling zich op gebeurtenissen kan abonneren, moet een e-Boekhouden-koppeling periodiek kijken of er iets nieuws is.

Plan dat interval op wat het proces echt nodig heeft: betalingen ophalen elk kwartier is bijna altijd genoeg, voorraadstanden elke minuut vrijwel nooit.

Dezelfde afweging speelt bij Moneybird, waar de API wél webhooks kent — als je nog vrij bent in je pakketkeuze, is dat een argument dat pas ná de go-live gaat tellen.

Waar AI het overtypen stopt: vóór de koppeling#

Een API verplaatst gestructureerde data. Het werk dat in het MKB de meeste uren kost, zit ervóór: een PDF-factuur die iemand leest en overtypt.

Daar zit de winst, en die staat los van de vraag of je SOAP of REST kiest.

Twee toepassingen die we in koppelingen inbouwen:

• Factuurherkenning vóór de boeking. Een taalmodel leest de inkoopfactuur en levert leverancier, factuurnummer, datum, bedragen en btw-uitsplitsing als JSON — precies de velden die POST /v1/mutation verwacht.
• Grootboek- en btw-voorstel bij de mutatie. Op basis van eerdere boekingen van dezelfde relatie stelt het model ledgerId en vatCode voor, met een zekerheidsscore.

De harde eis in beide gevallen: een voorstel is geen boeking. Onder een ingestelde drempel gaat de regel naar een goedkeuringsscherm in plaats van naar de API.

Wie dat weglaat, automatiseert fouten sneller dan een mens ze kan vinden. Hoe wij die laag bouwen, staat op onze pagina over software met AI.

Wanneer een standaardkoppeling volstaat#

Voor de gangbare stromen hoef je niets te bouwen. e-Boekhouden heeft een koppelingenoverzicht met kant-en-klare integraties voor webshops, banken, kassasystemen, urenregistratie, salaris- en rapportagesoftware (e-Boekhouden, Koppelingen{target="_blank" rel="noopener noreferrer"}).

Draait je webshop op een gangbaar platform en is je btw standaard, dan is dat de goedkoopste route.

Maatwerk wordt pas verdedigbaar bij een van deze vier:

• Je bronsysteem staat niet in het koppelingenoverzicht, bijvoorbeeld een eigen ordersysteem of een branchepakket.
• Je grootboek- of kostenplaatsmapping wijkt per productgroep, klantgroep of project af.
• Je hebt meerdere administraties en dus meerdere tokens, met logica die bepaalt wat waar hoort.
• Je wil documentherkenning of classificatie vóór de boeking, zoals hierboven.

Een standaardstroom van webshop naar boekhouding bouwen we voor €2.000 tot €5.000 eenmalig plus €150 tot €350 per maand beheer; de volledige opbouw en wat daar technisch in zit, staat op boekhoudkoppeling en ERP-integratie. Gaat het om meer dan twee systemen, dan wil je een koppeling tussen systemen laten maken.

Twijfel je aan welke kant van die streep jouw scenario valt? Leg het ons kort voor — je krijgt een eerlijk antwoord over standaard versus maatwerk, inclusief kostenindicatie.