Exact Online API in de praktijk: wat kan er echt

De Exact Online API is een REST-koppeling met ruim 400 resources: relaties, artikelen, orders, facturen, voorraad en boekingen. Er geldt een plafond van 60 calls per minuut en 5.000 per dag, per app per administratie. Bijna alles is te lezen en veel is te schrijven. De beperkingen zitten in het abonnement, de tokens en de webhooks.

Dit stuk is geschreven vanuit koppelingen die we zelf bouwen en draaien, voor onze eigen administraties en voor klanten in handel en productie.

Wat kan er via de API?

Lezen kan vrijwel alles wat in de schermen staat. Schrijven kan op de stromen waar de meeste koppelingen om draaien:

• Verkooporders en verkoopfacturen aanmaken en bijwerken. Een factuur met status verwerkt is daarna vergrendeld.
• Inkooporders, inclusief regels. Regels worden niet los gepost, ze zitten in de order.
• Relaties, artikelen en prijsafspraken, ook klantspecifieke verkoopprijzen.
• Bestelpunt, veiligheidsvoorraad en maximumvoorraad per artikel per magazijn, via inventory/ItemWarehouses. Dat opent de deur naar een inkoopadvies dat zijn uitkomst terugschrijft in Exact.
• Voorraadtellingen en magazijnoverboekingen, zolang ze nog concept zijn.

Een inkooporder kent geen veld "concept". Er zijn vier losse statussen: goedkeuring, order, ontvangst en factuur. Of een order via de API op "wacht op goedkeuring" blijft staan, hangt af van de goedkeuringsinstellingen in de administratie zelf. Test dat in de eigen omgeving voordat er een inkoopflow op leunt.

Welk Exact-abonnement is nodig?

Dat is de vraag die het vaakst te laat gesteld wordt. De API laat alleen zien wat het abonnement bevat. Voorraad per magazijn, met bestelpunt en veiligheidsvoorraad, zit alleen in Handel en Productie vanaf de Plus-editie. Verkoop- en inkooporders zitten in alle Handel- en Productie-edities. Een administratie met alleen Boekhouden heeft die resources niet.

Elke resource in de officiële referentie noemt de edities waarin hij beschikbaar is. Kijk daar eerst, dan pas naar de bouw.

Hoe werkt de toegang?

Een eigen koppeling begint met een app-registratie in het App Center van de eigen Exact-omgeving. Dat is gratis en levert een client-id, een client-secret en een webhook-secret op. De redirect-URL moet HTTPS zijn.

Daarna volgt OAuth2 met een login in de browser. Drie regels die in de praktijk het verschil maken tussen een koppeling die maanden draait en een die elke week omvalt:

1. Een access token leeft 10 minuten. Verversen kan pas in de laatste 30 seconden of daarna. Elke nachtelijke taak begint dus met verversen.
2. Een refresh token is eenmalig. Elke verversing levert een nieuw refresh token en maakt het oude ongeldig. Twee processen die tegelijk verversen, slopen elkaars token. Dan helpt alleen nog een handmatige login. In onze eigen client gebeurt verversen daarom onder een exclusieve lock, en na het pakken van de lock wordt de opslag opnieuw gelezen.
3. Een refresh token vervalt na 30 dagen zonder gebruik. Een koppeling die een maand stil ligt, moet opnieuw geautoriseerd worden.

Exact deelt de resources in scopes in, zoals Logistics inventory. Daarbinnen krijgt de app de rechten van de gebruiker die hem autoriseert. Een koppeling die alleen mag lezen, autoriseer je met een gebruiker die in die modules niets mag aanmaken.

Hoe ver komt een koppeling met 5.000 calls per dag?

Verder dan het klinkt, mits de juiste endpoints gebruikt worden. Exact heeft er drie soorten:

• Gewone endpoints: per record of in kleine pagina's. Bedoeld voor schrijven en voor losse records.
• Bulk-endpoints: 1.000 rijen per pagina, alleen lezen. Voor de eerste volledige download.
• Sync-endpoints: 1.000 rijen per pagina, alleen wat nieuw of gewijzigd is sinds een opgeslagen teller. Samen met SyncDeleted, dat de verwijderde records geeft.

Een meting uit de praktijk: de eerste volledige export van 21 tabellen uit de administratie van een importeur kostte 783 calls. Daarna haalt de dagelijkse sync alleen de wijzigingen op. De limieten hebben we daar ook gemeten, in de headers van een gewoon antwoord: 60 per minuut, 5.000 per dag.

De Sync-endpoints zijn betrouwbaarder dan filteren op de wijzigingsdatum. Twee records met dezelfde wijzigingsdatum komen bij een datumfilter soms dubbel of helemaal niet terug. De teller van Sync loopt altijd op en is uniek.

Wat kan er niet, of niet goed?

Eerlijk is eerlijk: een paar dingen werken anders dan verwacht.

Webhooks dragen geen data. Een webhook zegt alleen: dit record is aangemaakt, gewijzigd of verwijderd, met de sleutel erbij. De koppeling moet het record daarna zelf ophalen. Per onderwerp kan een app één abonnement hebben, en niet elke resource heeft een webhook. Gebruik webhooks als seintje, en laat de sync de waarheid zijn.

Geen aparte testomgeving. Er is geen geïsoleerde sandbox per Handel-administratie die we konden bevestigen. Testen gebeurt op een eigen proefadministratie of met nep-Exact in de tests. Schrijfacties op een productieadministratie verdienen dus een droge run.

Lange queries worden geweigerd. Exact draait op IIS, en dat weigert standaard een querystring boven 2.048 tekens. Een filter op honderd artikelcodes in één call loopt daarop stuk, en de fout telt mee voor de foutenlimiet per uur. Knip zulke filters op.

Verbindingen vallen soms weg. Bij een lange nachtelijke run brak Exact na 19 minuten en ruim duizend goede calls de verbinding af. Dat is geen reden om de run te laten falen. Een GET is veilig om te herhalen, dus drie pogingen met oplopende pauze, pas daarna alarm.

Niet alles staat er als stamgegeven in. Levertijd per leverancier bestaat als veld, maar de werkelijke levertijd volgt alleen uit inkooporder tegenover ontvangst. Voor een inkoopadvies is die tweede de betrouwbare bron.

Hoe bouwen we een Exact-koppeling?

Altijd hetzelfde patroon. Eerste keer volledig ophalen via Bulk of Sync. Daarna elke nacht alleen de wijzigingen plus SyncDeleted. Webhooks waar ze bestaan, om sneller te reageren. Een eigen budget van 50 calls per minuut, onder het plafond, zodat een tweede script op dezelfde dag nog ruimte heeft. En alles wat de koppeling schrijft, gaat eerst als concept in Exact, zodat een mens het kan goedkeuren.

Een veelgevraagde toepassing is de ordermail die als conceptorder in Exact landt. Bij een B2B-producent komen ruim 3.300 van de 5.017 gemeten ordermails er als correcte conceptorder in. Hoe dat werkt staat bij orderverwerking automatiseren. Wie meerdere systemen aan elkaar wil knopen, vindt de bredere aanpak in systemen koppelen.

Plan een Data Impact Scan en zie binnen een week wat er uit de eigen Exact-administratie te halen is.

Veelgestelde vragen

Kost de Exact Online API extra?

Voor een eigen koppeling op de eigen administratie niet: een app registreren in het App Center van de eigen omgeving is gratis. Wel bepaalt het abonnement welke data er via de API beschikbaar is. Voorraad per magazijn zit bijvoorbeeld alleen in de Handel- en Productie-edities vanaf Plus.

Wat zijn de limieten van de Exact Online API?

60 calls per minuut en 5.000 per dag, per app per administratie. Die staan in de headers van elk antwoord, als X-RateLimit-Minutely-Limit en X-RateLimit-Limit. Daarboven komt een 429 met een Retry-After. Lezen en schrijven putten uit hetzelfde budget.

Heeft Exact Online webhooks?

Ja, per onderwerp, zoals Accounts, Items, SalesOrders, PurchaseOrders, GoodsDeliveries en StockPositions. Een webhook bevat alleen de sleutel van het gewijzigde record, niet de data zelf. De koppeling haalt daarna het record op, dus elke webhook kost ook een call.

Kan een Exact-koppeling alleen-lezen zijn?

Niet via een aparte leesrechten-instelling. Exact deelt de resources in scopes in, zoals Logistics inventory, en daarbinnen krijgt de koppeling de rechten van de gebruiker die hem autoriseert. Wie een koppeling alleen-lezen wil, autoriseert hem met een gebruiker zonder aanmaak- of wijzigrechten in de betreffende modules.

Kan ik facturen via de API in Exact Online zetten?

Ja, verkoopfacturen kunnen via salesinvoice/SalesInvoices worden aangemaakt, als concept of direct. Een verwerkte factuur is daarna vergrendeld en niet meer via de API te wijzigen. Inkoopfacturen kunnen ook: de pdf als document met bijlage (documents/Documents en DocumentAttachments) en de boeking via purchaseentry/PurchaseEntries.