Exact Online koppeling met je webshop: houd Exact, koppel de rest

Wat is Exact Online en welke variant heb je?

Exact Online is het online boekhoud- en ERP-pakket van Exact, veel gebruikt in het Nederlandse mkb. Het bestaat uit pakketten per soort bedrijf, waaronder Boekhouden, Handel en Productie, elk in meerdere edities. Voor een koppeling is dat de eerste vraag, want de API geeft per resource aan in welk pakket hij werkt. De on-premise voorganger die bij veel groothandels draait is een ander product met een andere techniek: zie Exact Globe koppeling.

De documentatie gebruikt de Engelse pakketnamen: Accounting voor Boekhouden, Wholesale & Distribution voor Handel, Manufacturing voor Productie. Met Boekhouden kan een webshoporder dus als factuur of boeking landen en niet als verkooporder. Voorraad per magazijn via ItemWarehouses vraagt een van de drie hoogste edities.

Wat je met Exact Online koppelt

In de meeste koppelingen is Exact Online leidend voor artikelen, voorraad en prijzen, en de webshop voor orders en nieuwe klanten. Per stroom ligt vast welke kant de waarheid heeft; dat principe staat uitgewerkt op ERP koppeling met je webshop.

Een verkooporder heeft twee verplichte onderdelen: OrderedBy, de klant als GUID, en minstens één orderregel met Item, het artikel als GUID. De rest is mapping. Zo ziet het verzoek eruit voor order 10482 van Bakker Installatie B.V.:

POST /api/v1/1234567/salesorder/SalesOrders HTTP/1.1
Host: start.exactonline.nl
Authorization: Bearer eyJ0eXAi...
Content-Type: application/json

{
  "OrderedBy": "8f3c1e52-7a40-4c1b-9d2e-5b1f0a6c3e77",
  "YourRef": "WEB-10482",
  "Description": "Webshoporder 10482",
  "PaymentCondition": "30",
  "SalesOrderLines": [
    {
      "Item": "b1d7a0c4-2f6e-4e0a-8c11-93a4d5e6f012",
      "Quantity": 12, "NetPrice": 17.08, "VATCode": "4"
    }
  ]
}

Het getal 1234567 in het pad is de divisie: het nummer van de administratie. VATCode en PaymentCondition zijn codes uit jouw administratie, geen percentages of dagen. In dit voorbeeld staat 4 voor 21% exclusief; in een andere administratie kan dat een andere code zijn.

Naast de webshop hangen aan dezelfde administratie vaak een magazijnsysteem, een verzendplatform en een marktplaats. Voor Picqer staat dat op Picqer Exact Online koppeling. Welke velden per stroom meegaan staat op orders, klanten en verzending en voorraad en beschikbaarheid.

Hoe Exact Online data vrijgeeft

REST API met een divisie in elk pad

Exact Online heeft een REST API op basis van OData, met JSON als antwoord. Elk pad begint met /api/v1/{division}/. Een koppeling die het verkeerde divisienummer gebruikt, boekt zonder foutmelding in een andere administratie waar dezelfde gebruiker rechten op heeft. Het nummer van de actieve administratie komt uit /api/v1/current/Me. Wij leggen de divisie per koppeling vast en controleren hem bij elke start.

Inloggen met OAuth 2.0

De koppeling krijgt toegang via OAuth 2.0. Een beheerder van de administratie logt één keer in bij Exact en geeft toestemming; het wachtwoord komt niet bij de koppeling terecht en de toestemming is in Exact weer in te trekken. Voor de tokens gelden vaste regels:

• Een access token is 600 seconden geldig, dus 10 minuten.
• Een nieuw access token is pas op te vragen 9 minuten en 30 seconden na het vorige. Eerder vragen geeft een 401.
• Bij elke verversing komt er een nieuw refresh token en vervalt het oude direct.
• Een refresh token is 30 dagen geldig. Staat de koppeling langer stil, dan moet de beheerder opnieuw toestemming geven.

Het derde punt is waar zelfgebouwde scripts op breken. Twee processen die tegelijk verversen krijgen elk een antwoord, en één van de twee bewaart een token dat al vervallen is. Daarna geeft elk verzoek een 401. Bij ons ververst één proces het token en lezen alle andere het uit dezelfde opslag.

De limieten: 60 per minuut, 5.000 per dag

Per app en per administratie staat Exact Online 60 verzoeken per minuut en 5.000 per dag toe. Wat erboven komt krijgt HTTP 429. Elk antwoord draagt vijf headers, waaronder X-RateLimit-Remaining voor wat er die dag nog over is en X-RateLimit-Minutely-Remaining voor de lopende minuut. De volledige regeling staat in de documentatie van Exact over API-limieten.

Een gewoon endpoint geeft 60 records per pagina. De bulk- en sync-endpoints geven er 1.000 en Exact raadt de sync-endpoints aan. Een sync-endpoint onthoudt niets voor je: de koppeling bewaart de hoogste Timestamp uit het vorige antwoord en vraagt daarna alleen wat nieuwer is. Dat verschil bepaalt het hele ontwerp:

• 12.000 artikelen ophalen via logistics/Items kost 12.000 / 60 = 200 verzoeken.
• Dezelfde 12.000 artikelen via sync/Logistics/Items kost 12 verzoeken, en bij de volgende ronde 1 verzoek voor alleen de wijzigingen.
• De voorraad per artikel opvragen via read/logistics/StockPosition kost 1 verzoek per artikel: 12.000 verzoeken, ruim twee dagbudgetten voor één ronde.

Een dagindeling die past, met een voorraadronde elke 5 minuten en een ronde voor artikelen, prijzen en relaties elk uur:

De 4 verzoeken per order zijn: debiteur zoeken, order aanmaken, levering ophalen en factuur ophalen. Voor orders blijft 5.000 - 360 = 4.640 over, dus het plafond ligt bij 4.640 / 4 = 1.160 orders per dag. Op een piekdag met 1.100 orders is er nog ruimte voor 240 verzoeken.

Ligt je piek hoger, dan gaat het aantal verzoeken per order omlaag: debiteuren uit de eigen opzoektabel in plaats van uit Exact, leveringen via de webhook in plaats van een vraag per order. De rekenmethode staat in Exact Online API limieten.

Webhooks voor een deel van de gegevens

Exact Online verstuurt webhooks voor onder meer SalesOrders, SalesInvoices, Items, Accounts, StockPositions en GoodsDeliveries. Het bericht bevat een verwijzing en een HashCode, een HMAC-SHA256 over de inhoud waarmee de ontvanger controleert dat het van Exact komt. De gegevens zelf haalt de koppeling daarna op, en dat verzoek telt mee voor het dagbudget. Een bericht dat niet aankomt probeert Exact 10 keer opnieuw, verspreid over 34 uur. Meer over die werking staat in wat is een webhook.

Waar het bij Exact Online op vastloopt

Debiteuren, btw-codes en dagboeken

De debiteurcode in crm/Accounts is een tekenreeks van 18 posities, aangevuld met spaties aan de voorkant. Een filter moet die spaties bevatten, anders komt er een leeg antwoord terug en maakt een onoplettende koppeling een tweede debiteur aan. Het enige verplichte veld bij een nieuwe relatie is Name. Btw-nummer, factuuradres en betalingsconditie moeten dus bewust gemapt worden, want Exact vraagt er niet om.

Btw-codes, dagboeken en grootboekrekeningen verschillen per administratie. Een webshop kent een percentage, Exact een code. Verkopen aan zakelijke klanten in de EU, btw verlegd en verzendkosten hebben elk een eigen code nodig. De achtergrond staat in bedragen en btw mappen.

Artikelen: één code, één afbeelding, geen varianten

De artikelresource heeft geen veld voor een hoofdartikel met varianten. Elke maat en kleur is een eigen artikel met een eigen code. De koppeling groepeert ze voor de webshop op een afgesproken kenmerk, bijvoorbeeld een vrij veld of een deel van de artikelcode. Een artikel heeft één afbeelding (PictureUrl), een omschrijving van 60 tekens en een extra omschrijving van 255. Productteksten en extra beelden komen daarom meestal uit de webshop of een PIM; zie productdata.

Voorraad: welk getal

StockPositions geeft per artikel en magazijn onder meer CurrentStock, ReservedStock, PlanningIn, PlanningOut en FreeStock. Welk getal naar de webshop gaat is een keuze per koppeling: 20 op voorraad met 6 gepland uit is 14 verkoopbaar. Bij meer dan één magazijn komt de vraag erbij welke magazijnen meetellen; zie meerdere magazijnen.

Fouten tellen mee

Exact staat per app, gebruiker, administratie en endpoint 10 fouten per uur toe. Daarboven wordt de sleutel tijdelijk geblokkeerd, en bij herhaling duurt de blokkade langer. Een koppeling die een order met een onbekend artikel blijft insturen, legt zo ook de goede orders stil. Daarom valideren wij elke order voor verzending: bestaat de debiteur, bestaat elk artikel, is er een btw-code. Wat niet door de controle komt gaat naar een controlelijst in het dashboard en niet naar Exact. Een afgeronde verkooporder is via de API niet meer te wijzigen; een wijziging uit de webshop na levering wordt dan een taak voor een medewerker.

Platformen die we aan Exact Online koppelen

De koppeling wordt gebouwd op jouw administratie en jouw webshop. De eigenschappen per combinatie staan op een eigen pagina:

• WooCommerce Exact Online koppeling
• Shopify Exact Online koppeling
• Magento Exact Online koppeling
• Shopware Exact Online koppeling
• Lightspeed Exact Online koppeling
• CCV Shop Exact Online koppeling
• Picqer Exact Online koppeling

De platformen zelf staan op WooCommerce koppeling en Shopify koppeling. Draai je een ander ERP naast of in plaats van Exact, zie dan AFAS webshop koppeling en Business Central koppeling. Het overzicht van alle stromen en systemen staat op koppelingen.

Wij bouwen de koppeling voor een vaste prijs, en hosten, draaien en bewaken hem daarna voor een vast bedrag per maand. Voor de livegang draait hij als dry run: je ziet per order en per artikel wat er naar Exact zou gaan, zonder dat er iets geboekt wordt. Vertel welk pakket en welke webshop je hebt, dan hoor je welke stromen in jouw editie kunnen en wat het dagbudget voor jouw aantallen betekent.