Begin bij de betekenis van de aanvraag.
Zoek je een concrete aansluiting? Bekijk de uitwerkingen voor Sendcloud, Exact en AFAS, Mollie, Adyen en Stripe of Odoo en Salesforce. Daar komen ook inrichting en ingebruikname aan bod.
Een API is een afgesproken manier waarop software informatie opvraagt of een bewerking laat uitvoeren. Bij logistieke koppelingen gaat de belangrijkste afspraak vaak over betekenis: wat heeft het ontvangende systeem precies toegezegd wanneer het antwoord geeft? Een ontvangstbevestiging kan betekenen dat een bericht is opgeslagen, dat een order is gevalideerd of dat een voorraadmutatie definitief is verwerkt.
Leg per bewerking vast welke stap is afgerond. Maak bij verwerking op de achtergrond een status opvraagbaar, bijvoorbeeld via een verwerkingsnummer. Een technisch geaccepteerd verzoek mag op een scanner nog niet als definitieve voorraadboeking verschijnen. Spreek ook af hoe een latere afwijzing de medewerker bereikt.
Beschrijf in het contract de artikel- en orderidentiteit, eigenaar van de voorraad, eenheden, verplichte velden en toegestane wijzigingen. Een hoeveelheid van twaalf zonder eenheid is geen bruikbare logistieke afspraak. Bepaal eerst de systeemrollen met onze gids over WMS, TMS en ERP koppelen.
Geef de handeling een eigen identiteit.
Bij idempotent verwerken heeft herhaling van dezelfde bedoelde handeling geen extra bedrijfseffect. De technische aanvraag kan meerdere keren aankomen, terwijl er één transportopdracht ontstaat. Gebruik daarvoor een blijvende identificatie voor de handeling en hergebruik die bij een technische herhaling. Een bewust nieuwe opdracht krijgt een nieuwe identificatie.
Onderstaand fictief bericht illustreert een contract. De veldnamen zijn ontwerpkeuzes, geen API van een leverancier.
{
"operationId": "op-7842",
"orderId": "ORD-1048",
"shipmentId": "SHP-1048-2",
"palletCount": 4
}De ontvanger bewaart de identificatie binnen de juiste klant- of afzendercontext, samen met het resultaat en de mutatie. Die opslag moet één samenhangende transactie vormen en ook gelijktijdige herhalingen opvangen. Alleen vooraf zoeken of het nummer al bestaat, laat ruimte voor twee gelijktijdige verzoeken.
Leg vast wat er gebeurt als dezelfde identificatie met een andere inhoud terugkomt: bijvoorbeeld afwijzen als contractfout. Bepaal ook hoe lang een verwerkingsresultaat beschikbaar blijft. Na het verlopen van die afspraak is opnieuw insturen niet vanzelf veilig. Het ordernummer alleen is vaak te grof: één order kan meerdere legitieme deelzendingen hebben.
Herhaal alleen als dat iets kan oplossen.
Een retry is een nieuwe poging na een mislukte aanroep. Een korte netwerkstoring kan verdwijnen; een onbekende artikelcode meestal niet. Maak daarom onderscheid tussen tijdelijk niet beschikbaar, inhoudelijk afgewezen en onbekende uitkomst. Gebruik het afgesproken foutcontract, niet uitsluitend de HTTP-statuscode, om de vervolgstap te kiezen.
Begrens het aantal pogingen en de totale wachttijd. Laat de tussenpozen oplopen en voeg enige spreiding toe, zodat veel terminals niet gelijktijdig opnieuw proberen. Respecteer een door de ontvanger opgegeven wachttijd. Voorkom ook dat zowel de scanner, tussenlaag als achtergrondwerker dezelfde handeling onbeperkt blijft herhalen.
| Situatie | Passende vervolgstap | Wat ziet de gebruiker? |
|---|---|---|
| Onbekend artikel | Gegevens herstellen; niet blind herhalen. | Afgewezen met een concrete reden. |
| Tijdelijk niet beschikbaar | Begrensd herhalen als de bewerking dat veilig ondersteunt. | Wacht op verwerking. |
| Timeout na verzenden | Resultaat opvragen of met dezelfde identificatie veilig herhalen. | Uitkomst nog niet bevestigd. |
| Identificatie hergebruikt met andere inhoud | Afzonderlijk beoordelen als contractfout. | Aandacht nodig; geen tweede boeking. |
Ondersteunt een pakket geen idempotente bewerking of betrouwbare resultaatcontrole? Dan kun je die zekerheid niet met een eigen sleutel aan de buitenkant alsnog afdwingen. Houd de uitkomst zichtbaar en laat bij twijfel eerst de bestaande opdracht controleren voordat iemand opnieuw verzendt.
Ontwerp ook de terugmelding.
Een webhook is een bericht dat een systeem naar jouw toepassing stuurt zodra iets gebeurt. Dat helpt om een nieuwe transportstatus door te geven zonder voortdurend te vragen of er iets is veranderd. De ontvangende toepassing moet de afzender volgens het afgesproken mechanisme controleren, het bericht valideren en herhaalde afleveringen herkennen.
Als verwerking later gebeurt, bevestig de ontvangst pas nadat het bericht duurzaam is vastgelegd. Die bevestiging zegt dan nog niets over de zakelijke verwerking. Een status als “afgeleverd” kan bijvoorbeeld verwijzen naar een onbekende deelzending en alsnog herstelwerk vragen. De precieze aflever- en herhaalafspraken verschillen per aanbieder.
Voeg een controle achteraf toe op ontbrekende of vastgelopen opdrachten. Vergelijk bijvoorbeeld afgeronde zendingen met de verwachte terugmeldingen. Een succesvolle webhookaanroep bewijst niet dat de hele keten sluit. Meer over betrouwbare overdracht staat in logistieke software met events.
Laat een interface gecontroleerd meegroeien.
Een veld toevoegen lijkt onschuldig, maar een ontvanger kan onbekende velden of nieuwe statuswaarden afwijzen. Test wijzigingen met de partijen die het contract gebruiken. Leg bij een brekende wijziging vast welke versies tijdelijk naast elkaar bestaan en wanneer alle afnemers zijn overgezet. Een koppeling wordt ook beheerd nadat de eerste order succesvol is doorgekomen.
Geef iedere aansluiting alleen toegang tot de bewerkingen en gegevens die zij nodig heeft. Controleer de klant- of voorraadeigenaar aan de ontvangende kant; een meegestuurd nummer is geen toegangsrecht. Houd sleutels buiten voorbeelden en logs. Test autorisatie net zo concreet als aantallen: een vervoerder mag niet door een aangepast zendingsnummer opdrachten van een andere partij ophalen.
Werk één overdracht volledig uit.
Kies één echte overdracht, zoals een ontvangst boeken of een transportopdracht aanmaken. Beschrijf de normale route, een inhoudelijke afwijzing, een dubbele aanvraag en een verloren antwoord. Daarmee wordt zichtbaar welk deel het pakket ondersteunt en welk deel aanvullende software nodig heeft.
Blade ontwerpt en bouwt API-koppelingen en complete logistieke toepassingen. We verbinden de technische afspraken aan wat medewerkers op de werkvloer moeten kunnen zien en herstellen. Dat kan een koppeling tussen bestaande pakketten zijn of onderdeel van een eigen WMS of TMS.
Bespreek je koppeling met onze makers. Neem een voorbeeldopdracht en de betrokken systemen mee. Dan kunnen we samen de overdracht, uitzonderingen en eerste werkende stap concreet maken.
De keuze vóór het technische ontwerp is minstens zo belangrijk: moet je vooral gegevens overdragen of ontbreekt de regie over het hele proces? Vergelijk custom koppelingen met een eigen operationeel systeem.