FedEx API koppelen aan je TMS: zo pak je het aan

Je wil FedEx als vervoerdersoptie naast PostNL, DPD of bpost in je TMS, maar de documentatie is versnipperd over tientallen pagina's op developer.fedex.com. Dit stappenplan loopt de koppeling van de FedEx REST API (OAuth 2.0, Rate, Ship en Track) end-to-end door, inclusief wat er misgaat als tokens verlopen of een zending bij validatie afketst. Het is geschreven voor een technisch koppelteam dat de FedEx API koppelen aan TMS als concrete taak op het bord heeft, niet voor wie nog aan het oriënteren is.

Wat je nodig hebt voordat je begint

Je hebt vier dingen nodig voordat je ook maar één request verstuurt: een zakelijk FedEx-account, en drie identifiers uit het developer.fedex.com-portaal. Zonder deze vier loop je binnen een uur vast.

• API Key (Client ID): dit is een publieke identifier voor je applicatie, gebruikt in elke API-request header.
• Secret Key (Client Secret): wordt uitsluitend gebruikt voor OAuth token-aanvragen, en deze sleutel moet privé blijven.
• Account Number: vereist voor shipment- en rate-aanvragen, en koppelt je API-gebruik aan je FedEx-account.
• Meter Number: een legacy-identifier die bij sommige API-calls nog nodig kan zijn.

Test eerst in sandbox. FedEx heeft aparte API-URI's voor test en productie: de testomgeving draait op apis-sandbox.fedex.com, productie op apis.fedex.com. Werk nooit rechtstreeks tegen productie tijdens de eerste koppelpogingen, ook niet "even snel een labeltje testen".

Stap 1 t/m 3: OAuth 2.0-token ophalen

FedEx draait sinds de overstap van SOAP naar REST volledig op OAuth 2.0 met de client credentials-flow. Dat betekent: geen gebruikersinteractie, alleen je API Key en Secret Key.

1. Verstuur een POST-request naar het endpoint /oauth/token, form-encoded, met grant_type: client_credentials, client_id: je API Key en client_secret: je Secret Key.
2. Vang de response op. Die bevat een access_token en de vervaltijd, doorgaans geldig voor 3.600 seconden (1 uur).
3. Stuur dit token als Bearer-header mee bij elke volgende API-call. Dit OAuth access token moet elke 60 minuten opnieuw gegenereerd worden en bij elke API-transactie meegestuurd worden om toegang tot FedEx-resources te authenticeren.

De praktische valkuil: niet voor elke verzendaanvraag een nieuw token ophalen. Het token-endpoint heeft namelijk een eigen limiet: standaard 5 requests per seconde en 1.000 per dag. Bij een B2B-verlader met honderden zendingen per dag loop je daar snel tegenaan als je token-logica niet slim is. Bouw in plaats daarvan een refresh-routine in je TMS die het token cachet, een timer op ongeveer 55 minuten zet, en pas dan een nieuwe aanvraagt. Dat scheelt onnodige calls en voorkomt rate-limit fouten op een moment dat je ze het minst kunt gebruiken, bijvoorbeeld net voor sluitingstijd van je sorteercentrum.

Stap 4 en 5: Rate API en Ship API aanroepen

Met een geldig token kun je twee kernendpoints aanspreken: Rate voor tarieven, Ship voor het daadwerkelijke label. Beide werken met een vergelijkbare request-structuur, dus als je de eerste goed hebt staan, is de tweede een kwestie van velden uitbreiden.

Voor een tariefopvraag stuur je een requestedShipment-object mee. De kernvelden zijn RequestedShipment/Shipper (verplicht), RequestedShipment/Recipient (verplicht) en RequestedPackageLineItems, aangevuld met requestedPackageLineItems met afmetingen en gewicht, pickupType met opties als DROPOFF_AT_FEDEX_LOCATION of USE_SCHEDULED_PICKUP, en serviceType, dat je ook leeg kunt laten om alle beschikbare opties terug te krijgen. Let op: postalCode en countryCode zijn verplichte velden in zowel het shipper- als het recipient-adres.

Voor het aanmaken van een label via de Ship API gebruik je dezelfde basis, aangevuld met verzendspecifieke velden: pickupType om de ophaalmethode te specificeren, serviceType met keuzes als FEDEX_GROUND of PRIORITY_OVERNIGHT, en requestedPackageLineItems met gewicht, afmetingen en pakketaantal.

Benelux-specifiek: Luik, documenten en zonefactuur

Voor verladers in Zuid-Nederland en België loopt internationale lucht­vracht via de FedEx-hub op Liège Airport. Die hub is geen bijzaak: de faciliteit telt bijna 1.400 medewerkers, verwerkt ongeveer 75.000 zendingen per dag en verbindt Europa met bestemmingen als Memphis, Indianapolis, Oakland en Guangzhou. Luik is naast Paris-Charles de Gaulle een van de twee grote Europese airhubs van FedEx en fungeert als Europese draaischijf voor intercontinentale vracht. Voor je koppeling betekent dit vooral: zendingen vanuit NL/BE naar buiten de EU lopen fysiek via Luik, maar dat verandert niets aan je API-calls zelf. Wel relevant voor je documentenflow.

Bij elke zending buiten de EU moet je een handelsfactuur meesturen. De handelsfactuur is verplicht voor alle internationale commodity-zendingen (exclusief intra-EU), oftewel voor elke internationale zending met commerciële waarde. Bouw dit veld dus als verplicht in je TMS-formulier zodra het bestemmingsland buiten de EU valt, en koppel de data aan dezelfde adresvelden die je al voor de Ship API gebruikt, zodat naam, adres en goederenomschrijving consistent blijven. Een incorrecte of ontbrekende handelsfactuur kan leiden tot vertraging, annulering of inbeslagname door de douane, plus extra surcharges. Voor zonetarieven (de manier waarop FedEx internationale ritten prijst op basis van afstand/zone in plaats van een vast NL-tarief) geldt: vraag die altijd op via de Rate API vóórdat je het label aanmaakt, zeker bij gemengde zendingen richting DACH of verder.

Stap 6: Tracking terugkoppelen naar je TMS

Koppel na het aanmaken van een label meteen de Track API, zodat statusupdates automatisch in je TMS-dashboard verschijnen in plaats van dat iemand handmatig trackingnummers natrekt op de FedEx-website. Dat is dezelfde aanpak die je waarschijnlijk al kent van eerdere koppelingen met GLS of DPD op dit blog: periodiek pollen of, waar beschikbaar, een webhook-abonnement.

Voor wie dit liever niet zelf bouwt: Cargoson heeft losse integratiepagina's voor FedEx Express Nederland, waarbij tracking links automatisch worden gegenereerd en FedEx NL binnen seconden te integreren is, zonder code.

Veelvoorkomende fout: shipment-validatie faalt

Dit is waar de meeste koppelteams vastlopen, meestal pas bij hogere volumes. De oorzaak zit in hoe FedEx grote zendingen verwerkt.

Bij een multi-piece shipment werkt FedEx boven een bepaald aantal pakketten asynchroon via de Open Ship API in plaats van synchroon via de gewone Ship API. Open shipping is gelimiteerd tot 40 pakketten per zending voor synchrone verwerking, 300 pakketten per zending voor asynchrone verwerking en 999 pakketten per zending voor internationale commodities. Zit je boven de 40 pakketten, dan werk je met een ander patroon:

1. Roep Create Open Shipment aan om de zending te openen met alle vereiste verzend- en verpakkingsinformatie, accountNumber en shipmentgegevens.
2. Voeg pakketten toe via Add Open Shipment Packages, waarbij je een uniek index-veld meegeeft dat is toegewezen aan de al aangemaakte Open Shipment, samen met het accountNumber.
3. Herhaal stap 2 zo vaak als nodig: je kunt een aparte Add Package-aanvraag sturen voor elk pakket terwijl je de zending gedurende de dag voorbereidt.
4. Rond af met Confirm Open Shipment. Pas dan kunnen de verzenddocumenten zoals labels, AWB of rapporten gegenereerd worden. Slaagt de validatie niet, dan identificeert en rapporteert deze stap de eventuele fouten in de transactie en geeft een passende status terug.
5. Herstel foutieve regels via Modify Open Shipment of Modify Open Shipment Packages en confirm opnieuw.

Let op de deadline: de zending blijft vijf dagen open na de verzenddatum en wordt gepurged als hij niet binnen die vijf dagen bevestigd wordt. Bouw dus geen losse eenmalige scripts voor dit proces, maar een retry- en foutafhandelingslaag in je TMS-koppeling die automatisch Modify-calls stuurt op basis van de foutcodes die FedEx teruggeeft. Handmatig door foutlogs scrollen bij elke mislukte zending is op termijn onhoudbaar.

De tweede veelvoorkomende fout is subtieler: rate limiting op het token-endpoint zelf, zoals hierboven al genoemd bij stap 1 t/m 3. Als je TMS per verzending een vers token opvraagt in plaats van te cachen, loop je bij pieken (denk aan een maandagochtend met een stapel weekendorders) tegen de limiet van 5 requests per seconde en 1.000 per dag aan. De oplossing is dezelfde: cache het token, ververs het pas na ongeveer 55 minuten.

Zelf bouwen of een pasklare koppeling gebruiken?

Zelf de REST-API bouwen geeft volledige controle over foutafhandeling, retry-logica en welke velden je precies doorstuurt naar je WMS. De prijs daarvoor is onderhoud: elke wijziging in FedEx' API-schema, elke nieuwe servicetype-waarde, is jouw verantwoordelijkheid om te volgen en te patchen.

Een kant-en-klare multi-carrier connector kost je die controle, maar bespaart onderhoudsuren. Vier opties die FedEx al voorgeïntegreerd hebben:

Bij Cargoson betekent dit concreet dat één integratie vanuit je ERP al je huidige en toekomstige carrier-koppelingen dekt, je al je zendingen op één dashboard volgt, en het toevoegen, verwijderen of wisselen van vervoerders snel en eenvoudig is. Wie puur parcel-volume heeft zonder volwaardig TMS kan ook kijken naar courier-aggregators zoals Easyship of AfterShip, al missen die doorgaans de diepere ERP/WMS-koppeling die een verlader met gemengde B2B/B2C-stromen nodig heeft.

Hoe weet je dat de koppeling werkt?

Vier checks, in deze volgorde, voordat je het "live" noemt:

• Een testlabel in sandbox komt zonder foutmelding terug, inclusief geldig trackingnummer.
• Een trackingevent verschijnt binnen enkele minuten in je TMS-dashboard na een sandboxverzending.
• De factuurregel van FedEx matcht het tarief dat je via de Rate API had opgevraagd, inclusief zonetoeslag bij internationale zendingen.
• Na 48 uur productie is je foutlog leeg, of bevat alleen verwachte meldingen (zoals een onvolledig adres dat een medewerker moet corrigeren).

Wil je het resultaat ook in KPI's uitdrukken: meet de gemiddelde verwerkingstijd per zending vóór en na de koppeling, van orderregel tot label. Dat is de nuchtere maatstaf die laat zien of de integratie daadwerkelijk tijd bespaart, in plaats van alleen "mooier" te ogen op papier.