Hoe werkt de Exact Online API?
De Exact Online API is een REST API op basis van OData v3. Je spreekt hem aan per administratie (division) met een OAuth2-token. Elke resource, zoals SalesOrders, Items of Accounts, heeft een eigen endpoint. Je kunt filteren, selecteren en pagineren met OData-parameters.
Dat is prettig om mee te werken. Het nadeel: elke call telt. Een koppeling die per order eerst de relatie opzoekt, dan de artikelen controleert, dan de order plaatst en daarna de status terugleest, doet vier of vijf calls per order. Bij 100 orders per uur zit je dan al dicht tegen de minuutlimiet aan en bij 1.000 orders per dag ruim over de daglimiet.
Welke limieten gelden er?
| Limiet | Waarde | Geldt per |
|---|---|---|
| Calls per minuut | 60 | app, per administratie |
| Calls per dag | 5.000 | app, per administratie |
| Records per bulk- of sync-call | tot 1.000 | call |
| Access token | 10 minuten geldig | koppeling |
| Refresh token | vervalt na 30 dagen zonder gebruik | koppeling |
| Antwoord bij overschrijding | HTTP 429 | call |
| Onderhoudsvenster | dagelijks 04:00 tot 04:30 | hele API |
De tellers per minuut en per dag lopen los van elkaar. Je kunt dus ruim binnen de minuutlimiet blijven en toch halverwege de middag de daglimiet raken. Exact stuurt de actuele stand mee in de response headers (X-RateLimit-Minutely-Remaining en X-RateLimit-Remaining). Lees die uit en log ze. Dan zie je het aankomen in plaats van dat je het merkt aan een stapel 429-fouten.
De limieten gelden per app per administratie. Heb je drie administraties, dan heeft elke administratie zijn eigen budget. Draaien er twee koppelingen onder dezelfde app-registratie op dezelfde administratie, dan delen ze het budget.
Wat doe je met HTTP 429?
Een 429 betekent: te veel verzoeken in dit venster. Het verzoek is niet verwerkt. Een goede koppeling doet dan vier dingen:
- Stoppen met verzenden naar die administratie tot het venster is verlopen.
- Het niet-verwerkte werk in een wachtrij bewaren, niet weggooien.
- Later opnieuw proberen met een maximum aantal pogingen en een oplopende wachttijd.
- Controleren of het record inmiddels toch bestaat voordat je het opnieuw aanmaakt. Anders krijg je dubbele orders of facturen.
Zet de wachtrij buiten Exact, in je eigen middleware of database. Dan overleeft hij ook een herstart en het onderhoudsvenster van 04:00 tot 04:30.
Hoe verminder je het aantal calls?
Gebruik sync- en bulk-endpoints
Voor veel resources heeft Exact naast het normale endpoint een sync-variant (bijvoorbeeld sync/SalesOrder/SalesOrders) en een bulk-variant. Die geven tot 1.000 records per call terug. De sync-endpoints werken met een oplopende Timestamp-waarde, een teller en geen klok: je bewaart de hoogste waarde die je hebt gezien en vraagt de volgende keer alles daarboven. Zo haal je alle wijzigingen sinds de vorige run op in een handvol calls in plaats van duizenden. De resource catalogus van Exact laat per resource zien of er sync- en bulk-support is.
Gebruik webhooks in plaats van polling
Elke minuut vragen "is er iets veranderd?" kost 1.440 calls per dag, ook als er niets gebeurt. Webhooks draaien het om: Exact stuurt een bericht als er iets wijzigt in een topic zoals Accounts, Items, FinancialTransactions of StockPositions. Het bericht bevat alleen de sleutel en de actie. Je haalt het volledige record daarna op met een call. Zo betaal je alleen voor echte wijzigingen.
Let op drie dingen. Exact ondertekent het bericht met een HMAC-SHA256 hash over de inhoud, met het webhook secret van je app. Controleer die hash altijd. Exact verstuurt berichten opnieuw als je endpoint niet snel antwoordt, dus ontdubbel op sleutel en actie. En direct na het aanmaken van een abonnement stuurt Exact een lege validatie-POST die je moet accepteren.
Filter en selecteer
Vraag alleen de velden die je nodig hebt met $select en alleen de records die je nodig hebt met $filter. Een call blijft een call, maar de response is kleiner en sneller, en je hoeft minder vaak te pagineren.
Cache stamdata
Artikelen, relaties, btw-codes en grootboekrekeningen veranderen weinig. Haal ze eens per uur of per dag op via sync en bewaar ze lokaal. Zoek daarin op in plaats van per order een call naar Exact te doen.
Wanneer kies je een replica?
Rapportage is de grootste verbruiker van calls. Een Power BI-dashboard dat bij elke verversing alle verkoopregels van het jaar ophaalt via de API trekt in een keer duizenden calls en raakt de daglimiet. Daarna werkt ook je orderkoppeling niet meer, want die deelt hetzelfde budget.
De oplossing is een replica: een continu gesynchroniseerde kopie van je Exact Online-data in een eigen SQL-database (SQL Server, PostgreSQL of MySQL). De synchronisatie gebruikt sync-endpoints en webhooks en blijft binnen de limieten. Power BI, Tableau of je eigen rapportages lezen uit de database zonder de API te raken. Je houdt bovendien historie vast, ook als een record in Exact later wordt gewijzigd. Lees de vergelijking in ons artikel over Power BI via de API of via een replica.
Hoe werken de OAuth-tokens?
Een access token is 10 minuten geldig. Een refresh token vervalt als je hem 30 dagen niet gebruikt. Bij elke refresh krijg je een nieuw refresh token en vervalt de oude. Dat levert in de praktijk twee valkuilen op:
- Een koppeling die weinig draait, bijvoorbeeld een maandelijkse export, verliest na 30 dagen zijn refresh token. Plan dan een wekelijkse ping om hem levend te houden.
- Twee processen die hetzelfde refresh token gebruiken halen elkaar in. De tweede refresh faalt omdat de eerste het token al heeft vervangen. Laat een proces de tokens beheren en bewaar het nieuwe token voordat je het gebruikt.
Wat betekent de App Center-review?
Je registreert een app in Exact Online onder Partners, Exact App Store, Manage my apps. Dat levert een client id en secret op. Met die app autoriseer je de administraties waar je toegang toe hebt. Voor een koppeling die voor jouw bedrijf draait is dat genoeg. De review door Exact is alleen nodig als je de app wilt publiceren in de Exact App Store, zodat andere bedrijven hem kunnen installeren. Exact controleert dan onder meer je gebruik van de API, de afhandeling van limieten en de beveiliging.
Voor een koppeling die alleen bij jou draait is dat niet nodig. Voor een leverancier die een koppeling als product aanbiedt wel. Reken daar tijd voor in de planning.
Checklist: is je koppeling limietbestendig?
- Leest de koppeling de X-RateLimit-headers uit en logt ze?
- Gebruikt hij sync- of bulk-endpoints voor alles wat periodiek wordt opgehaald?
- Gebruikt hij webhooks voor wijzigingen in plaats van polling?
- Staat er een wachtrij met retry en een maximum aantal pogingen?
- Controleert hij op bestaande records voordat hij opnieuw aanmaakt?
- Beheert een proces de tokens en wordt het refresh token direct opgeslagen?
- Blijft hij binnen de limiet als het volume verdubbelt?
- Lopen rapportages via een replica in plaats van via de API?
Conclusie
De limieten van 60 calls per minuut en 5.000 per dag zijn geen probleem als je koppeling ervoor is ontworpen. Sync-endpoints, webhooks, een wachtrij en gecachete stamdata houden het verbruik laag. Rapportage hoort niet op de API maar op een replica. Draait er een koppeling die regelmatig 429 geeft? We helpen en fixen ook zonder groot project.