e-Boekhouden API koppelen aan je webshop.

e-Boekhouden.nl is online boekhoudsoftware uit Purmerend, veel gebruikt door zzp’ers, kleine bedrijven, verenigingen en stichtingen. Facturen, bankmutaties, btw-aangifte, relaties en artikelen zitten erin, en voor verenigingen ook een ledenadministratie.

Dat laatste is een verschil met de meeste pakketten en het is voor een website soms precies de reden om te koppelen: een vereniging die haar leden in e-Boekhouden bijhoudt, wil dat een inschrijving op de site daar terechtkomt en niet in een los formulier.

De REST API is openbaar beschreven. Je maakt in de instellingen van je account een API-token aan, en daarmee vraag je een kortlevend sessietoken op. Dat sessietoken gaat mee in de Authorization-header bij elke aanroep.

Wat er te benaderen valt: relaties, artikelen en artikelgroepen, facturen en factuursjablonen, mutaties, het grootboek met saldi, kostenplaatsen, eenheden en leden. Genoeg voor een webshopkoppeling en ruim genoeg voor een ledenadministratie.

De oudere SOAP-koppeling bestaat nog en werkt met een gebruikersnaam en twee beveiligingscodes. Voor nieuw werk gebruiken wij de REST-variant.

De stappen:

1. Jij maakt in de instellingen van je account een API-token aan en zet het direct in een wachtwoordkluis.
2. De koppeling stuurt dat token naar /v1/session, samen met een vaste naam voor de bron. Die naam helpt e-Boekhouden bij het uitzoeken van een probleem als je contact opneemt. Het antwoord geeft het sessietoken en het aantal seconden dat het geldig is.
3. Werk je met meer dan één administratie, dan kiest de koppeling eerst de juiste. /v1/administration/linked geeft de administraties die gekoppeld zijn aan de administratie waarin het API-token is aangemaakt. Is er in de sessie geen administratie geopend, dan geeft de API daar een foutmelding over.
4. Na afloop sluit de koppeling de sessie af met een DELETE op hetzelfde adres, zodat er geen geldige sessies blijven liggen.

Naar e-Boekhouden gaat de omzet: per bestelling een factuur, of per dag een verzamelboeking per kanaal. Welke van de twee hangt af van je aantallen en van wat je boekhouder wil zien.

De klant wordt een relatie. Spreek ook hier af hoe je een bestaande relatie herkent, anders staat dezelfde persoon er na een maand vijf keer in. Werk je met Moneybird, dan bouwen we dezelfde stroom als koppeling met Moneybird.

Naar je site komen de artikelen en prijzen. Voor een webshop die zijn assortiment daar bijhoudt scheelt dat een tweede lijst; voor een vereniging is de interessantere kant juist de andere, namelijk een inschrijving die als lid wordt aangemaakt.

En er is een kant die vaak wordt vergeten: de API geeft ook de openstaande facturen. Daarmee kan een klant of lid in een eigen account op je site zien wat er nog betaald moet worden.

Een lijst geeft standaard 100 regels en hoogstens 2000 per aanroep; met offset haal je de volgende op. Per parameter past één filter, dus een zoekvraag met meerdere voorwaarden op hetzelfde veld splits je op. Datums gaan in het formaat JJJJ-MM-DD.

De meeste fouten zitten in de administratie en niet in de techniek. Een factuurnummer dat al bestaat wordt geweigerd, dus de nummering van de webshop en die van e-Boekhouden mogen elkaar niet kruisen. Een btw-code moet passen bij het land waar het bedrijf is gevestigd, en de oude code voor het lage tarief van 6% heeft een einddatum van 1 januari 2019; voor 9% is er een eigen code.

En een account in de proefperiode heeft een grens voor de boekhoudmodule en de factuurmodule. Tijdens een test op zo’n account kan de koppeling daardoor ineens worden geweigerd, terwijl er niets mis is met de code.

Dit is de toepassing die het vaakst wordt vergeten. Een vereniging heeft een site met een inschrijfformulier, en een penningmeester die de leden in e-Boekhouden bijhoudt. Zonder koppeling typt die penningmeester elke inschrijving over, en gaat het mis op het moment dat iemand verhuist of opzegt.

Met de koppeling wordt een inschrijving op de site meteen een lid in de administratie, en kan de contributiefactuur daaruit volgen.

Wat wij daarbij aanraden: houd de site dom en de administratie slim. De site verzamelt en toont, de administratie bepaalt wie lid is en wat er betaald moet worden. Dat scheelt discussies over welk systeem gelijk heeft.

Op WordPress met WooCommerce stuurt een taak op de server de betaalde bestellingen door, per order of als dagtotaal, en houdt hij bij welke al in de administratie staan. Voor een vereniging zit de koppeling achter het inschrijfformulier: een nieuw lid komt via de API in de ledenadministratie, en de penningmeester ziet het daar verschijnen.

Bouwen we de site op maat, in Next.js met Payload als beheer, dan loopt hetzelfde via een eigen serverroute. Dat is de keuze als de site meer doet dan verkopen, zoals een ledenomgeving waarin leden hun gegevens en openstaande contributie zien.

Werkt je boekhouder liever in een ander pakket, dan werkt een integratie met SnelStart volgens hetzelfde idee. Over het bouwen van de site of ledenomgeving zelf gaat Design & Development.