Skip to content
Work Expertise Services CV Portfolio Integrations Laravel packages Blog Sign in Get in touch

Exact Online API

Exact Online is de plek waar de cijfers uiteindelijk moeten staan. Hieronder staat wat ik erop gebouwd heb: aanmelden met een Exact-account, verkoopfacturen die in twee richtingen gelijklopen, en elke regel op de grootboekrekening waar ze hoort. Onderaan de package die eruit voortkwam.

Wat Exact Online is

Exact Online is het boekhoudpakket waar in Belgie en Nederland een groot deel van de boekhouders in werkt. Dagboeken, grootboek, btw-aangifte, relaties, openstaande posten en de koppeling met de bank zitten erin, en alles staat per administratie: een vennootschap is een administratie, en een kantoor beheert er honderden naast elkaar.

Er zit een api op, met oauth ervoor. Daar begint mijn werk. Exact weet wat er geboekt is, de applicatie van de klant weet wat er verkocht is, en ertussen zat tot dan het overtikken: een maandlijst uitdraaien, een boeking per hand inbrengen, en in maart uitzoeken waarom de omzet op de verkeerde rekening staat.

Aanmelden met een Exact-account

Geen api-sleutel die per mail doorgegeven wordt, maar oauth: de klant geeft zelf toestemming en trekt ze zelf weer in. Zes stukken die daarna het werk zijn.

De knop en de toestemming

De klant meldt zich aan bij Exact zelf en geeft daar toestemming. Ik zie zijn wachtwoord niet, en er gaat geen sleutel per mail rond die niemand ooit nog intrekt. Terug in het eigen scherm staat de koppeling er, met de naam van de administratie erbij.

Het land staat in het adres

Exact draait per land op een eigen domein: start.exactonline.be, .nl, .de, .co.uk. Wie in Nederland boekt, meldt zich aan op het Nederlandse adres en spreekt daarna dezelfde api aan. Dat adres is dus een instelling en geen regel in de code.

De administratie komt uit Me

Meteen na de aanmelding vraagt de applicatie op wie er binnenkwam en in welke administratie hij zit. Dat nummer staat daarna in elke url. Een klant met drie vennootschappen kiest in het eigen scherm welke administratie aan welke webshop hangt.

Een token van tien minuten

De toegang tot de api gaat tien minuten mee, de verversing dertig dagen. Verversen gebeurt achter de schermen en voor het verzoek vertrekt, niet nadat Exact al een 401 teruggaf.

De verversing is eenmalig

Elke verversing levert een nieuwe op en maakt de vorige ongeldig. Ze wordt daarom weggeschreven in dezelfde transactie als waarin ze gebruikt wordt, met een slot erop zodat twee processen niet tegelijk beginnen. Raakt ze kwijt, dan is de koppeling dood en moet de klant opnieuw toestemming geven.

Een koppeling die niets doet, sterft

Dertig dagen stilte en de verversing vervalt. Een bouwverlof is daarvoor lang genoeg. Er loopt dus elke dag een taak die ververst, ook als er niets te boeken viel, en wie toch uitvalt krijgt een mail voor de boekhouder het merkt.

Facturen in twee richtingen

De applicatie maakt de factuur, Exact houdt de boekhouding. Zes stukken die ervoor zorgen dat beide hetzelfde zeggen, zonder dat iemand iets overtikt.

Van verkoop naar boeking

Elke verkoopfactuur uit de applicatie wordt een boeking in het verkoopdagboek van Exact, met het factuurnummer van de applicatie als eigen referentie. De applicatie nummert, Exact boekt: geen tweede reeks nummers die na een jaar uit elkaar loopt.

De klant wordt een relatie

Een boeking heeft een relatie nodig. Die wordt gezocht op een sleutel die vastligt, het relatienummer of het btw-nummer, en aangemaakt als ze er nog niet is. Nooit op naam: dezelfde bvba met en zonder punt is anders twee relaties en een openstaande post die niemand terugvindt.

Twee keer versturen is een keer boeken

Voor er geboekt wordt, kijkt de applicatie of dat factuurnummer al in Exact staat. Een taak die opnieuw loopt, een timeout die het antwoord opvreet, een klik te veel: het resultaat blijft een boeking, en niet een omzet die dubbel in de aangifte zit.

Creditnota volgt de factuur

Een creditnota is geen apart geval maar dezelfde boeking met een ander teken, op dezelfde rekeningen als de factuur die ze rechtzet. Zo blijft de omzet per rekening kloppen zonder dat iemand achteraf handmatig verschuift.

Betaald komt terug uit Exact

Afpunten gebeurt op het rekeninguittreksel, en dat gebeurt in de boekhouding. De openstaande stand komt dus terug naar de applicatie: wat daar op betaald springt, is betaald in Exact, en er vertrekt geen herinnering meer naar iemand die al overgeschreven heeft.

Ophalen op de stand, niet op de datum

Wat er sinds de vorige keer wijzigde komt binnen via de sync-endpoints van Exact, die met een teller werken in plaats van met een datum. Dat scheelt elke keer het hele bestand doorlopen, en een boeking die met terugwerkende kracht aangepast wordt, valt niet tussen twee datums door.

Uitsplitsen op grootboekrekeningen

Een factuur is voor de klant een totaal, en voor de boekhouding een rij regels die elk ergens anders thuishoren. Vier dingen bepalen waar een regel terechtkomt.

Het artikel of zijn categorie

Elk artikel hangt aan een categorie en elke categorie aan een omzetrekening. Kleding staat daardoor niet op dezelfde rekening als meubels, zonder dat iemand per factuur moet nadenken over welk nummer het wordt.

Het btw-tarief

Zes, twaalf en eenentwintig procent gaan elk naar hun eigen rekening, met de btw-code van Exact op de regel. Die code stuurt de aangifte, dus het tarief op de factuur en de code op de boeking moeten hetzelfde zeggen. Doen ze dat niet, dan vertrekt de boeking niet.

De soort regel

Omzet, verzendkosten, korting en waarborg zijn vier verschillende dingen, ook al staan ze op een blad onder elkaar. Elk krijgt zijn eigen rekening, zodat verzendkost geen omzet wordt en een korting niet stil uit de omzet verdwijnt.

Het kanaal of de vestiging

Webshop, winkel en filiaal krijgen hun eigen rekening of hun eigen kostenplaats. Daarna is de vraag wat de webshop vorige maand opbracht een rapport in Exact zelf, en geen export die iemand in een rekenblad naast de kassacijfers legt.

De tabel staat in het eigen scherm

Die vier assen komen samen in een tabel in de applicatie zelf, en niet in een reeks voorwaarden in de code. Wijzigt het rekeningschema, komt er een categorie bij of verhuist een tarief, dan past de boekhouder dat aan waar hij toch al werkt. Een nieuw rekeningnummer is dan een regel in een scherm en geen uitrol. Het land en het btw-nummer van de klant kunnen mee als voorwaarde, zodat een levering binnen Europa of een verlegde btw hun eigen code en hun eigen rekening krijgen.

De regels moeten sluiten op de cent. Exact weigert een boeking waarvan de regels niet optellen tot het totaal, en dat is terecht. Btw per regel berekenen en dan optellen geeft soms een cent verschil met het totaal dat de klant betaald heeft. Dat verschil gaat naar een vaste afrondingsrekening, in plaats van het uit te smeren over een regel die daarna niet meer klopt met de factuur.

En een regel zonder toewijzing wordt niet geboekt. Een artikel in een categorie die nergens aan hangt, blijft staan met een melding erbij. Zo'n geval op een wachtrekening zetten is verleidelijk, want dan loopt alles door en merkt niemand iets. Dat is precies het probleem: een wachtrekening wordt opgeruimd in maart, door iemand die niet meer weet wat er in september verkocht werd.

Hoe het in elkaar zit

Vijf keuzes die bepalen of de boekhouding ook klopt op de dag dat Exact traag is of een taak twee keer loopt.

De koppeling hangt aan een administratie

Elke call gaat naar een administratie, en een klant met drie vennootschappen heeft er drie. De koppeling hangt daarom aan die administratie en niet aan de persoon die ze aansloot: die mag van werk veranderen zonder dat het boeken stopt.

De teller loopt per minuut en per dag

Exact rekent af per administratie: zestig verzoeken per minuut, met een dagteller daarnaast, en de stand staat in de antwoordheaders. Het boeken loopt dus door een wachtrij die zichzelf afknijpt en die op de teller kijkt in plaats van ertegenaan te lopen. Een drukke maandag wordt zo een wachtrij die leegloopt, en geen reeks mislukte facturen.

Niemand wacht op de boekhouding

Wie een factuur aanmaakt, wacht niet tot Exact geantwoord heeft. De boeking vertrekt uit een wachtrij, met een herhaling die groeit voor een fout die overwaait, en met een melding voor wie ze moet oplossen bij een fout die blijft staan.

Elke boeking laat een spoor

Bij elke factuur staat wat er naar Exact ging, wat er terugkwam en welke sleutel ze daar kreeg. Vraagt de boekhouder in maart waarom een factuur nergens staat, dan is dat een opzoeking van een halve minuut en geen archeologie in logbestanden.

Per veld ligt vast wie de bron is

De factuur en haar regels komen uit de applicatie, de afpunting en de openstaande stand komen uit Exact. Beide kanten beslissen dus nooit over hetzelfde veld, en er is geen moment waarop twee systemen elkaar staan te overschrijven.

De package

Aanmelden met Exact is het stuk dat in elk project terugkomt, en het is ook het stuk dat je geen twee keer wil schrijven. Het staat op Packagist als hansdeboeck/socialite-exactonline: een provider voor Laravel Socialite, zodat Exact Online dezelfde weg volgt als Google of Microsoft.

Installeren, en de gegevens van je app bij Exact in config/services.php zetten:

composer require hansdeboeck/socialite-exactonline:dev-master
'exactonline' => ['client_id' => env('EXACTONLINE_CLIENT_ID'),'client_secret' => env('EXACTONLINE_CLIENT_SECRET'),'redirect' => env('EXACTONLINE_CALLBACK_URL'),'base_url' => env('EXACTONLINE_BASE_URL', 'https://start.exactonline.be'),],

Daarna is aanmelden een regel, en komt de gebruiker terug met zijn naam, zijn mailadres en zijn foto, plus het token en de verversing waarmee de rest van de api aangesproken wordt:

return Socialite::driver('exactonline')->redirect();

Wat ze doet is smal gehouden: het adres van de toestemming en van het token, het token ophalen, en de aangemelde gebruiker uitlezen. Meer niet. Het verversen, de administratie onthouden, de boekingen: dat is werk van de applicatie erboven. Een provider die meer doet dan aanmelden, is een provider die in de weg gaat zitten zodra een project iets anders wil.

Het land is wel instelbaar, want dat is het enige dat aan de provider zelf hangt: base_url staat standaard op het Belgische adres en gaat met een regel in je .env naar het Nederlandse of het Duitse.

Ze is de oudste van mijn reeks, en de enige die niet van nul begon. Ik nam in 2021 een bestaande provider over die was blijven liggen, zette hem op Socialite Providers 4 en op een recente PHP, en bracht hem onder mijn eigen naam op Packagist omdat er projecten op draaiden. De tag die er staat, is nog die van voor die overname: voor PHP 8 neem je dus dev-master, zoals hierboven. De broncode staat op GitHub, onder MIT.

Boek je zelf in Exact Online

Staat je boekhouding in Exact en tikt er nog iemand facturen over uit een webshop, een kassa of een eigen applicatie, dan is het patroon hierboven hetzelfde: aansluiten met oauth, boeken vanuit een wachtrij, en de grootboekrekening uit een tabel die je zelf beheert. Stuur me gerust een mail.

De andere software waar ik al mee koppelde staat bij de koppelingen, de rest van de packages bij de Laravel packages, en wat er als eigen applicatie uit groeide bij het portfolio.