Exact Online is een praktische boekhoudpakket voor (voornamelijk) de Nederlandse markt. Buiten boekhouding biedt het ook ERP-functionaliteit. Dankzij vele standaard en maatwerk-integratiemogelijkheden is het eenvoudig te koppelen om zo onderdeel te worden van de bedrijfsvoering.
Verstandig omgaan met beperkte aantal API-calls
Echter, de integratiemogelijkheden worden onder andere beperkt door het beschikbare aantal verzoeken die door de Exact Online API-servers afgehandeld kunnen worden. API staat hierbij voor “Application Programmatic Interface”; een koppelvlak voor data. De afgelopen jaren is die beperkt geweest middels zogenaamde “rate limits” tot een aantal verzoeken per dag en per minuut per combinatie van applicatie (de zogenaamde “client ID”) en administratie (de “divisie”). Dit aantal is van vrijwel onbeperkt via 50.000 in een aantal tussenstappen verlaagd naar de ultimo 2022 5.000 Exact Online API-calls per administratie per applicatie per dag en via vrijwel onbeperkt via 300 naar 60 API-calls per minuut voor dezelfde combinatie. Deze verlagingen worden in het algemeen vrij snel doorgevoerd en er zijn weinig tot geen mogelijkheden om hier vanaf te wijken. Meer uitleg over de werking is te vinden op Hoe werken de API limieten van Exact Online? - 3 van forums en andere daaraan gekoppelde artikelen op deze forums. Bij overschrijding van de limieten wordt meestal een foutmelding gegeven zoals “too many requests” of een HTTP 429-statuscode.
Merk op dat deze limiet qua Exact Online API-calls geldt voor een accountancy Exact Online-administratie van een paar euro per maand, maar ook voor een administratie binnen een regulier handelsabonnement van misschien wel 1000 Euro.
Het is daarom steeds belangrijker geworden om bij het opzetten van een nieuwe Exact Online-omgeving of bij het aanpassen van het gebruik het aantal beschikbare API-calls mee te nemen in de keuzes. Dit document als hulpmiddel daarbij. Uiteindelijk zal een consultant in overleg met de gebruikers hierin keuzes kunnen adviseren.
Workarounds
Er zijn meerdere mogelijkheden op dit moment om de limiet van 5.000 Exact Online API-calls per dag te omzeilen, bijvoorbeeld door meerdere applicaties te registreren in de Exact Online App Store (tot 2023: Exact Online App Center). Ook kan via eenvoudig gebruik gemaakt worden van de applicatieregistraties van apps in de marktplaats van Exact Online. Keuzes hierop baseren is echter niet duurzaam; de stikstofcrisis laat zien waar geitenpaadjes toe kunnen leiden.
Daarom is het eerste advies om geen gebruik te maken van workarounds als die niet volledig en duurzaam in lijn zijn met de gebruiksvoorwaarden, dan wel geen alternatief binnen enkele werkdagen beschikbaar is indien de gekozen route niet meer werkt.
Meest voorkomende problemen
In de dagelijkse praktijk is de limiet van 60 API-calls op Exact Online per minuut zelden een probleem. Ook op andere platformen met nog lagere limieten en doorvoersnelheid per API-verzoek leidt dit meestal niet tot problemen. Alleen platformen die 1 API-call per gelezen record nodig hebben, leiden tot onwerkbare problemen ook voor kleinere omgevingen. In de rest van de tekst zal daarom alleen de daglimiet behandeld worden voor het plannen van een Exact Online-omgeving.
De daglimiet heeft zijn weerslag op het aantal rijen dat per dag gelezen en het aantal rijen dat per dag geschreven of gemuteerd kan worden.
Lezen
Via de Exact Online API’s lezen levert elke API-call tussen de 1 (zoals AttachmentByUrl) en 1.000 (zoals TransactionLinesBulk) rijen op. De XML API’s liggen daar qua lezen meestal tussen met meestal 100 rijen op het hoogste niveau. Echter, onder de rijen op het hoogste niveau kunnen ook onderliggende niveau’s veel informatie bevatten.
Daarnaast biedt Exact Online nog zogenaamde “sync API’s”, waarbij bij het initieel laden 1.000 rijen per API-verzoek terugkomen, en vanaf dan alleen de mutaties bijgewerkt worden. Merk op dat gedurende het initieel laden nog steeds de limiet heeft van 1.000 rijen per API-call. Dit geldt dus ook als er bijvoorbeeld een nieuwe kolom gevuld moet worden! De Invantive SQL Exact Online-driver biedt gezien de complexe achterliggende logica hiervoor afgeleide tabellen met namen zoals TransactionLinesIncremental.
Voor de meeste transactietabellen bestaan sync API’s. Echter, voor niet alle API’s geldt dit. Vooral aan de inkoopzijde is de ondersteuning beperkt en moet vaak teruggevallen worden op 60 rijen per API-call. Bedrijven met als primair proces de assemblage van complexe producten uit onderdelen zullen hier mee geconfronteerd worden. Maar bijvoorbeeld een groothandelsbedrijf dat van een paar ingekochte containers spullen veel losse verkopen realiseert zal van deze beperking weinig tot geen last hebben.
Als richtlijn kan het benodigde aantal API-calls geschat worden door de tabellen die men nodig heeft in groepen onder te verdelen:
- Exact Online XML-tabellen: 1 API-call per 100 rijen vastgelegd in Exact Online
- Exact Online REST-tabellen: 1 API-call per 60 rijen vastgelegd in Exact Online
- Exact Online bulk en sync API’s: 1 API-call per 1.000 rijen vastgelegd in Exact Online
Merk op dat ook voor sync API’s geldt dat de bovengrens 1.000 rijen per API-call is. De geamortiseerde doorsneewaarde zal een hoger aantal rijen per API-call zijn, maar dat brengt risico’s met zich mee voor de continuïteit van de werking, net zoals ook een kortstondig liquiditeitstekort tot een faillissement kan leiden ondanks geweldig goed gevulde orderportefeuille.
Tel de aantallen API-calls bij elkaar op. Dit aantal moet samen met de benodigde API-calls onder de daglimiet (“daily rate limit”) blijven.
Schrijven
Het schrijven, verwijderen of bijwerken gaat meestal met 1 API-call per rij via de Exact Online REST API.
Via de XML-API met UploadXMLTopics kan voor de traditionele functionele onderdelen een veel hogere doorvoersnelheid en verlaagd capaciteitsbeslag gerealiseerd worden (zie Does Invantive SQL match the speed of Infinite Probability Drive?), maar de XML-API van Exact Online wordt niet bijzonder actief doorontwikkeld, biedt excellente ondersteuning voor het grootboek, maar zeer beperkte ondersteuning voor de branche-oplossingen. Producten zoals Get My Report maken bij voorkeur gebruik van de XML-API om het gebruikte aantal API-calls sterk te verlagen t.o.v. meeste maatwerkoplossingen en de Exact Online SDK.
Het is technisch mogelijk om de batchfunctionaliteit van OData via de REST API te gebruiken, maar die biedt formeel geen garanties voor correcte werking (de incorrecte werking is ook bevestigd), en heeft als bijkomend nadeel dat de payload na splitsing nog steeds per stuk geteld wordt. Men bespaart dus geen API-calls door te batchen.
In de praktijk is het dus niet mogelijk om meer rijen bij te werken of te muteren dan de daglimiet. Veelal worden alleen gegevens toegevoegd aan Exact Online, maar zodra eenmaal gearriveerd betekent dit dat mutaties over de gehele dataset bijzonder moeizaam zijn, nog los van de functionele beperkingen. Omdat financiële transacties van aard uit complianceredenen meestal onwijzigbaar horen te zijn, leidt deze eigenschap vooral tot praktische problemen als er veel data zijn in subadministratiecategorieën:
- relaties,
- artikelen,
- documenten,
- assemblages,
- en hun eigenschappen zoals prijzen.
Een ander veelvoorkomend probleem bij het schrijven is het schokkerig toevoegen van financiële transacties. In sommige organisaties worden niet elke dag transacties geboekt, maar gebeurt dit per tijdsperiode zoals een maand. Binnen enkele dagen wordt dan een groot aantal transacties verwerkt. Per maand bekeken valt dit ruim binnen de rate limits, maar op deze enkele dagen overstijgt dit de limiet regelmatig. De kans op productiestoringen is in een dergelijke hectische periode is hierdoor relatief groot tenzij de foutafhandeling van “too many requests” dusdanig vormgegeven is dat het bedrijfsproces goed en elegant herstartbaar is. Zorg daarom voor een herstartbaar bedrijfsproces, ook als halverwege de facturatie er uit vliegt!
Geadviseerde Beperkingen
In de praktijk is het advies om op Exact Online indien men gebruik wenst te maken van eigen integraties of standaardkoppelingen serieus naar het aantal benodigde API-calls te kijken afhankelijk van aantallen registratie en/of productie van data.
Bij schrijven in Exact Online is het nodig om de API-limieten serieus mee te nemen in de opzet als er sprake is van:
- Vastlegging van meer dan 5.000 relaties in totaal, en/of
- Vastlegging van meer dan 5.000 artikelen in totaal, en/of
- Inboeking van meer dan 1.000 verkoopfacturen per maand, en/of
- Inboeking van meer dan 500 inkoopfacturen per maand.
De aantallen waarbij daadwerkelijk problemen optreden met de rate limits kunnen significant hoger of lager liggen, en zal alleen uit een diepere analyse blijken. Een inkoopfactuur kan bijvoorbeeld tientallen regels hebben of maar een enkele regel.
In de praktijk zal de limiet het snelst geraakt worden bij schrijven in Exact Online. Indien uitsluitend voor lezen/rapportages gekoppeld wordt liggen de limieten waarbij serieuze aandacht nodig is significant hoger.
Bij enkel lezen in Exact Online is het pas nodig om de API-limieten serieus mee te nemen in de opzet als er sprake is van:
- Vastlegging van meer dan 100.000 relaties in totaal, en/of
- Vastlegging van meer dan 100.000 artikelen in totaal, en/of
- Vastlegging van meer dan 2.000.000 transactieregels in totaal over de levensduur van een administratie, en/of
- Inboeking van meer dan 10.000 verkoopfacturen per maand, en/of
- Inboeking van meer dan 500 inkoopfacturen per maand.
Geadviseerde Oplossingen
Op dit moment lopen de arbeidskosten stijl op zodra de bovengenoemde grenzen in zicht komen. De volgende oplossingsrichtingen dragen bij het aan het voorkomen van problemen met de limieten:
- Verspreid de gegevens over meerdere administraties.
- Gebruik een subadministratie buiten Exact Online.
Verspreid gegevens
Aangezien de Exact Online rate limits per administratie en per applicatie gelden, kan door bijvoorbeeld de data te spreiden over meerdere administraties een lineair hogere limiet gerealiseerd worden. Dit geldt zowel voor lezen als schrijven. In de praktijk komen we tegen dat per boekjaar een nieuwe administratie gevoerd wordt of dat verschillende soorten bedrijfsprocessen in apart Exact Online administraties gevoerd worden.
Subadministratie elders voeren
Het over langere tijd vastleggen van grote aantallen transacties binnen de grootboekadministratie van een werkmaatschappij kan problemen veroorzaak met de API-limieten. Aangezien Exact Online een gemengd grootboek is, leiden veel acties meteen tot boekingen die meteen of enige tijd later blijvend en onwisbaar worden.
Het aantal boekingen kan sterk beperkt worden door het gebruik van subadministraties binnen Exact Online te beperken, bijvoorbeeld door de registratie van verkopen in Magento te laten plaatsvinden of uren in Simplicate te laten boeken. Vervolgens kan het geaggregeerde saldo geboekt worden in het juiste grootboek en eventueel daar verder afgeletterd tegen betalingen. Ook is het mogelijk - zoals bij Autotask, Magento of kassasystemen - om de volledige subadministratie buiten Exact Online te voeren. Hierbij worden bijvoorbeeld per dag of per maand geaggregeerde boekingen gemaakt in Exact Online. Dit kan het benodigde aantal API-calls beperken met een factor 1.000 of meer.
Het is ook mogelijk om bijvoorbeeld verkoopfacturen met hulp van Invantive SQL/PSQL op te stellen en deze te mailen. U kunt dan de bedragen verdicht in het verkoopboek laden, wat maar een handvol API-calls kost voor honderden verkoopfacturen. Bijlages kunnen met 1 API-call per stuk geleidelijk of meteen toegevoegd worden.