Exact Online Magento koppeling die blijft draaien als het druk wordt

Exact Online biedt een REST API met resources voor onder meer verkooporders, verkoopfacturen, artikelen, voorraadposities, relaties (CRM-accounts) en grootboekrekeningen. De API gebruikt OData-achtige queryparameters, zoals een select om alleen de velden op te halen die je nodig hebt. Elke call gaat naar een specifieke administratie, in de API een division genoemd. Heb je meerdere administraties, bijvoorbeeld per land of per BV, dan moet de koppeling per order bepalen naar welke division die gaat.

De belangrijkste beperking zijn de rate limits. Volgens de officiële Exact-documentatie mag een app per administratie 60 calls per minuut en 5.000 calls per dag doen, voor zowel de REST API als de XML-webservices. Boven de limiet krijg je een HTTP 429-antwoord. De responses bevatten headers waarmee je ziet hoeveel calls er resteren. Een goede koppeling leest die headers uit en remt zelf af voordat Exact dat doet.

Reken het voor je eigen shop even door. Een order met een nieuwe klant kost al snel meerdere calls: klant opzoeken, eventueel aanmaken, de order met regels aanmaken en de status terugschrijven. Daar komen voorraad- en artikelupdates bij. Met 5.000 calls per dag is er bij een paar honderd orders per dag weinig ruimte meer voor een volledige voorraadsynchronisatie elk kwartier. Daarom gebruiken we waar mogelijk de sync- en bulk-endpoints van Exact. Volgens de documentatie leveren die tot 1.000 records per pagina, tegen 60 bij de meeste gewone endpoints, en vragen ze alleen gewijzigde records op via een timestamp. Exact raadt die sync-endpoints zelf aan om binnen de limieten te blijven.

Authenticatie loopt via OAuth 2.0 met de authorization code flow. Er is geen server-naar-server sleutel: een gebruiker met rechten in Exact logt eenmalig in en geeft toestemming. Daarna werkt de koppeling met een access token dat ongeveer 10 minuten geldig is en een refresh token. Bij elke refresh krijg je een nieuw refresh token en vervalt het oude. Slaat de koppeling dat nieuwe token niet direct en atomair op, of verversen twee processen tegelijk, dan is de verbinding weg en moet iemand opnieuw autoriseren. Dit is in onze ervaring de meest voorkomende oorzaak van een koppeling die 's nachts stilvalt zonder dat iemand het merkt. De oplossing is een centrale tokenopslag met een lock, zodat er altijd maar één proces tegelijk ververst.

Voor voorraad en artikelen hoeft de koppeling niet continu te pollen. Exact ondersteunt webhooks voor een deel van de resources. Een webhook meldt dat er iets is gewijzigd; de koppeling haalt daarna alleen dat record op. Dat scheelt calls en maakt voorraad op de site sneller actueel. Webhooks vervangen geen periodieke controle: bij een gemiste melding moet een nachtelijke reconciliatie de verschillen alsnog rechtzetten.

Bij B2B verschuift het leidende systeem. Debiteuren, betalingscondities, kredietlimieten en klantspecifieke prijzen staan vaak in Exact en moeten naar Magento, niet andersom. Magento 2 Open Source heeft geen ingebouwde bedrijfsaccounts met meerdere gebruikers; dat zit in Adobe Commerce of vraagt om extensies. De koppeling moet dus aansluiten op de manier waarop jouw shop B2B-klanten modelleert. Kijk voor de platformkant ook naar onze pagina over Magento B2B.

Met meerdere store views of websites speelt een andere vraag: gaan alle orders naar één administratie, of heeft elk land of elk merk een eigen division? Dan moet de koppeling per website de juiste division, dagboeken, BTW-codes en valuta kiezen. Voor OSS-verkopen buiten Nederland betekent dat bovendien BTW-codes per land. Deze mapping leggen we vast voordat er een regel code wordt geschreven, samen met degene die de boekhouding doet.

Retouren zijn het lastigste deel. Een gedeeltelijke retour met verzendkosten en een kortingsregel moet in Exact een creditnota opleveren die naar de originele factuur verwijst en exact optelt tot het bedrag dat de klant terugkrijgt. Afrondingsverschillen van een paar cent per order lijken klein, maar maken een maandafsluiting tot zoekwerk.