Exact Online API koppelen aan je webshop.

Exact Online is online boekhoudsoftware uit Delft, met daarnaast modules voor handel, productie en projecten. Voor een webshop of groothandel is het meestal de plek waar de administratie staat: debiteuren, facturen, betalingen, artikelen en vaak ook de voorraad.

Dat maakt het een logisch eindpunt van een koppeling. Wat op je site gebeurt is verkopen; wat in Exact gebeurt is de financiële verantwoording. De koppeling zorgt dat die twee dezelfde werkelijkheid zien.

Boekhoud je in Moneybird, lees dan hoe we Moneybird koppelen aan je website, met factuur en betaalstatus. Voert je accountant de administratie in Twinfield, lees dan wat er komt kijken bij Twinfield koppelen aan je website.

De API is REST met JSON en werkt per administratie: de code van die administratie staat in het adres van elke aanroep.

Aanmelden gaat met OAuth 2.0. Je maakt in het developerportaal van Exact een app aan, en een beheerder van de administratie geeft die app eenmalig toegang. Daarna werkt de koppeling met een access token dat 10 minuten geldig is, en een refresh token waarmee je een nieuw ophaalt.

Dat refresh token verandert bij elke vernieuwing. De koppeling moet dus het nieuwste bewaren, niet het eerste. Doet hij dat niet, dan werkt alles tot het token verloopt en daarna niets meer.

In stappen ziet een koppeling op de Exact Online API er zo uit:

1. We registreren de app en kiezen de scopes. In de API-documentatie staat bij elk endpoint welke scope erbij hoort, zoals Crm accounts voor debiteuren en Sales invoices voor facturen. Meer rechten dan nodig vragen we niet.
2. Een beheerder van de administratie geeft de app toegang. Met /api/v1/current/Me leest de koppeling daarna welke administratie actief is, en met system/Divisions welke administraties de gebruiker die toegang gaf kan openen.
3. We testen met een beperkte set orders en lopen de boekingen samen met je boekhouder na.
4. Bij de livegang zetten we de synchronisatie op een vast ritme aan, en voor wat meteen door moet een webhook.

De kant op naar Exact: de bestelling. Meestal als verkooporder of als factuur, met de klant als debiteur erbij. Verkooporders via de API zijn er alleen in de pakketten Wholesale & Distribution en Manufacturing; in de andere pakketten wordt het een verkoopfactuur. Bestaat die klant al, dan koppel je eraan in plaats van hem opnieuw aan te maken; daar hoort een afspraak bij over hoe je dat herkent, op e-mailadres of op klantnummer. Rekent je klant online af, dan hoort de betaling bij dezelfde referentie als de factuur; hoe dat werkt lees je bij Mollie koppelen.

De kant op naar je site: artikelen, prijzen en voorraad. Dat is waar de winst zit voor een groothandel met duizenden artikelen, want die lijst met de hand bijhouden is geen werk maar een achterstand. Ligt de voorraad in een magazijnsysteem als Picqer, dan spreken we vooraf af welk systeem het getal levert. Komt je omzet uit een winkel, dan haal je die via de Lightspeed API op voordat hij in Exact Online landt.

Wat je niet doet is alles bij elke bezoeker ophalen. Wij bewaren de gegevens aan onze kant en verversen op een ritme dat binnen de limieten past.

Drie dingen, en ze komen altijd terug. Een order die in de webshop staat en niet in de boekhouding, en dus pas bij de kwartaalafsluiting opvalt. Een artikel dat op je site nog leverbaar is terwijl het al weken op is, met een boze klant als gevolg. En een prijs die in Exact is aangepast en op de site niet, waarna iemand met de hand een creditnota maakt.

Elk van de drie kost meer tijd dan de integratie, en dat is voor de meeste klanten de rekensom. Wat het niet oplost is een administratie die niet klopt: een koppeling maakt van rommel geen orde, hij maakt het alleen sneller zichtbaar.

De Exact Online API rekent met 60 aanroepen per minuut en een dagelijkse limiet per administratie. Elk antwoord vertelt in de headers hoeveel er nog over is, dus een koppeling kan zelf afremmen voordat hij tegen de grens loopt.

Daar hoort de paginagrootte bij. De meeste endpoints geven 60 regels per keer, de bulk- en sync-endpoints geven er 1000. Wie een catalogus van tienduizend artikelen via het gewone endpoint ophaalt, gebruikt ruim 160 aanroepen voor iets wat met de sync-variant in 10 kan.

De sync-endpoints werken met een timestamp. Je bewaart de hoogste waarde van de vorige keer en krijgt daarna alleen wat nieuw of gewijzigd is. Verwijderde records komen daar niet in mee; die haal je op via een apart endpoint voor verwijderde gegevens. Wie dat overslaat, houdt artikelen op de site die in Exact al weg zijn.

En een afgeronde verkooporder is via de API niet meer te wijzigen. Een correctie op een order die al is afgehandeld gaat dus niet automatisch, en dat hoort in de afspraken over retouren.

Exact Online kent twee routes. De REST API is de huidige: per endpoint gedocumenteerd met de methodes, de scope en of er een webhook bij hoort, en met aparte sync- en bulk-endpoints voor grote hoeveelheden. De XML API is de oudere route voor import en export van vaste onderwerpen, en de documentatie daarvan staat achter de login van Exact Online.

Voor een koppeling met een webshop bouwen wij op de REST API. Daar zitten de webhooks en de sync-endpoints die een koppeling zuinig houden met de limieten. Kom je bij een bestaande site een koppeling op XML tegen, dan is dat de oudere route; voor uitbreiden bouwen we liever op REST.

Op WordPress met WooCommerce draait de koppeling als een taak op de server. Een bestelling gaat naar Exact zodra de betaling is bevestigd en niet bij het afrekenen, zodat er geen facturen ontstaan voor orders die nooit zijn betaald. Artikelen en voorraad verversen op een vast ritme, en in het beheerscherm laat de logging zien wanneer de laatste synchronisatie was en of er iets is blijven hangen. Hoe we zo’n WooCommerce webshop bouwen, staat op een eigen pagina.

Op een maatwerksite in Next.js staat de koppeling in een eigen serverroute. Exact kan daar webhooks naartoe sturen, bijvoorbeeld bij een gewijzigde debiteur, en de site ververst dan alleen de pagina’s die het raakt. Dat past bij een groothandel met een eigen bestelomgeving voor vaste klanten, waar de prijslijsten per klant uit Exact komen. Een klantportaal op je administratie, waarin klanten hun orders en facturen uit Exact inzien, bouwen we als webapplicatie op maat.

In beide gevallen staan de tokens alleen op de server. Voor de webshop of bestelomgeving zelf, zie Design & Development.