Sendcloud-koppeling laten maken voor multi-carrier verzending.

Waarom koppelen aan Sendcloud?

Wie meer dan een paar pakketten per dag verstuurt, kent het patroon: een order in de webshop, een label in het portaal van de vervoerder, een trackingcode die per mail wordt doorgegeven, en een retour die ergens in een mailbox begint. Dat werkt tot het volume groeit of tot je een tweede vervoerder toevoegt — en dan verdubbelt het handwerk in plaats van dat het meeschaalt.

Sendcloud lost dat op de manier op die voor koppelingen het gunstigst is: je activeert de vervoerders die je wilt gebruiken in het platform, en je eigen software praat met één API. Voeg je later DPD toe naast PostNL, dan is dat een instelling in Sendcloud, geen nieuw integratieproject.

Bouw op API v3, niet op v2

Dit is de belangrijkste keuze vooraf, en er is maar één goed antwoord. Sendcloud documenteert dat API v2 sinds april 2026 in maintenance mode gaat: er komen geen nieuwe functies meer bij en endpoints die die status krijgen, worden gesloten voor nieuwe gebruikers. Het Create Parcel-endpoint — precies het endpoint waar elke verzendkoppeling op draait — was de eerste die dichtging voor nieuwe accounts.

Wat dat concreet betekent:

• Nieuwe koppeling: v3, zonder discussie. De v2-route is voor nieuwe accounts deels simpelweg niet meer beschikbaar.
• Bestaand account van vóór april 2026: je mag v2 blijven gebruiken, inclusief nieuwe integraties en het roteren van sleutels. Maar je bouwt dan verder op een versie waar niets meer aan wordt toegevoegd.
• Sendcloud-partners: houden toegang via de Sendcloud-Partner-Id-header. Bouw je als bureau koppelingen voor klanten, dan is dat het verschil tussen wel en niet kunnen leveren.

Draai je nu op v2, dan is dat geen reden tot paniek maar wel een agendapunt. Sendcloud publiceert migratierichtlijnen voor de stap naar v3; plan die op een moment dat je verzendseizoen het toelaat, niet in november.

Een koppeling bouwen op een API-versie waar de leverancier de deur voor nieuwe gebruikers al heeft dichtgedaan, is technische schuld die je vrijwillig inkoopt.

Wat kun je koppelen?

De v3-API is opgedeeld in een paar duidelijke stukken. Dit zijn de onderdelen die in vrijwel elk project terugkomen:

• Verzendopties en tarieven — je stuurt herkomst- en bestemmingsadres naar het Shipping Options-endpoint en krijgt de beschikbare opties terug, gefilterd op de vervoerders die je hebt geactiveerd, op gewicht en afmetingen. Met calculate_quotes komen de tarieven mee. Hoe completer het adres, hoe nauwkeuriger de prijs: postcode, plaats en regio bepalen zonetoeslagen.
• Zendingen en labels — een order omzetten in een zending en het label opvragen. Er is ook een gecombineerd endpoint dat zending en label in één stap regelt, handig als je vanuit een ordersysteem batchgewijs verstuurt.
• Functionaliteiten — aanvullende diensten die je als filter meegeeft, zoals handtekening bij ontvangst of geschiktheid voor verzending van verse producten. Zo laat je de API alleen opties teruggeven waar je product daadwerkelijk mee verstuurd mag worden.
• Afhaalpunten — filteren op service_point als last mile levert de opties met afhaalpunt op; het gekozen punt geef je mee bij het aanmaken van de zending. De lijst met punten haal je op via de Service Points-API.
• Track-and-trace — statusupdates per zending, uniform over alle vervoerders heen. Dat is precies de winst van een verzendplatform: je klantcommunicatie hoeft niet te weten of het pakket bij PostNL of GLS ligt.
• Retouren — de Returns-API van v3 maakt losstaande retourlabels aan, ook als de oorspronkelijke zending niet via Sendcloud liep. Anders dan bij het oude retourportaal is er geen JWT-constructie meer nodig: gewone API-authenticatie volstaat. Er is een synchrone en een asynchrone variant, waarbij de asynchrone beter presteert bij volume.

Contracten bepalen wat je ziet

Een detail dat in de praktijk verwarring geeft: sommige verzendopties vereisen een eigen contract met de vervoerder, andere komen beschikbaar zodra je de carrier in Sendcloud activeert. Heb je meerdere contracten bij dezelfde vervoerder, dan vergelijk je die door per aanroep een ander contract_id mee te geven — één aanroep geeft één contract per carrier terug. Krijg je lege tarieven terug, dan is dat meestal geen bug maar een ontbrekend adresveld of een direct contract waarvoor nog geen tarieven zijn geüpload.

Authenticatie, webhooks en rate limits

Sendcloud werkt met een public key en een secret key via HTTP Basic Authentication: de public key is de gebruikersnaam, de secret key het wachtwoord. Daarnaast is er een OAuth2-variant in beta voor een beperkte groep klanten, met access tokens die na ongeveer een uur verlopen. Voor de meeste maatwerkkoppelingen is Basic Auth prima — mits de sleutels uitsluitend serverside staan en niet in front-endcode of een repository belanden.

Webhooks valideren

Statuswijzigingen komen binnen op de webhook-URL die je in je integratie-instellingen zet. Sendcloud ondertekent elke call met HMAC-SHA256 in de Sendcloud-Signature-header, berekend met je secret key of je webhook signature key. Die handtekening controleren is geen optionele extra: zonder validatie accepteert je endpoint elk verzoek dat de juiste vorm heeft.

Faalt een aanroep naar jouw kant, dan probeert Sendcloud het tot tien keer opnieuw met een oplopende vertraging, beginnend bij vijf minuten en met maximaal een uur ertussen. Dat is genereus, en het is meteen de reden dat je verwerking idempotent moet zijn: dezelfde statusupdate mag best drie keer binnenkomen, maar mag je klant niet drie keer een mail opleveren.

Rate limits

De gepubliceerde limieten zijn 1.000 GET-verzoeken per minuut en 100 schrijfacties (POST, PATCH, PUT, DELETE) per minuut, met een burst van 15 per seconde. Overschrijd je dat, dan volgt een HTTP 429. In de praktijk raak je dat vooral met twee dingen: een nachtelijke batch die in één keer honderden labels aanmaakt, en een synchronisatie die statussen ophaalt door te pollen in plaats van op webhooks te wachten. Spreid het eerste, vermijd het tweede.

Valkuilen bij een Sendcloud-koppeling

Uit de verzend- en e-commercekoppelingen die we bouwen, komen deze steeds terug:

• Tarieven in de checkout hard coderen — verzendkosten die in je eigen code staan lopen uit de pas zodra een vervoerder zijn tarieven aanpast. Haal ze op met quotes en cache ze kort.
• Adressen te laat valideren — een onvolledig adres levert geen of een verkeerd tarief op en strandt pas bij het aanmaken van het label. Valideer bij de bron, in de checkout.
• Geen statusmodel aan je eigen kant — als de zendingstatus alleen in Sendcloud bestaat, kan je klantenservice niets zonder tweede scherm. Sla de relevante statussen op in je eigen datamodel.
• Retouren als bijzaak behandelen — het retourproces raakt voorraad, terugbetaling en boekhouding tegelijk. Ontwerp het samen met de koppeling naar je boekhoudpakket, niet erna.
• Labels aanmaken zonder retry — een timeout tijdens het aanmaken van een label mag geen order zonder verzending achterlaten, en ook geen twee labels voor dezelfde order.

Mijn kijk op verzendkoppelingen

Verzenden is bij uitstek een domein waar een tussenlaag zijn geld waard is. Bij boekhouding of CRM koppel ik meestal liever direct op de bron, omdat je anders een extra afhankelijkheid en een extra datamodel introduceert. Bij vervoerders ligt dat anders: elke carrier heeft zijn eigen API, eigen statuscodes, eigen labelformaat en eigen eigenaardigheden rond douanedocumenten. Die verschillen zelf oplossen is werk dat je jaar na jaar blijft onderhouden zonder dat het je product beter maakt.

De keerzijde erken ik ook: je zet een leverancier tussen je bedrijfsproces en je pakketten. Daarom bouw ik dit soort koppelingen graag met een eigen laag ertussen — een eigen zendingsobject in de database, eigen statussen, eigen logboek. Dan is Sendcloud een uitwisselbare uitvoerder in plaats van de plek waar de waarheid staat, en overleeft je software een leverancierswissel zonder dat je klantenservice iets merkt.

En wat de versiekeuze betreft: dat v2 voor nieuwe gebruikers deels dicht is, maakt de beslissing makkelijk. Bouw op v3, ook als een voorbeeld dat je online vindt nog v2 laat zien.

— Jasper

Zo helpt Coding Agency hierbij

Wij bouwen Sendcloud-koppelingen op maat voor webshops, ordersystemen en WMS-omgevingen: verzendopties en tarieven in de checkout, labels vanuit je eigen ordersysteem, ondertekende webhooks met idempotente verwerking en een retourstroom die aansluit op je voorraad en administratie. Bestaande v2-koppelingen migreren we naar v3 zonder dat de verzending stilvalt.

Lees ook wat een API-koppeling precies is, hoe een Bol.com-koppeling in hetzelfde orderproces past, of wat een API-koppeling kost. Benieuwd wat er in jouw situatie kan? Neem contact op voor een vrijblijvend gesprek.

Bronnen: API version guide, Authentication en Rate limits (sendcloud.dev).