Hoe maak ik een Exact Online API koppeling (met voorbeelden)?

Wiki (nl)
,
1

English version

Exact Online koppelingen

Een API koppeling met Exact Online zorgt voor het snel en efficiënt verwerken van gegevens uit andere systemen of Excel-sheets in je boekhouding. Een Exact Online API koppeling bespaart veel tijd en voorkomt fouten bij herhalende handelingen.

Exact Online heeft ruim 1.000 API’s, die allemaal via Invantive SQL toegankelijk zijn. Met Invantive SQL blijft de techniek onder de motorkap en kun je focussen op de functionaliteit dankzij SQL-statements die real-time omgezet worden in lees- en schrijfacties op Exact Online en ruim 70 andere (cloud)platformen.

Vaak worden ook Excel-bestanden gebruikt als bron van een API koppeling. De meeste gebruikers kunnen veel sneller een Excel-sheet klaarzetten dan stuk-voor-stuk bijvoorbeeld verkoopfacturen in te voeren met telkens vergelijkbare gegevens. Zowel interactief via de Excel add-in Invantive Control for Excel met Exact Online als via uploads op Get My Report en massaal via Invantive Data Hub kunnen Excel-bestanden ingelezen worden.

Hoe maak ik een Exact Online API koppeling?

Het maken van een API koppeling of meerdere API koppelingen tussen verschillende systemen waarbij ook Exact Online gekoppeld wordt kan op verschillende manieren:

  • REST API’s: de tabellen die beginnen met ExactOnlineREST zijn REST API’s.
  • XML API’s: de tabellen die beginnen met ExactOnlineXML zijn de XML API’s.

Zowel elke REST API als elke XML API is al vooraf gekoppeld als tabel. Hier is geen werk meer voor nodig binnen de Exact Online API koppeling.

Exact Online vormt de ene zijde van de API koppeling. Voor de andere zijde van de API koppeling kan gekozen worden uit ruim 70 platformen zoals verschillende Visma producten, maar ook Chargebee, ActiveCampaign, Teamleader, Yuki of AFAS. Ook voor al deze platformen geldt dat de API koppeling toegang heeft tot elke API: elke API is al vooraf gedefinieerd en getest, en meteen bruikbaar.

Een schematische weergave van het Exact Online datamodel is te vinden op:

Een doorzoekbaar overzicht van de beschikbare Exact Online tabellen op basis van de Exact Online API Documentation is te vinden op:

De meestgebruikte tabellen zijn te vinden in Aanbevolen en populaire Exact Online tabellen voor 2022.

Uitgewerkte voorbeelden van Exact Online API koppelingen

Voor veelvoorkomende combinaties met een Exact Online koppeling zijn al scripts voor API koppelingen beschikbaar. In geval van twijfel of een Exact Online koppeling al gecodeerd is, is het advies om hieronder een reactie achter te laten.

Een aantal populaire concrete voorbeelden van koppelingen met Exact Online met statements klaar om te draaien zijn:

Er zijn ook voorgedefinieerde API koppelingen zoals de volgende in Get My Report:

Handmatig of volledige automatisch

Het verwerken van gegevens met een Exact Online API koppeling kan op verschillende manieren: zowel handmatig als volledig automatisch is mogelijk. In het algemeen geldt dat het verstandiger is om met een handmatige Exact Online koppeling te beginnen als de processen en/of gegevens nog niet eerder geautomatiseerd verwerkt zijn. Als er weinig problemen zijn kan men volledig automatisch Exact Online koppelen.

Het is wel wenselijk om regelmatig de status van een volledig automatische koppeling te controleren. Dat kan via e-mails vanuit de koppelingen of door het nalezen van het verwerkingsverslag van de software.

Gegevens ophalen uit Exact

Het ophalen van gegevens uit Exact Online werkt meteen na het aanmelden op Exact Online met gebruikersnaam, wachtwoord en verificatiecode met bijvoorbeeld:

select *
from   ExactOnlineREST..Journals

op de Exact Online REST API of de gelijkwaardige Exact Online XML API maar met andere en meer veldnamen:

select *
from   ExactOnlineXML..Journals

Deze werkwijze is op alle producten hetzelfde. Deze werkwijze met select is naast voor een Exact Online koppeling ook voor de andere verschillende systemen hetzelfde.

Het uitwisselen van de gegevens met de koppeling tussen Exact Online en het andere platform kan met de insert, update en delete statements, maar synchroniseren gaat nog handiger met synchronize. Een voorbeeld van synchronize voor het koppelen van Exact Online en Visma.net Financials is te lezen in Synchronize Exact Online with Visma.net Financials. Na afloop van het synchronize statement zijn twee tabellen gesynchroniseerd qua inhoud. Het synchronize-statement zoekt zelf in een handomdraai uit welke mutaties nodig zijn en efficiënt verwerkt kunnen worden.

XML laden in Exact

Voor het snel laden van serieus grote aantallen transacties in Exact Online is de XML API aan te bevelen. Deze gebruikt heel weinig API calls en verwerkingstijd voor grote volumes, zoals aangetoond in ons onderzoek beschreven op Does Invantive SQL match the speed of Infinite Probability Drive?.

Het laden via de Exact Online XML API is wat bewerkelijker dan via de REST API en werkt via de tabel UploadXMLTopics. Een voorbeeld hiervan staat op Inlezen extra velden van Exact Online artikelen. Het koppelen kan voor tientallen soorten gegevens zoals journaalposten maken, facturen toevoegen, orders muteren, CRM-relaties laden en productinformatie voor productie laden.

Een goede test is om eerst met Get My Report via een upload module een Excel sheet met bijvoorbeeld 100.000 verkooporders te laden in Exact en te kijken of dit bevalt.

Transacties laden in Exact via REST API

Exact Online heeft een onhebbelijkheidje in de software. Het traditionele verschil tussen kop en regels bij transacties lijkt afwezig. Daarom moet bijvoorbeeld elke verkooporder minimaal een regel hebben. De XML API biedt altijd alle data in 1x aan. Voor de REST API vereist het laden van verkooporders, inkoop- en verkoopfacturen, bestellingen en boekstukken vereist daarom transactielogica. Een voorbeeld via de REST API is uitgewerkt in Create an Exact Online Sales Order with Details through REST Calls.

Meerdere Exact Online administraties

De meeste ondernemers hebben maar enkele Exact administraties in de boekhouding, maar grote accountants die Invantive gebruiken hebben vaak honderden of duizenden administraties waarvoor ze boekhouding voeren van honderden klanten. Vooral voor accountants is het nodig om de juiste administratie(s) te selecteren uit de boekhouding.

Standaard worden de gegevens van alle geselecteerde Exact Online administraties van het bedrijf onder elkaar gezet. Het veld Division (REST) of DIVISION_CODE bevat het unieke nummer van de Exact administratie. Het concept van administraties (“Divisions”) wordt verder uitgelegd in de rechterkolom van het API diagram.

De gewenste Exact administraties van de boekhouding voor de software koppeling selecteer je afhankelijk van het product:

API Performance

De API van een cloudapplicatie is langzamer dan het uitwisselen van gegevens met een apparaat op loopafstand. Toch zijn er ook gradaties; als we kijken over alle 1.000 gekoppelde API’s heen, dan meten we enorme snelheidsverschillen tussen grotendeels vergelijkbare API’s.

De snelste manier op dit moment om gegevens op te halen uit Exact Online zijn de sync API’s zoals beschreven op Snel en met minder API-calls Exact Online uitlezen met de incrementele "sync API"-tabellen.

Een algemeen onderzoek over de snelheid van verschillende manieren om Exact Online uit te lezen met een vergelijking tussen de Exact Online XML API, de Exact Online REST API, SQL Server en SQL Server met bulk uploads is te vinden op Does Invantive SQL match the speed of Infinite Probability Drive?.

Integratie van Power BI met Exact Online

Voor Power BI is er een voorgedefinieerde koppeling waarmee alle 1.000 beschikbare tabellen geïmporteerd kunnen worden in Power BI Desktop, Power BI Service en Power Query voor Excel. Deze Exact Online Power BI koppeling is te vinden op:

Een stappenplan voor het koppelen van Exact Online met Power BI is te vinden op:

Exact Online Consolideren met Excel

Specifiek voor de Windows-versie van Microsoft Excel is er een Exact Online Excel add-in. Hiermee kunnen met gewone Excel-formules de gegevens van Exact Online administraties verwerkt worden in Excel-bestanden. De meestgebruikte Excel formules voor Exact Online zijn te vinden op De meest populaire Exact Online Excel add-in formules. De software kan gedownload worden als MSI-bestand.

Integratie van Azure Data Factory met Exact Online

Voor Azure Data Factory is er een voorgedefinieerde koppeling voor het laden van alle 1.000 Exact Online tabellen in Azure Data Factory. Deze Exact Online Azure Data Factory koppeling is te vinden op:

Een stappenplan voor het koppelen van Exact Online met Azure Data Factory is te vinden op:

Exact Online API Status

Een koppeling met Exact Online vereist een stabiele Internetverbinding, maar ook de Exact Online API’s kunnen last hebben van storingen, variërend van een trage werking tot gewoon volledig onbereikbaar zijn. De status van de Exact Online API’s kan opgevraagd worden met de tips beschreven op Hoe vraag ik de status van een Exact Online storing op?.

De Exact Online API status is ook deels te raadplegen via de Invantive Statuspagina; zie Statuspagina uitgebreid met doorvoersnelheid en Exact Online metingen.

Voorkom Storingen door Exact Online API Aanpassingen

De API ondergaat doorlopend wijzigingen. Dit leidt nogal eens tot onverwachte storingen in een API koppeling. Soms wordt de oorzaak van een storing automatisch opgelost na een paar dagen omdat iemand anders geklaagd heeft. Maar soms is het ook nodig om zelf contact op te nemen met Exact Online API Support. Bij gebruik van Invantive SQL zal dit normaliter zelden nodig zijn omdat voor de meestvoorkomende problemen al oplossingen onder de motorkap verwerkt zijn.

Een aantal factoren om rekening mee te houden bij het maken van Exact Online API koppelingen staan beschreven bij Impact Exact Online API aanpassingen 1 juli 2021. Hiermee vooraf rekeninghouden voorkomt fouten en verkleint de kans op storingen in API koppelingen.

Rechten en Scoping

De Exact Online API heeft als je hem zelf volledig moet aansturen voor zowel accountants als ondernemers veel nuances qua rechten en zogenaamde “scoping”.

De rechten op een API van een gebruiker zijn te bepalen met de tips op Exact Online API rechten van een user op specifieke endpoint - 2 van forums.

Dit zijn grofweg de rechten die een gebruiker ook op start.exactonline.nl terugziet, maar elke API vereist een zogenaamd “OAuth app”. De OAuth app is te registreren door een Exact Online gebruiker met “Abonnement beheren”-rechten via https://apps.exactonline.com.

Er wordt onderscheid gemaakt tussen eigen en gepubliceerde apps. Een zelfgeregistreerde app geeft alleen toegang tot de eigen administraties, en heeft geen last van de onder beschreven “data scoping” en “division scoping”. De rechten van gebruikers worden wel toegepast.

Een voorbeeld van de registratie van een eigen app voor on-premises gebruik staat beschreven in Registratie Exact Online app voor gebruik met Invantive Control for Excel, terwijl een voorbeeld voor een web app te vinden is in Registratie Exact Online app voor gebruik met Invantive Cloud.

Een gepubliceerde app kan na goedkeuring door een gebruiker van een willekeurige administratie gegevens uitwisselen met deze administratie.

De rechten voor gegevensuitwisselingen worden beperkt door:

  • data scoping: gepubliceerde apps hebben alleen toegang tot gegevenselementen waarvan de uitgever aangegeven heeft dat ze nodig zijn (let op: bevat beveiligingsgaten)
  • division scoping: gepubliceerde apps hebben alleen toegang tot administraties die de gebruiker geselecteerd heeft.

Zowel data als division scoping zijn relatief gevoelig voor bugs aan de Exact Online. Het is ook relatief lastig om alle variaties vooraf goed te testen en bovendien een logisch samenwerkend geheel op te bouwen.

API Gebruik Beveiligen

Gedurende de tijd kunnen steeds meer API’s gekoppeld worden en mogelijkerwijs buiten beeld vallen. Exact laat niet-gebruikte refresh tokens (applicatie-specifieke wachtwoorden) daarom na enige tijd vervallen, maar het is toch verstandig om regelmatig te kijken welke apps en koppelingen allemaal draaien. De gebruikte apps en koppelingen zijn terug te vinden zoals beschreven op Hoe zie ik welke Exact Online apps wij gebruiken?.

Het intrekken van rechten op een Exact app / koppelingen kan vanuit de Exact website zoals beschreven op Hoe trek ik de app rechten in voor Exact Online?.

Hulp nodig?

Heeft u hulp nodig? Laat dan een vraag achter op de site https://forums.invantive.com of neem telefonisch of per e-mail contact op met Invantive. Invantive kan ook voor u de Exact-koppeling configureren op basis van de reeds beschikbare koppelingen.