API-koppeling voor uw webshop en webhooks: voorraad en bestellingen synchroniseren met uw ERP

Uw webshop staat niet alleen. De voorraad beweegt in de winkel, de boekhouding wacht op de bestellingen en een ERP of marktplaats moet de juiste prijzen tonen. Om die programma's met elkaar te laten praten zonder alles opnieuw in te tikken, hebt u een API-koppeling en webhooks nodig. Deze gids legt uit waarvoor ze dienen, wat de API van Eazyclick kan, wat ze nog niet dekt en hoe u een voorraad met een ERP synchroniseert.

In het kort

• Een webshop-API laat een ander programma de producten, de voorraad en de bestellingen van uw webshop lezen en wijzigen.
• Een webhook verwittigt dat programma zodra er iets gebeurt, zonder dat het de webshop voortdurend moet bevragen.
• De API van Eazyclick (v1) dekt producten, voorraad en bestellingen, met lees- of schrijfsleutels.
• Twee ondertekende webhooks: order.placed (bestelling geplaatst) en stock.updated (voorraad gewijzigd).
• Gepubliceerde limieten: 120 verzoeken per minuut om te lezen en 30 om te schrijven, per sleutel.

Wat is een API-koppeling voor een webshop?

Een API-koppeling is een technische toegangspoort tot uw webshop. Ze laat een ander programma, zoals een ERP of een marktplaats, de catalogus, de voorraad en de bestellingen lezen en soms wijzigen, zonder langs het beheerscherm te gaan. De gegevens worden uitgewisseld in JSON, via HTTP-verzoeken die met een sleutel beveiligd zijn.

Concreet bespaart een API u manuele CSV-exports en dubbel typwerk. Een ontwikkelaar of uw integrator schrijft de koppeling tussen beide programma's één keer, daarna stromen de gegevens vanzelf. Dat noemt men een integratie of een API-koppeling.

API of webhook: wat is het verschil?

De API en de webhook werken in tegengestelde richting. Met de API stelt uw programma een vraag aan de webshop wanneer het dat nodig heeft, bijvoorbeeld "wat is de voorraad van dit product?". Met een webhook verwittigt de webshop uw programma zodra er iets gebeurt, zoals een nieuwe bestelling. Een goede synchronisatie combineert beide.

Wat de API van Eazyclick kan

De open API van Eazyclick, versie 1, dekt drie onderdelen van de webshop: producten met hun varianten, voorraad en bestellingen. Producten kunt u lezen, aanmaken en wijzigen. De voorraad kunt u lezen, instellen en voorraadbewegingen doorgeven. Bestellingen kunt u lezen, ook op datum van wijziging. De API hoort bij de module Webshop.

Wat versie 1 niet dekt, zodat u niet voor verrassingen staat:

• Klanten, CRM en facturen zijn niet beschikbaar via de API.
• De voorraad per winkel: de API geeft de voorraad van elke variant over alle locaties samen, zonder opsplitsing per winkel.
• Kassaverkopen komen binnen via de webhook order.placed, maar zijn niet te lezen via GET /orders.
• Er is geen kant-en-klare connector voor een bepaald ERP: met de API en de webhooks kunt u er een bouwen.

Lees- en schrijfsleutels

U krijgt toegang tot de API met een sleutel uit de instellingen van de webshop. Een leessleutel raadpleegt de gegevens, een schrijfsleutel kan ook producten aanmaken en de voorraad instellen. De sleutel wordt maar één keer getoond, is met één klik in te trekken en handelt in naam van de accounteigenaar, die elke wijziging in het logboek ziet.

Enkele regels van gezond verstand:

• Eén sleutel per integratie: trekt u de toegang van een dienstverlener in, dan sluit u alleen hem af.
• De kleinste toegang die volstaat: een prijsvergelijker heeft genoeg aan lezen.
• De sleutel blijft op een server, nooit in een webpagina of in een coderepository: hij geeft toegang tot de bestellingen en adressen van uw klanten.

Ondertekende webhooks: order.placed en stock.updated

Eazyclick stuurt twee gebeurtenissen naar het adres van uw keuze. order.placed vertrekt bij elke geplaatste bestelling, online of aan de kassa. stock.updated vertrekt zodra de voorraad van een variant verandert, door een verkoop, een wijziging via de API of een correctie in de back-office. Elke verzending is ondertekend, zodat uw server kan nagaan dat ze echt van Eazyclick komt.

• HMAC-SHA256-handtekening in de header Eazyclick-Signature, berekend op het tijdstempel en de ruwe inhoud met het geheim van het ontvangstpunt. Weiger een tijdstempel ouder dan 5 minuten.
• Vaste gebeurtenis-ID (Eazyclick-Event-Id): dezelfde gebeurtenis kan twee keer aankomen, ontdubbel op die ID.
• Automatische nieuwe poging als uw server niet antwoordt: na 1 minuut, 5 minuten, 30 minuten, 2 uur en 6 uur, of 6 pogingen over 8 uur en 36 minuten.
• Verzendlogboek, opnieuw versturen en een knop "Testen" in de back-office, om een integratie te controleren zonder op een echte bestelling te wachten.

Limieten en paginering

De API past gepubliceerde limieten toe, per sleutel en per minuut: 120 verzoeken om te lezen en 30 om te schrijven, apart geteld. Daarboven antwoordt ze 429 rate_limited met de header Retry-After, die aangeeft hoeveel seconden u moet wachten. Lijsten overloopt u per pagina van maximaal 100 elementen, en alle bedragen staan in hele centen.

Die limieten laten ruim marge voor een normale synchronisatie. De documentatie raadt webhooks aan voor realtime, een inhaalronde voor bestellingen om de 5 tot 15 minuten, een nieuwe lezing van de catalogus elk uur en een volledige voorraadcontrole elke nacht. Dat ritme past ruim binnen de 120 leesverzoeken per minuut.

Voorbeeld: de voorraad synchroniseren met een ERP

Om een ERP of een ander kassasysteem met de webshop te synchroniseren, blijft Eazyclick de bron van waarheid voor de voorraad. Het ERP laadt eerst de catalogus, krijgt daarna elke voorraadbeweging en elke bestelling via webhook, meldt zijn eigen verkopen via de API en controleert alles elke nacht. Eén lees- en schrijfsleutel volstaat voor het hele scenario.

1. Eerste lading: GET /products, pagina per pagina, met de varianten gekoppeld op SKU.
2. Voorraad in realtime: abonnement op stock.updated, meteen toegepast.
3. Bestellingen: order.placed in realtime, plus GET /orders?updatedAfter=… om de 5 tot 15 minuten om een gemiste verzending in te halen.
4. Verkopen buiten Eazyclick: POST /variants/{variantId}/stock-movements bij elke verkoop.
5. Controle: GET /stock elke nacht, vergeleken met de database van het ERP.

Twijfelt u nog over de keuze van een ERP? Onze gids over ERP voor kmo's en onze vergelijking Odoo of Eazyclick zetten de opties op een rij. Voor een zaak met meerdere winkels toont de pagina Software voor meerdere winkels hoe de voorraad, het kassasysteem en de webshop samenwerken.

Documentatie en OpenAPI-specificatie

De documentatie van de API is openbaar, in het Frans en het Engels, en wordt rechtstreeks uit de code van de API gegenereerd: elk getal dat u ziet, is het getal dat de API toepast. Ze bevat een startgids, authenticatie, paginering en fouten, limieten, synchronisatieritme, webhooks met controlevoorbeelden in Node, PHP en Python, en de volledige referentie.

• API-documentatie in het Engels
• API-documentatie in het Frans
• OpenAPI-specificatie, te importeren in Postman, Insomnia of een clientgenerator.

De tools die al aan de modules gekoppeld zijn, vindt u op de pagina Integraties.

Veelgestelde vragen

Zit de API inbegrepen in Eazyclick?

De open API hoort bij de module Webshop: ze wordt samen met die module geactiveerd, zonder aparte module. Sleutels en webhooks stelt u in bij de instellingen van de webshop. Zonder de module Webshop is de API niet beschikbaar, omdat ze over de producten, de voorraad en de bestellingen van de webshop gaat.

Bestaat er een kant-en-klare koppeling met mijn ERP?

Nee. Eazyclick levert geen kant-en-klare connector voor een bepaald ERP. De API en de webhooks bieden alles om er een te schrijven: catalogus laden, voorraad in realtime, bestellingen en externe verkopen. Uw ontwikkelaar of de integrator van uw ERP kan zich baseren op de documentatie en de OpenAPI-specificatie om de koppeling te bouwen.

Kunt u klanten of facturen lezen via de API?

Niet in versie 1. De API dekt producten, varianten, voorraad en bestellingen. Klantenfiches, CRM-gegevens en facturen zijn niet beschikbaar. Een bestelling bevat wel het e-mailadres, de naam en de adressen die nodig zijn om ze te verwerken, en dat volstaat voor de meeste synchronisaties van logistiek en voorraad.

Wat gebeurt er als mijn server onbereikbaar is?

De webhooks worden automatisch opnieuw verstuurd: zes pogingen in totaal, na 1 minuut, 5 minuten, 30 minuten, 2 uur en 6 uur. Na de laatste blijft de verzending zichtbaar in het logboek van de back-office en kunt u ze met één klik opnieuw versturen. Voor onlinebestellingen haalt een regelmatige lezing met updatedAfter een gemiste gebeurtenis ook in.

Krijgt u de voorraad per winkel?

Nog niet via de API. Versie 1 geeft per variant de totale voorraad van de webshop, over alle voorraadlocaties samen: aanwezige, gereserveerde en beschikbare hoeveelheid. De back-office beheert wel al een voorraad per winkel. Hebt u die opsplitsing in de API nodig, laat het ons weten: zo'n toevoeging kan zonder breuk met versie 1.