UPS Tracking API: een beginnersgids om aan de slag te gaan
De UPS Tracking API stelt een bedrijf in staat om de status van zendingen op te halen en leveringsupdates weer te geven binnen zijn eigen website, app, orderbeheersysteem of klantenservicetools. Om te beginnen moet u doorgaans een UPS-ontwikkelaarsaccount aanmaken, een applicatie registreren, authenticatiegegevens verkrijgen, een trackingaanvraag versturen en het antwoord vertalen naar nuttige gebeurtenissen voor klanten. Deze handleiding legt het proces uit zonder uit te gaan van eerdere API-ervaring.
De voorbeelden richten zich op tracking en niet op het aanmaken van labels, tariefberekening of adresvalidatie. UPS onderhoudt afzonderlijke API-producten en documentatie. Controleer daarom of de applicatie die u registreert toegang heeft tot de trackingfunctionaliteit die u nodig hebt voordat u productieprocessen bouwt.
Wat doet een UPS Tracking API?
Een API is een gestructureerde manier waarop het ene softwaresysteem informatie bij een ander kan opvragen. In een trackingproces stuurt uw systeem een zendingidentificatie, zoals een trackingnummer, naar een vervoerder of trackingplatform. De service retourneert zendinggegevens die, afhankelijk van de service, de zending en de beschikbare antwoordvelden op het moment van de aanvraag, een actuele status, statusbeschrijving, locatiegegevens, datums en pakketmijlpalen kunnen bevatten.
Deze gegevens kunnen verschillende praktische functies ondersteunen:
- Een trackingpagina die in een ecommerce-webshop is ingebed.
- Inzicht in zendingen binnen een orderbeheersysteem of enterprise-resource-planningsysteem.
- Klantenserviceschermen die de noodzaak verminderen om handmatig een vervoerderswebsite te controleren.
- Interne meldingen voor leveringsproblemen, vertragingen of voltooide leveringen.
- Berichten na aankoop op basis van zendinggebeurtenissen.
De API vervangt uw applicatielogica niet. U moet nog steeds bepalen hoe vaak u updates opvraagt, hoe u antwoorden opslaat, hoe u onvolledige gegevens verwerkt en hoe u vervoerdersstatussen aan klanten uitlegt.
UPS Tracking API versus de UPS-website
De UPS-website is ontworpen voor iemand die een trackingnummer invoert en het resultaat leest. Een API is ontworpen voor software. Deze is nuttig wanneer trackinginformatie automatisch in een ander systeem moet verschijnen of een intern proces moet activeren.
Dit onderscheid is belangrijk omdat een API-integratie verantwoordelijkheden met zich meebrengt die een handmatige zoekopdracht niet heeft. Uw team moet inloggegevens beschermen, gebruikersinvoer valideren, aanvragen en antwoorden op de juiste manier vastleggen, tijdelijke storingen afhandelen en controleren of de integratie blijft werken nadat het vervoerdersplatform is gewijzigd.
Het UPS-ontwikkelaarsplatform is het juiste startpunt voor actuele registratie- en technische vereisten. De documentatie daarvan moet voorrang krijgen boven oudere handleidingen, codevoorbeelden of forumberichten, omdat authenticatiemethoden, API-versies, vereiste headers en regels voor producttoegang kunnen veranderen.
Wat u nodig hebt voordat u een aanvraag doet
Bereid de volgende zaken voor voordat u de integratie schrijft:
- Een UPS-ontwikkelaarsaccount. Gebruik het officiële UPS Developer Portal om beschikbare API's te bekijken en een applicatie aan te maken.
- Applicatiegegevens. De exacte namen van de inloggegevens en de authenticatiestroom moeten uit de actuele UPS-documentatie komen. Plaats clientgeheimen niet in browsercode, mobiele applicaties, openbare repositories of pagina's die klanten kunnen zien.
- Een geldig trackingnummer voor tests. Test met zendingen waartoe uw organisatie gemachtigd is toegang te hebben en voorkom dat persoonlijke of commerciële zendinggegevens in logboeken worden blootgelegd.
- Een integratiepunt aan de serverzijde. Een backendservice is doorgaans veiliger dan de vervoerder rechtstreeks vanaf een openbare webpagina aanroepen, omdat deze inloggegevens privé kan houden en het aantal aanvragen kan beheren.
- Een plan voor het opslaan van antwoorden. Bepaal welke velden u nodig hebt, hoe lang u ze bewaart en hoe u een vervoerdersgebeurtenis aan een interne bestelling koppelt.
Een beginnersvriendelijke integratieworkflow
1. Bevestig de bedrijfsbehoefte
Bepaal eerst wat “tracking” in uw product betekent. Een klantgerichte pagina heeft mogelijk alleen een actuele status en informatie over de verwachte levering nodig. Een magazijn- of supportdashboard heeft mogelijk ook scangeschiedenis, tijdstempels, beschrijvingen van uitzonderingen en het oorspronkelijke trackingnummer nodig.
Vraag niet zonder reden elk beschikbaar veld op. Een kleiner gegevensmodel is eenvoudiger te onderhouden en zal minder snel informatie blootleggen die uw gebruikers niet nodig hebben.
2. Registreer de applicatie
Maak een applicatie aan in de UPS-ontwikkelaarsomgeving en selecteer het relevante trackingproduct volgens de actuele instructies in het portaal. Sla de applicatie-ID veilig op. Als UPS goedkeuring, accountkoppeling of aanvullende configuratie voor productietoegang vereist, voltooi die stappen dan voordat u een live lanceringsdatum belooft.
Houd test- en productiegegevens en -configuratie gescheiden waar het platform dat model ondersteunt. Dit verkleint de kans dat een testscript een liveproces beïnvloedt.
3. Implementeer authenticatie
Authenticatie bewijst dat uw applicatie de service mag aanroepen. Volg de authenticatiemethode, het token-endpoint, de scopevereisten en de headerindeling die in de actuele UPS-documentatie worden weergegeven. Behandel toegangstokens als tijdelijke geheimen en schrijf ze niet naar applicatielogboeken.
Een verstandige implementatie vraagt alleen een token aan wanneer dat nodig is, gebruikt het gedurende de toegestane levensduur opnieuw en verkrijgt een nieuw token na het verlopen ervan. Uw code moet ook onderscheid maken tussen een authenticatiefout en een fout met het trackingnummer. De oplossing verschilt: voor het ene zijn controle van inloggegevens of configuratie nodig, terwijl het andere mogelijk invoervalidatie vereist.
4. Verstuur een trackingaanvraag
Stuur na authenticatie een aanvraag met de trackingbewerking en indeling van de identificatie die UPS voorschrijft. De exacte URL, HTTP-methode, headers en antwoordstructuur staan in de officiële documentatie voor de API-versie die u selecteert.
Een conceptuele aanvraag ziet er als volgt uit:
POST /tracking-operation
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json
{
"trackingNumber": "YOUR_TRACKING_NUMBER"
}Dit is een leervoorbeeld en geen productieaanvraag die u direct kunt kopiëren en plakken. Vervang de naam van de bewerking, het endpoint, de headers en de body door de waarden uit de actuele UPS API-referentie. Sommige API's gebruiken een padparameter of een andere aanvraagstructuur.
5. Normaliseer het antwoord
Antwoorden van vervoerders zijn niet altijd geschreven in de taal die uw klanten verwachten. Maak een intern gebeurtenismodel met stabiele velden, zoals:
- Interne ID van bestelling of zending.
- Naam van de vervoerder en trackingnummer.
- Laatste statuscode van de vervoerder en onbewerkte beschrijving.
- Een genormaliseerde status die door uw applicatie wordt gebruikt.
- Tijdstempel van de gebeurtenis en, indien verstrekt, de locatie.
- Tijdstip van de laatste geslaagde update.
Bewaar waar mogelijk de oorspronkelijke status van de vervoerder. Een genormaliseerd label zoals “Onderweg” is nuttig voor een klantinterface, maar de onbewerkte beschrijving kan supportmedewerkers helpen een ongebruikelijke gebeurtenis te onderzoeken.
6. Bepaal hoe updates worden opgehaald
Sommige systemen gebruiken geplande polling: een backend controleert geschikte zendingen met geselecteerde tussenpozen en slaat wijzigingen op. Andere gebruiken gebeurtenismeldingen wanneer het relevante platform deze ondersteunt. Ga er niet van uit dat elk UPS-trackingproduct hetzelfde meldingsmechanisme biedt. Controleer de actuele documentatie en commerciële voorwaarden voordat u een workflow op basis van webhooks ontwerpt.
Polling moet selectief gebeuren. Recent verzonden of actief bewegende pakketten kunnen vaker controleren rechtvaardigen dan geleverde of geannuleerde zendingen. Pas voor tijdelijke storingen retries met backoff toe, respecteer gedocumenteerde limieten en stop onnodige aanvragen na een eindstatus, tenzij uw bedrijfsproces latere verificatie vereist.
Veelvoorkomende fouten en hoe u ermee omgaat
| Situatie | Waarschijnlijke reactie | Praktische actie |
|---|---|---|
| Authenticatiefout | De aanvraag is niet geautoriseerd. | Controleer inloggegevens, tokenverwerking, scopes, omgeving en vereiste headers. |
| Ongeldige trackinginvoer | De identificatie ontbreekt, heeft een onjuiste indeling of wordt niet geaccepteerd. | Valideer de invoer en toon een duidelijke correctiemelding. |
| Nog geen nuttige gebeurtenis | Een zending heeft mogelijk nog geen eerste scan ontvangen. | Verklaar niet dat de levering is mislukt; toon een neutrale melding dat de zending in behandeling is en probeer het later opnieuw. |
| Reactie over snelheid of quotum | De applicatie verstuurt te snel aanvragen of heeft een limiet bereikt. | Verminder de polling, plaats werk in een wachtrij en volg de richtlijnen van de provider. |
| Tijdelijke server- of netwerkfout | De service kan korte tijd niet beschikbaar zijn. | Probeer veilig opnieuw met backoff en bewaar de laatst bekende status. |
De belangrijkste regel voor de gebruikerservaring is dat ontbrekende gegevens niet mogen worden omgezet in een stellige conclusie. “Geen nieuwe scan” betekent niet automatisch “kwijt” en “label aangemaakt” betekent niet noodzakelijk “onderweg”. Breng statussen zorgvuldig in kaart en houd de afhandeling van uitzonderingen zichtbaar voor supportteams.
Wanneer een API voor meerdere vervoerders beter past
Een directe UPS-integratie kan een verstandige keuze zijn wanneer uw zendingen voornamelijk door UPS worden afgehandeld en uw team directe controle over de verbinding met de vervoerder wil. Het nadeel is dat elke extra vervoerder mogelijk een ander authenticatiemodel, gegevensschema, foutbeleid en onderhoudsproces vereist.
Als uw bedrijf meerdere vervoerders gebruikt, kan een service voor meerdere vervoerders het aantal afzonderlijke integraties verminderen. De Tracking API van 17TRACK is ontworpen voor tracking van zendingen via applicaties en de officiële ontwikkelaarsdocumentatie legt het beschikbare integratiemodel uit. Deze kan het overwegen waard zijn wanneer de werkelijke behoefte niet alleen UPS-tracking is, maar een consistente trackinglaag voor meerdere vervoerders.
Dit is geen reden om een directe UPS-verbinding automatisch te vervangen. Vergelijk de benodigde dekking van vervoerders, gebeurtenisdetails, vereisten voor gegevensbewaring, het authenticatiemodel, operationele limieten, het supportproces en de totale implementatie-inspanning. De openbare documentatie van een provider moet worden beschouwd als het startpunt voor een technisch proof of concept, niet als vervanging voor het testen van uw eigen zendingpatronen.
Checklist voor productiegereedheid
- Inloggegevens worden opgeslagen in een secretmanager en nooit aan de browser blootgesteld.
- Test- en productieomgevingen zijn duidelijk gescheiden.
- Aanvragen hebben time-outs, gecontroleerde retries en nuttige foutregistratie.
- Trackingnummers worden gevalideerd voordat ze worden verstuurd.
- Het systeem slaat de laatste geslaagde update op en overschrijft deze niet met een leeg antwoord.
- Onbewerkte berichten van vervoerders en klantgerichte labels worden afzonderlijk verwerkt.
- De pollingfrequentie volgt de gepubliceerde limieten van de provider en uw operationele behoefte.
- Monitoring kan authenticatiefouten, verhoogde foutpercentages en verouderde zendingen detecteren.
- Supportmedewerkers kunnen voldoende details zien om een vraag van een klant te onderzoeken.
- De integratie wordt opnieuw getest wanneer UPS de documentatie, inloggegevens, endpoints of antwoordvelden wijzigt.
Begin met één volledig pad: authenticeer, track één testzending, sla het antwoord op, toon een eenvoudige status en verwerk fouten. Breid pas uit nadat dat pad betrouwbaar is. Deze aanpak is doorgaans veiliger dan een grote klantgerichte trackingervaring bouwen voordat de onderliggende gegevens en het foutgedrag zijn begrepen.
Veelgestelde vragen
Heb ik een API nodig als ik slechts enkele pakketten track?
Meestal niet. Handmatig tracken op de website van de vervoerder kan praktischer zijn voor incidentele zoekopdrachten. Een API wordt waardevoller wanneer tracking deel uitmaakt van een herhaalbaar proces of in een andere applicatie moet verschijnen.
Kan ik de UPS Tracking API aanroepen vanuit een Shopify-thema of browser?
Een rechtstreekse browseraanroep kan inloggegevens blootleggen en het beheer van aanvragen bemoeilijken. Een service aan de serverzijde of een bestaande trackingintegratie is doorgaans veiliger. Bevestig de technische vereisten en toegestane architectuur in de actuele UPS-documentatie.
Maakt een tracking-API verzendlabels aan?
Niet noodzakelijk. Tracking, het aanmaken van labels, tariefberekening, adresvalidatie en andere logistieke functies kunnen afzonderlijke API-producten zijn. Selecteer het product dat past bij de bewerking die u nodig hebt.
Waarom kan een geldig trackingnummer weinig informatie opleveren?
Een pakket heeft mogelijk nog geen eerste scan ontvangen, de gegevens zijn mogelijk nog niet beschikbaar of de aanvraag voldoet mogelijk niet aan de vereiste indeling of toegangsrechten van de API. Beschouw een leeg of beperkt antwoord als een toestand die moet worden onderzocht, niet als bewijs dat de zending kwijt is.
Moet ik rechtstreeks voor UPS kiezen of voor een tracking-API voor meerdere vervoerders?
Kies een directe verbinding wanneer UPS de belangrijkste vervoerder is en u een gerichte integratie wilt. Overweeg een service voor meerdere vervoerders wanneer uw operationele doel één trackingworkflow voor verschillende vervoerders is. Test de vereiste vervoerders en gebeurtenisscenario's voordat u een definitieve beslissing neemt.
