API koppeling laten maken: van twee API's naar één werkende stroom

Stuur ons de namen van de twee systemen

Voor een API koppeling heb je in het begin weinig meer nodig dan de namen van de systemen. Wat een API toelaat staat in de documentatie van de leverancier, en dat zoeken wij uit. Per API zijn het steeds dezelfde zes vragen:

De laatste vraag is de belangrijkste. Business Central heeft een uitgebreide standaard-API, maar item.inventory is één getal over alle locaties. Wie voorraad per magazijn nodig heeft, publiceert in Business Central een eigen pagina of query als webservice. Dat weet je voordat je begint, of je ontdekt het halverwege. Wat een API in het algemeen wel en niet regelt, staat in wat is een API koppeling.

Wat een API wel en niet regelt

Een API geeft toegang tot de gegevens van één systeem, in de vorm die dat systeem kiest. Hij regelt niet welk systeem leidend is, hoe een klant in het ene systeem dezelfde klant in het andere is, en wat er gebeurt als een aanroep halverwege mislukt. Drie voorbeelden uit de documentatie van leveranciers:

• De API zegt niet dat er meer is. Een GetConnector van AFAS zonder skip en take geeft de eerste 100 regels terug, zonder melding dat er meer zijn. Magento doet het omgekeerde: zonder pageSize komen alle resultaten in één antwoord.
• Een standaardwaarde die stil iets invult. Moneybird gebruikt het standaardtarief van de administratie als een factuurregel geen btw-tarief meekrijgt. Een regel met 9% wordt dan zonder foutmelding een regel met 21%.
• Een sleutel die anders werkt dan hij eruitziet. De debiteurcode in Exact Online is 18 posities lang met spaties aan de voorkant. Een filter op 10432 vindt niets, en een koppeling die dat niet weet maakt een tweede debiteur aan.

Daarom is het werk aan een API koppeling voor een groot deel mapping: per veld vastleggen waar het vandaan komt, hoe het wordt omgezet en wat er gebeurt met een waarde die nergens past. Dat staat uitgewerkt in wat is veldmapping.

Hoe een systeem een wijziging meldt

Er zijn drie manieren. Een webhook: het systeem stuurt zelf een bericht. Een sync-endpoint: je vraagt alles wat nieuwer is dan de vorige keer. Of zelf vragen, op een vast moment, met een filter op een datum. Elk systeem doet het anders, en bij een webhook verschilt vooral wat er gebeurt als de ontvanger even niet bereikbaar is.

Een storing van 6 uur, doorgerekend. Een Shopify-shop met 300 orders per dag krijgt er gemiddeld 12,5 per uur. Ligt de ontvangende kant 6 uur plat, dan gaan er 6 x 12,5 = 75 orders verloren als de koppeling alleen op webhooks draait. De eerste berichten geeft Shopify na 4 uur op, en daarna is het abonnement weg, dus ook de orders van uur 5 en 6 komen niet. Daarom haalt de koppeling naast de webhook op een vast moment alle orders op die sinds de vorige controle zijn gewijzigd, en zet hij het abonnement opnieuw op als het verdwenen is. De 75 orders staan dan bij de eerstvolgende controle alsnog in het ERP.

Ook een sync-endpoint heeft een uitzondering. Exact Online zet de Timestamp-waarden opnieuw als een administratie naar een andere database is verhuisd; de documentatie raadt dan aan alles opnieuw te synchroniseren. De koppeling controleert daarvoor de DivisionMoveDate. Meer over de werking staat in wat is een webhook.

Toegang, tokens en wie ze uitgeeft

Elke API heeft een eigen manier van inloggen, en bij elk systeem moet iemand aan de kant van de klant iets aanmaken of goedkeuren. Wat er dan verloopt en wanneer, verschilt sterk:

Drie van deze sleutels zie je maar één keer: het Consumer Secret van WooCommerce, het token van een AFAS app connector en het API-token van e-Boekhouden. Wie het scherm sluit zonder te kopiëren, maakt een nieuwe aan.

Het token van Exact Online, doorgerekend. Een access token is 10 minuten geldig. Een koppeling die de hele dag draait, ververst het 24 x 60 / 10 = 144 keer per dag. Bij elke verversing komt er een nieuw refresh token en vervalt het oude direct. Verversen twee processen tegelijk, dan bewaart één van de twee een token dat al vervallen is, en geeft elk volgend verzoek een 401. Bij ons ververst één proces het token en lezen de andere het uit dezelfde opslag. Meer over Exact staat op Exact Online koppeling.

Kleine verschillen die veel tijd kosten

Het voorbeeld van WooCommerce in getallen: btw over € 4,13 is € 0,8673. Op 2 decimalen wordt dat € 0,87, en 0,87 / 4,13 = 21,07%. Een boekhoudpakket dat het tarief uit de bedragen afleidt, herkent dat niet als het hoge tarief. Met dp=4 is het 0,8673 / 4,13 = 21,00%. Meer voorbeelden staan bij bedragen en btw mappen.

Welke limieten de systemen hebben en wat dat betekent voor de doorvoer, staat in wat is een rate limit. Exact Online staat 60 verzoeken per minuut en 5.000 per dag toe, Business Central online 6.000 per 5 minuten per gebruiker, Moneybird 150 per 5 minuten per IP-adres.

Veiligheid van de verbinding

Een API koppeling is een deur tussen twee systemen. Wat erdoor mag, leg je vast bij de toegang, niet in de koppeling zelf.

• Alleen de rechten die nodig zijn. In AFAS kan de koppeling alleen de connectoren aanroepen die de beheerder in de app connector heeft gezet. Moneybird werkt met scopes per soort gegevens, bijvoorbeeld sales_invoices. Shopify geeft standaard alleen orders van de laatste 60 dagen; voor oudere orders moet read_all_orders apart worden aangevraagd.
• Een vast IP-adres. AFAS laat de beheerder per app connector vastleggen vanaf welke adressen aanroepen mogen. Een aanroep van een ander adres krijgt een 403.
• Berichten controleren voordat ze worden verwerkt. WooCommerce zet een HMAC-SHA256 over het bericht in X-WC-Webhook-Signature, Exact Online in HashCode, Picqer in X-Picqer-Signature. Een bericht met een handtekening die niet klopt, verwerkt de koppeling niet.
• Alleen over HTTPS. WooCommerce accepteert de sleutels via HTTP alleen met een OAuth-handtekening per verzoek; over HTTPS gaan ze als basic authentication. Wij koppelen alleen over HTTPS.
• Sleutels apart van de code. Een sleutel die vervangen moet worden, bijvoorbeeld als een medewerker vertrekt, wordt vervangen zonder de koppeling opnieuw te bouwen.

Wat je krijgt

Wij bouwen de koppeling voor een vaste prijs op de API's van jouw systemen. Daarna hosten, draaien en bewaken wij hem voor een vast bedrag per maand. Hoe die twee delen zijn opgebouwd staat op koppeling laten bouwen.

• Een wachtrij met herhalingen, zodat een 429 of een storing geen gegevens kost, en elke order één keer aankomt.
• Een controlelijst voor wat de validatie niet haalt, met de oorspronkelijke inhoud en de reden.
• Een dashboard met eigen login, met per run wat er is verwerkt en wat er is gewijzigd.
• Dry run en goedkeuring voordat er iets wordt weggeschreven.
• Aanpassing als een API verandert, zoals een nieuwe versie bij Shopify of de overstap naar OAuth bij AFAS.

Gaat het om één soort systeem, kijk dan bij ERP koppeling met je webshop of webshop koppeling laten maken. Alle stromen staan op koppelingen. Stuur de namen van je twee systemen, dan hoor je wat hun API's toelaten en waar het werk zit.