UPS API koppelen aan je TMS: OAuth 2.0 in 6 stappen

Waarom UPS in je TMS-stack, ook als PostNL of DPD je hoofdcarrier is

De meeste NL/BE-verladers draaien parcel via PostNL, DPD of GLS en pallets via een regionale vervoerder. UPS komt meestal in beeld zodra er internationale B2B-zendingen of retouren naar de VS/UK bijkomen, waar UPS met eigen customs-afhandeling en een dicht Europees netwerk sterk staat. Als je die stroom nu nog handmatig via het UPS-portaal labelt, kost dat op termijn meer tijd dan een koppeling met je TMS.

Wie nog een oude koppeling heeft die draait op access keys, moet sowieso in actie komen. In 2024 rondde UPS een grote migratie af van de oude XML-based API's naar moderne OAuth 2.0 REST API's. Dat betekent dat elke koppeling die je nu bouwt op REST en OAuth 2.0 moet draaien, niet op de oude SOAP/XML-structuur. Deze gids loopt de stappen door om UPS API koppelen aan TMS in de praktijk te doen, inclusief de fout die je bijna gegarandeerd tegenkomt.

Wat je nodig hebt voordat je begint

Je hebt een UPS.com-account met toegang tot het UPS Developer Portal, plus een geregistreerde app met Client ID en Client Secret. Zonder die twee kom je geen stap verder in de OAuth-flow.

Werk eerst in de sandbox-omgeving voordat je iets op productie loslaat. UPS gebruikt aparte hosts voor testen en live verkeer: voor de OAuth-token, rating en shipping is dat wwwcie.ups.com in sandbox tegenover onlinetools.ups.com in productie, en datzelfde onderscheid geldt voor de tracking-endpoint (test versus productie). Sandbox en productie gebruiken bovendien andere credentials, dus kopieer nooit zomaar dezelfde Client ID/Secret van test naar live.

Check ook of je TMS een generieke of custom carrierkoppeling ondersteunt. Niet elk pakket-gericht platform kan dit zelf bouwen. Multicarrier-platforms als Sendcloud, Shipmondo, ShipStation en Cargoson bieden een kant-en-klare UPS-connector naast lokale carriers, wat relevant is als je niet zelf wilt ontwikkelen.

UPS API koppelen aan je TMS, stap voor stap

Onderstaande stappen gaan uit van een eigen koppeling tussen je TMS en de UPS REST API's voor rates, labels en tracking.

1. Registreer een app in het UPS Developer Portal. Log in met je UPS.com-account, maak een nieuwe applicatie aan en selecteer de producten die je nodig hebt: Authorization (OAuth), Rating, Shipping en Tracking. Het portaal levert je Client ID en Client Secret op.
2. Implementeer de OAuth 2.0 client credentials flow. De UPS OAuth Client Credentials API haalt een OAuth Bearer-token op wanneer de integratie-eigenaar ook de UPS-verzender is, met behulp van UPS-inloggegevens en het UPS-accountnummer, en dat token gebruik je vervolgens in de authorization-header bij calls naar de Ship API, Track API en andere UPS API's. In de praktijk stuur je Client ID en Secret als Basic Auth naar het token-endpoint en krijg je een bearer token terug, dat je in elke volgende call meestuurt in plaats van credentials in de body.
3. Test eerst in sandbox: Rating, Shipping en Tracking los van elkaar. Begin met de Rating en Address Validation API's voor klantgerichte functies, voeg de Shipping API toe voor labelgeneratie, en implementeer webhook-based tracking voor real-time zichtbaarheid. Doe dit in die volgorde: rates werken los van labels, en labels werken los van tracking.
4. Koppel je TMS-velden aan het UPS Shipment-request. Denk aan shipper number, servicecode (bijvoorbeeld UPS Standard of Express Saver), pakkettype, gewicht en afmetingen. Voor niet-EU-zendingen vanuit NL/BE, zoals retouren naar het VK na Brexit-regels, vul je ook de douanevelden (HS-code, waarde, land van herkomst) correct in de request, anders wijst UPS de zending af bij het aanmaken van het label.
5. Zet tracking-webhooks op. Laat statuswijzigingen automatisch binnenkomen in je TMS of WMS in plaats van dat je elk pakket handmatig navraagt via de Tracking API. Dit scheelt vooral bij hogere volumes rekenwerk en voorkomt dat je klantenservice status handmatig moet opzoeken.
6. Schakel over naar productie. Wissel de sandbox-host om naar de productie-host, vraag nieuwe productie-credentials aan (deze zijn anders dan sandbox), en draai eerst een beperkte batch labels. Vergelijk de gegenereerde tarieven met de eerstvolgende UPS-factuur om te controleren of servicecodes en gewichtsklassen goed doorkomen.

Hoe je weet dat het werkt

In de sandbox-fase geven testtracking-nummers geldige statuscodes terug via de Track API, zonder foutmeldingen over ongeldige shipment-ID's. Het eerste live label moet qua adresformaat en barcode overeenkomen met wat je al van PostNL of DPD gewend bent, en de servicecode op het label moet matchen met de UPS-factuurregel van diezelfde zending. Als laatste check: je token-refresh logica moet meerdere dagen achter elkaar draaien zonder dat er 401-fouten in de logs verschijnen. Zie je die wel, dan zit het probleem vrijwel altijd in tokenbeheer.

Meest voorkomende fout: verlopen token en 401 Unauthorized

Dit is de fout die iedereen een keer tegenkomt. Een OAuth-token heeft een beperkte levensduur, en zodra het verloopt terwijl je TMS nog een batch labels probeert te genereren (bijvoorbeeld tijdens een nachtelijke run), krijg je van UPS een 401 Unauthorized terug op elke volgende call. Bij een handmatige test merk je dit meteen, maar in een geautomatiseerde nachtelijke batch loop je het risico dat honderden labels stilzwijgend mislukken.

De oplossing is niet ingewikkeld, maar moet wel expliciet ingebouwd worden: ververs het token proactief vóór expiry in plaats van te wachten op een 401, en bouw retry-logica met logging in zodat een mislukte call zichtbaar wordt in plaats van stil te falen. Sommige leveranciers nemen dit uit handen: EasyPost beheert zelf de opslag en refresh van client credentials voor klanten die via hun platform met UPS werken. Bouw je zelf een TMS-koppeling, dan moet je dit gedrag zelf implementeren: een achtergrondtaak die het token ruim voor expiry vernieuwt en het resultaat cachet, in plaats van bij elke rate- of labelcall opnieuw een token op te halen.

Zelf bouwen of kant-en-klare connector gebruiken?

Zelf bouwen geeft volledige controle over foutafhandeling, veldmapping en douaneflows, maar kost ontwikkeluren voor de OAuth-flow, tokenbeheer, en onderhoud zodra UPS weer iets wijzigt in de API. Voor verladers die UPS naast drie of vier andere carriers draaien, is dat onderhoud cumulatief: elke carrier heeft zijn eigen quirks.

Een kant-en-klare multicarrier-connector kan dat werk overnemen. Enkele platformen die dit aanbieden naast lokale NL/BE-carriers:

Bij Cargoson geldt bijvoorbeeld dat je eigen UPS-account gekoppeld wordt en je eigen onderhandelde tarieven blijft gebruiken; je hebt je eigen UPS-account nodig om UPS-diensten via het platform te gebruiken, zodat je je onderhandelde tarieven behoudt en een directe relatie met UPS houdt. Dat is een ander model dan platforms die als tussenpersoon optreden op UPS-tarieven.

De keuze hangt af van hoeveel devuren je vrij hebt en hoeveel carriers je naast UPS moet onderhouden. Draai je alleen UPS naast PostNL en heb je een klein integratieteam, dan is een kant-en-klare connector meestal goedkoper dan zelf bouwen en onderhouden. Heb je een specifiek douane- of veldmapping-vereiste die geen standaardconnector aankan, dan blijft een eigen koppeling op de UPS REST API's de aangewezen route, mits je het tokenbeheer vanaf dag één goed inricht.