Impact Exact Online API aanpassingen 1 juli 2021

Go to English version

Exact Online heeft aangegeven dat per 1 juli 2021 een aantal generieke aanpassingen aan de Exact Online API’s doorgevoerd zullen worden. Deze aanpassingen zijn nodig om de schaalbaarheid en het toegenomen gebruik van het ecosysteem te verbeteren.

Zie onder voor de laatste updates.

De aanpassingen kunnen niet vooraf getest worden door gebrek aan een representatieve omgeving en gebrekkige specificaties. Invantive heeft besloten om gebruikers te informeren dat rond 1 juli een productiestop kan optreden die meerdere weken kan duren en problemen kan veroorzaken tot in september. Abonnementen op Data Hub en Data Replicator worden ontbonden en een alternatief met lagere service-eisen is beschikbaar.

Invantive zal zodra mogelijk releases beschikbaar maken. Op basis van de huidige informatie en aanpak is het nog niet mogelijk om de benodigde aanpassingen te bepalen. Releases die de problemen ondervangen komen indien haalbaar ook beschikbaar van Invantive Data Hub en Data Replicator voor directe koppeling met Exact Online.

Ook aanpassingen in rapportages en de ketens die gebruik maken van Invantive SQL zullen nodig zijn; gelieve hiervoor ruim voor 1 juli consultancy bij dealers of Invantive te reserveren.

Nieuwe Exact Online API limieten

De volgende limieten worden ingevoerd naar verwachting per 1 juli 2021:

  • Maximaal 200 token endpoint calls per app, gebruiker en dag: implicit grant flow bij aanmelden en elke tien minuten, ophalen access token op basis van code uit code grant flow, ophalen access token via refresh token uit code grant flow.
  • Maximaal 1 accesstoken generatie per 9,5 minuten, maar niet wachten op HTTP 401 foutmelding (zie volgende punt).
  • Niet meer dan 10 foutmeldingen per app, administratie, endpoint en uur.
  • Verplichte filter op enkelvoudige en bulk endpoints als een sync API beschikbaar is (zie Exact Online: is verplicht filteren per client ID instelbaar?): bekend onder de werknaam “mandatory filtering”.
  • Maximaal 60 calls per minuut in plaats 300 calls per minuut: het betreft een limiet over zowel XML als REST API’s. Bij een overschrijding wordt automatisch het aantal calls per minuut gereduceerd.
  • Throttling bij gebruik boven fair use: dit was al zo.
  • Uitgereikte refreshtokens vervallen 30 dagen na laatste keer uitwisselen accesstoken.
  • Geen uitzonderingen meer qua gebruik oude refreshtokens (workaround voor interactieve producten beschreven op Omzeil Exact Online 2FA om te voorkomen dat u elke tien minuten uw pincode moet invoeren).

Daarnaast werden we er attent op gemaakt dat de jaren geleden aangekondigde limiet van 5.000 API calls per dag zal worden ingeschakeld. Hier verwachten we geen problemen mee omdat Invantive SQL de stabiele Sync API’s en bulk API’s al geruime tijd ondersteunt.

Wel is gebleken dat de rate limit header X-RateLimit-Remaining met daarin het resterende aantal API calls tot het volgende dagelijkse resetmoment niet altijd het juiste aantal resterende calls weergeven met tot een factor 4 verschil. Invantive SQL zal echter bij een HTTP 429 Too Many Requests error ook een steeds langere pauze inlassen, waardoor de kans op een storing beperkt blijft.

Wel is recent gebleken dat de Deleted items in de sync API’s na 2 maanden opgeruimd worden. Logica is toegevoegd in 20.1.432 en later om automatisch hiervoor te corrigeren. De sync API’s en gerelateerde *Incremental tabellen zijn dus niet betrouwbaar qua volledigheid op oudere releases.

De beperking van het aantal calls per dag zal wel problemen opleveren voor gebruikers die bijvoorbeeld 2 miljoen artikelupdates qua prijzen en teksten per kwartaal willen verwerken in paar dagen. Deze gebruikers moeten de werkzaamheden over een langere periode uitsmeren door de software te laten finetunen of wisselen naar een ander pakket.

De specificaties zijn te vinden als volgt:

Risico’s

De volgende risico’s zijn geïdentificeerd en vereisen mogelijk aanpassingen.

Ontbreken Testomgeving

De impact van de veranderingen kan pas op 1 juli getest worden. Exact Online kent geen sandbox of versies van de API’s zoals Salesforce waar app ontwikkelaars voor livegang de compliance van hun software met de API’s kunnen valideren. De signalerende e-mails vanuit het API ecosysteem blijken tenminste deels niet te kloppen en zijn niet herleidbaar.

Exact Online kent voor deze wijzigingen ook geen gefaseerde inproductiename, bijvoorbeeld per applicatie, accountant, server of klantclusters.

Een deel van de aanpassingen zijn niet te overzien qua impact en een deel van de aanpassingen is sowieso niet realiseerbaar zonder workarounds.

Het voorafgaand aan 1 juli uitleveren met aanpassingen op de gok en daarna nogmaals om verder glad te trekken over honderden servers heen is kostentechnisch niet realistisch en brengt het risico met zich mee dat de aanpassingen op de gok fouten introduceren of nog erger: security issues aangezien veel beperkingen betrekking hebben op de authenticatie.

Actie: het risico van het ontbreken van een testomgeving is verkleind door pas 1 juli te starten met de werkzaamheden voor eventueel benodigde aanpassingen.

Lange Looptijd door BTW- en Vakantieperiode

De werkzaamheden, behoudens voorsorterende activiteiten zoals upgraden centrale infrastructuur, starten zoals boven beschreven pas 1 juli. De livegang is ook de start van rapportage over de voorafgaande BTW-periode, die traditioneel ook mankracht vergt. Daarnaast is de mankracht beperkt vanwege geplande vakanties, zowel bij de Invantive partners als bij Invantive zelf.

De looptijd van de aanpassingen - voor zover haalbaar - is daardoor lang. We rekenen er op dat dit in september kan voortduren voor een zekere mate van stabiliteit optreedt.

Actie: het risico is zo goed mogelijk ondervangen door gebruikers vooraf te informeren zodat ze zich kunnen voorbereiden en een deel van de abonnementen op een lager serviceniveau in te delen, zie Stel tijdig uw rapporten op: tools voor Exact Online mogelijk niet beschikbaar na 1 juli, Laad tijdig uw wisselkoersen: Valuta Tools voor Exact Online mogelijk niet beschikbaar na 1 juli en Wijziging condities Invantive Data Hub en Invantive Data Replicator.

Het is niet gewenst om per klant duizend administraties of meer toe te voegen aan Invantive Cloud. De infrastructuur is niet voorzien op deze load en kostentechnisch kan dit niet uit.

Clusteropstellingen Invantive SQL, Data Hub of Data Replicator

  • Maximaal 200 token endpoint calls per app, gebruiker en dag: dit betekent maximaal 2000 verbindingsminuten per dag en dat is bij een clusteropstelling niet realiseerbaar.
  • Maximaal 1 access token generatie per 10 minuten: bij clusteropstellingen met Invantive SQL is dit niet realiseerbaar.
  • Geen uitzonderingen meer qua gebruik oude refreshtokens.

De limiet van maximaal 1 accesstoken per 10 minuten is ook niet haalbaar als meerdere Data Hub jobs gelijktijdig draaien tegen Exact Online of kort na elkaar gestart worden. Eventueel kan overwogen worden om de volgende executie van een job te plannen minimaal 10 minuten na afloop van de vorige job.

Actie: een deel van de problemen is opgelost doordat Invantive Keychain de snel vervallende refresh tokens zal vasthouden. Voor grote omgevingen met veel concurrency of clusters is er een oplossingsrichting op basis van consultancy en op basis van Bring Your Own App.

Actie: er vinden voorlopig geen nieuwe koppelingen plaats tussen Data Hub en Replicator en Exact Online. Grote kantoren die momenteel willen overstappen adviseren we dit uit te stellen tot na september. Kleine gebruikers kunnen gegevens laden via de Invantive Cloud driver.

Invantive Control for Excel

  • Maximaal 1 access token generatie per 10 minuten.

Actie: na 1 juli zal de logica die wacht op een 401 omgebouwd worden. Hierbij zal rekening gehouden worden met klokverschillen tussen lokale devices en de Exact servers, zoals nu ook al gebeurt met de generatie van verificatiecodes.

Overall

De volgende problemen gelden in alle deploymentscenario’s:

  • Niet meer dan 10 foutmeldingen per app, divisie, endpoint en uur: het is nog niet duidelijk welke gebeurtenissen gerekend worden als “foutmelding”; daardoor kan er nog niet afdoende rekening mee gehouden worden.
  • Verplichte filter op enkelvoudige en bulk endpoints als een sync API beschikbaar is: dit is niet praktisch haalbaar en een in onze ogen onzinnige aanpak van een overbelastingsissue.

Actie: na 1 juli zal proefondervindelijk bepaald worden wanneer er echt sprake is van foutmeldingen en zal van geval tot geval - indien haalbaar - een oplossingsrichting bepaald worden.
Actie: indien een filter verplicht wordt, dan zal als workaround een kunstmatig filter geïntroduceerd worden waardoor desgewenst effectief toch alles opgehaald wordt. Indien nodig wordt het kunstmatige filter automatisch gevarieerd. Daarnaast blijven Invantive gebruikers automatisch advies ontvangen over het gebruik van de API’s.

Andere Apps

Alle Exact Online applicaties en partners zullen tegelijk op 1 juli met deze verandering geconfronteerd worden. Uit berichten begrijpen we dat ook andere apps het risico lopen op discontinuïteit. We raden u aan om tijdig bij de leveranciers na te vragen of en welke problemen men verwacht.

Adviezen aan Gebruikers

We raden gebruikers aan om alvast te upgraden naar minimaal 20.1.432 (BETA) in afwachting van verdere aanpassingen.

Aangezien veel aanpassingen niet door ons vooraf getest kunnen worden, moeten gebruikers er van uit gaan dat het gebruik van Invantive-producten rond 1 juli niet mogelijk is en er een productiestop optreedt die meerdere weken kan duren. Het valt niet uit te sluiten dat de problemen aanhouden tot in september.

Invantive zal zodra mogelijk releases beschikbaar maken. Op dit moment is het voor ons niet mogelijk om de aanpassingen in te schatten.

Ook aanpassingen in rapportages en de ketens die gebruik maken van Invantive SQL zullen nodig zijn; gelieve hiervoor ruim voor 1 juli consultancy bij dealers of Invantive te reserveren.

Mogelijke Lange Termijn Verbeteringen Exact Online

Vanuit Invantive dragen we de volgende verbetervoorstellen aan richting Exact Online om de beschikbaarheid te verbeteren en gemakkelijker wijzigingen te kunnen doorvoeren. De relevantie en haalbaarheid kunnen we niet beoordelen, maar vanuit onze maatschappelijke betrokkenheid delen we deze:

Testomgeving en/of Versionering Exact Online API’s

Op dit moment worden wijzigingen (inclusief breaking changes) toegepast op Exact Online zonder dat app ontwikkelaars vooraf de kans hebben om hun applicaties te testen en certificeren tegen de nieuwe situatie. Op dit moment is er geen testomgeving en kunnen app ontwikkelaars ook niet (zoals bijvoorbeeld op Salesforce, Teamleader of Loket) zelf bepalen wanneer ze van de ene naar de andere API versie overgaan.

Suggestie(s): toevoegen van of een sandbox/testomgeving vanaf 6 maanden voor een breaking change live gaat stelt ontwikkelaars en gebruikers in staat om ongeplande en vermijdbare downtijd te voorkomen. Als alternatief kan gewerkt worden met versionering, door bijvoorbeeld naast de huidige v1 een v2 te introduceren. De v2 is grotendeels identiek aan v1, maar bevat breaking changes zoals boven genoemd, vervallen API’s en nieuwe API’s. In sync met de Falls en Spring releases kan telkens een oude versie offline gehaald worden, zodat er altijd 6 maanden overlap is en voldoende tijd om de risico’s te verkleinen. Een beleid per administratie is dan ook niet nodig; de app ontwikkelaar kan zelf sturen welke administraties van welke versie gebruik maken.

Beter Plannen

De afgelopen jaren werden breaking changes vaak op de 1e van de maand gepland en geimplementeerd. Dit valt precies samen met de periodekalender van de meeste bedrijven en dus traditioneel de drukste tijd voor de Exact Online gebruikers voor bijvoorbeeld BTW-aangiftes of management accounting. Het is niet ongewoon dat de 4e of 8e dag van de maand cijfers gerapporteerd moeten worden. Om risico’s te voorkomen vind je daarom bij de meeste beursgenoteerde bedrijven daarom frozen periods: rond de periodestart mag geen nieuwe software in productie genomen worden. Dit gaat soms zelfs zover dat zelfs de traditionele transacties zoals betalingen kort opgeschort worden.

Suggestie(s): het livegaan van breaking changes zou daarom beter plaatsvinden na de afronding van de perioderapportages in een periode waarin personeel beschikbaar is. Dit is meestal het voorjaar en najaar, bijvoorbeeld met de lange weekends rond 15 april en rond 15 september.

Slimmere Horizon

De horizon aan limieten worden meestal opgesteld op basis van ronde getallen, zoals 30 dagen voor refresh tokens of 60 dagen voor leeghalen deleted items van de sync API’s. Een veelvoud van 30 dagen is onhandig. Bij bijvoorbeeld heruitgifte van bankrekeningnummers en telefoonnummers wordt daarom vaak gewerkt met de periode lengte plus iets extra, bijvoorbeeld 12 maanden + 1 maand. Ook bij de APK-keuring is de tijdshorizon enigszins opgerekt t.o.v. precies 365 dagen, zodat mensen de kans hebben om een prettig tijdstip te prikken voor hun APK-keuring.

Suggestie(s): als een limiet nodig is van circa 30 dagen, dan is verstandig om bijvoorbeeld uit te gaan van minimaal 31 dagen plus de typische afwezigheid van cruciaal personeel, bijvoorbeeld in het weekend. Een betere keus is daarom bijvoorbeeld 38 dagen of 45 dagen in plaats van 30 dagen. Dit voorkomt dat elke maand een horizon bereikt wordt en er stress is.

Goed Communiceren

Breaking changes en changes worden zelden gecommuniceerd en zijn meestal niet of niet goed gedocumenteerd. Hierdoor ontstaan verstoringen, mede omdat dankzij het commerciele succes veel externe partijen met Exact Online willen samenwerken.

Ter illustratie: Invantive is misschien wel een grote partner van Exact, maar het is niet wenselijk dat Invantive bij Google op nummer 1 staat voor veel van de Exact Online API gerelateerde zoektermen. Als de merkeigenaar niet op 1 staat, dan betekent dit dat de merkeigenaar ondanks het door Google gewaardeerde eigendom van het merk een serieuze achterstand heeft in de informatievoorziening.

Suggestie(s): het zou prettig zijn als Exact API support actief en vroegtijdig communiceert met de actieve gebruikers. Onderdeel hiervan kan zijn om de community te stimuleren en ook via Google vindbaar zou maken. Het is verstandig om bij breaking changes vooraf aan te kondigen of op zijn minst na doorvoering te communiceren. Mocht een breaking change accuut doorgevoerd moeten worden vanwege overmacht, dan is het beter om het gesprek overbruggend aan te gaan als een dialoog in plaats van een stellende monoloog. Stellen - en zeker vanuit een last stand positie - levert volgens Zuidema in het algemeen een grotere kans op voor een relatiebreuk en escalatie.

Commercieel Model

Specifiek voor de Exact Online API rate limits zijn de beperkingen erg strak voor de bovenste 1% van de gebruikers. De Exact Online infrastructuur kan echter gemakkelijk de grote gebruikers aan, maar de API’s voorzien niet in dergelijk intensief gebruik.

Suggestie(s): het kan commercieel interessant zijn om net zoals Yuki en Salesforce extra API calls aan te bieden tegen een meerprijs. Dit stimuleert app ontwikkelaars en gebruikers ook om hier op te sturen. “Als iets gratis is, dan is het ook niks waard.” zegt een oud-verkopersgezegde.

Teruggeven Errorstatus via HTTP Headers

De status van de rate limits wordt gecommuniceerd via HTTP headers. De waardes stemmen niet altijd overeen met het daadwerkelijk gebruik, maar geven een goede indicatie. Productiestoringen kunnen door client software voorkomen als de beperkingen op het aantal foutmeldingen ook teruggegeven kunnen worden via een HTTP header, bijvoorbeeld het maximum aantal per uur op het endpoint, het aantal opgetreden errors en het eerstvolgende resetmoment in UTC.

Verder

Dit document zal indien nodig bijgewerkt worden.

Update 30 juni 2021 mogelijkerwijs worden een deel van de wijzigingen later dan 1 juli ingeschakeld voor alle administraties of per groep van applicaties. Hier is nog geen formeel bericht over.

Update 1 juli 08:45 het is onbekend of de wijzigingen doorgevoerd zijn en/of ze doorgevoerd worden. Tot dusver zijn geen van de verwachte productiestoringen gesignaleerd.

Update 2 juli

De nieuwe instellingen werden niet actief op 1 juli; er is dus geen sprake van een big bang en op dit moment zijn er geen bekende productiestoringen hierdoor.

De volgende nieuwe limiet is aangezet en zal vanaf 5 juli verder doorgevoerd worden:

Naar verwachting wordt vanaf 12 juli de volgende bij elkaar horende restricties langzamerhand ingeschakeld over meerdere weken via een centrale aanpassing:

Voor de volgende veranderingen is nog geen geplande invoeringsdatum bekend. Die zal door Exact later bepaald worden:

Impact Invantive Producten

Op dit moment werken alle Invantive producten ongestoord. Er komt mogelijkerwijs een testomgeving waartegen de Invantive software gecertificeerd kan worden.

Op dit moment is niet voorspelbaar of en wanneer software down zal gaan. In verband met de vakantieperiode kan een downsituatie langere tijd duren.

Zodra meer informatie bekend is zal die hier gedeeld worden.

Het lokale script wat op onze PC is geïnstalleerd en geconfigureerd werkt nog gewoon (gelukkig). Dat script haalt data 1x per dag uit Exact Online en plaatst het in een eigen PostgreSQL database.

Moeten we hier wel iets nieuws voor bedenken of blijft het voorlopig goed gaan?

Er zijn nog weinig of geen veranderingen doorgevoerd door Exact Online. We hopen vandaag (6 juli) meer te horen over de uitrolfasering en welke onderdelen in productie genomen gaan worden, en of er een testvoorziening komt. Advies is voorlopig gewoon blijven gebruiken.

Update 6 juli

Niet meer dan 10 foutmeldingen per app, administratie, endpoint en uur

De volgende nieuwe limiet is aangezet op 5 juli en volledig ingeschakeld:

Een analyse is hiervan gemaakt. Volgens de laatste versie van de specificaties worden alleen 400 (Bad request), 401 (Unauthorized), 403 (Forbidden) en 404 (Not Found) HTTP statuscodes meegeteld. Busines errors die als HTTP 500, 503 of anders terugkomen tellen volgens de analyse niet mee. Het is niet geanalyseerd of bijvoorbeeld documentbijlages ophalen mee loopt in deze tellingen.

Incidenteel geeft Exact Online onterecht een bad request terug, maar met Invantive SQL zullen vooral 401 of 403 optreden: het verkrijgen van een nieuw accesstoken wordt maximaal uitgesteld, zowel voor de implicit grant flow als de code grant flow. Dit genereert maximaal 6 errors per uur. De logica zal aangepast worden via ITGEN-5408.

Maximaal 200 token endpoint calls

Naar verwachting wordt vanaf 12 juli de volgende bij elkaar horende restricties langzamerhand ingeschakeld over meerdere weken via een centrale aanpassing:

De invoering zal geleidelijk over de landen plaatsvinden.

Verplicht filter

Het verplichte filter als een sync API beschikbaar is zal via een gefaseerde uitrol vanaf medio juli ingeschakeld worden:

Overige

Voor de volgende wijzigingen is ons nog niet duidelijk wat er ingeschakeld is cq. wanneer dat ingeschakeld gaat worden:

Impact Invantive Producten

Op dit moment werken alle Invantive producten ongestoord. Er komt geen zinvolle testomgeving waartegen de Invantive software gecertificeerd kan worden.

Op dit moment is niet voorspelbaar of en wanneer software down zal gaan. In verband met de vakantieperiode kan een downsituatie langere tijd duren.

We houden rekening met een productiestop die voor een deel van de gebruikers tot 3 maanden na inschakelen laatste wijziging kan duren.

Zodra meer informatie bekend is zal die hier gedeeld worden.

Vraagje, inmiddels heeft Exact volgens mij de API aanpassingen doorgevoerd en dit heeft nu ook effect op de data die wij binnen krijgen op de SQL server via Data Replicator. Is er al enig zicht op hoeveel de impact is van de wijzigingen van Exact en wat de geschatte tijd is dat de koppeling met Exact weer actief is?

Volgens onze metingen is er nog niks ingeschakeld van de wijzigingen op 13 juli. Kun je voor een eventueel probleem een topic maken?

Zie:

Als het goed is, dan worden maandag aanstaande (19 juli 2021) een aantal van de wijzigingen in de Exact Online API’s ingeschakeld. Op een aantal applicaties van Invantive worden niet alle Exact Online API wijzigingen geactiveerd.

Op een aantal testapplicaties wordt de “mandatory filtering” ingeschakeld. Hier zal daarna mee getest worden. Na certificering zullen de applicaties uitgerold worden.

Op dit moment treden veelvuldig HTTP 599 errors op; die manifesteren zich bijvoorbeeld als itgenoda486, zie Onbekende HTTP statuscode 599 van Exact Online OData server (itgenoda114).

Op dit moment treden relatief vaak HTTP 408 Request Timeout errors op op Exact Online.

De wijzigingen zijn vandaag, 19 juli, niet doorgevoerd op Exact Online. Het blijft helaas onduidelijk of en wanneer er wijzigingen doorgevoerd zullen gaan worden. Om ruis te voorkomen zal er pas verdere berichtgevingen volgen zodra er wijzigingen doorgevoerd zijn en effect merkbaar mocht worden.

In een aantal Exact Online landen waaronder UK en BE wordt bij te vaak aanvragen via https://start.exactonline.TLD/api/oauth2/token van een access token met een refresh token nu een HTTP 400 (Bad Request) teruggegeven (alleen Code Grant Flow, deze beperking geldt niet voor de Implicit Grant Flow).

De payload bevat:

{ "error":"access_denied","error_description":"Rate limit exceeded: access_token not expired" }

In de HTTP header Reason staat dezelfde foutmelding, plus een foutcode TooEarlyToRefreshTokens:

TooEarlyToRefreshTokens: Rate limit exceeded: access_token not expired

Deze is nog niet opgenomen op in de documentatie.

In de HTTP header Retry-After staat een back-off tijd in seconden zoals 569 (9 minuten, 29 seconden).

Indien deze foutmelding optreedt, lijkt het geldige refresh token te vervallen en is het vernieuwen van autorisatie nodig.

Waar mogelijk zullen de Invantive-producten hier op aangepast worden. Het is niet duidelijk of en wanneer deze functionaliteit met deze beperkingen in België en/of Nederland gebruikt zal gaan worden. Het is ook niet bekend hoe de eigen apps van Exact Online bij gebruik op bijvoorbeeld meerdere telefoons voor één gebruiker hiermee omgaan.