Impact Exact Online API aanpassingen 1 juli 2021

Wiki (nl)
1

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.