UPS Tracking API: En begyndervejledning til at komme i gang
UPS Tracking API gør det muligt for en virksomhed at hente forsendelsesstatus og vise leveringsopdateringer på sit eget website, i sin app, sit ordreadministrationssystem eller sine kundeserviceværktøjer. Kom godt i gang indebærer normalt at oprette en UPS-udviklerkonto, registrere en applikation, indhente godkendelsesoplysninger, sende en trackingforespørgsel og omsætte svaret til nyttige begivenheder, der er synlige for kunderne. Denne vejledning forklarer processen uden at forudsætte tidligere erfaring med API'er.
Eksemplerne fokuserer på tracking frem for oprettelse af etiketter, prisberegning eller adressevalidering. UPS vedligeholder separate API-produkter og dokumentation, så bekræft, at den applikation, du registrerer, har adgang til den trackingfunktion, du har brug for, før du bygger produktionsarbejdsgange.
Hvad gør et UPS Tracking API?
Et API er en struktureret måde, hvorpå ét softwaresystem kan anmode om oplysninger fra et andet. I en trackingarbejdsgang sender dit system en forsendelsesidentifikator, f.eks. et trackingnummer, til en transportør eller trackingplatform. Tjenesten returnerer forsendelsesdata, som afhængigt af tjenesten, forsendelsen og de svarfelter, der er tilgængelige på anmodningstidspunktet, kan omfatte den aktuelle status, en statusbeskrivelse, lokaliseringsoplysninger, datoer og pakkens milepæle.
Disse data kan understøtte flere praktiske funktioner:
- En trackingside integreret i en ecommerce-butik.
- Forsendelsesoverblik i et ordreadministrations- eller enterprise resource planning-system.
- Kundeserviceskærme, der reducerer behovet for manuelt at kontrollere en transportørs website.
- Interne advarsler om leveringsproblemer, forsinkelser eller gennemførte leveringer.
- Efterkøbsbeskeder baseret på forsendelsesbegivenheder.
API'et erstatter ikke din applikationslogik. Du skal stadig beslutte, hvor ofte der skal anmodes om opdateringer, hvordan svar skal gemmes, hvordan ufuldstændige data skal håndteres, og hvordan transportørens statusser skal forklares for kunderne.
UPS Tracking API sammenlignet med UPS-websitet
UPS-websitet er designet til, at en person indtaster et trackingnummer og læser resultatet. Et API er designet til software. Det er nyttigt, når trackingoplysninger automatisk skal vises i et andet system eller udløse en intern proces.
Denne forskel er vigtig, fordi en API-integration medfører ansvar, som et manuelt opslag ikke gør. Dit team skal beskytte legitimationsoplysninger, validere brugerinput, registrere anmodninger og svar korrekt, håndtere midlertidige fejl og overvåge, om integrationen fortsat fungerer efter ændringer på transportørens platform.
UPS' udviklerplatform er det rigtige udgangspunkt for aktuelle registrerings- og tekniske krav. Dokumentationen bør have forrang for ældre vejledninger, kodeeksempler eller forumindlæg, fordi godkendelsesmetoder, API-versioner, påkrævede headers og regler for produktadgang kan ændre sig.
Hvad skal du bruge, før du sender en anmodning?
Forbered følgende, før du skriver integrationen:
- En UPS-udviklerkonto. Brug den officielle UPS Developer Portal til at gennemgå tilgængelige API'er og oprette en applikation.
- Applikationslegitimationsoplysninger. De præcise navne på legitimationsoplysningerne og godkendelsesflowet skal hentes fra den aktuelle UPS-dokumentation. Placer ikke client secrets i browserkode, mobilapplikationer, offentlige repositories eller kundesynlige sider.
- Et gyldigt trackingnummer til test. Test med forsendelser, som din organisation har tilladelse til at tilgå, og undgå at eksponere personlige eller kommercielle forsendelsesdata i logs.
- Et integrationspunkt på serversiden. En backend-tjeneste er normalt sikrere end at kalde transportøren direkte fra en offentlig webside, fordi den kan holde legitimationsoplysninger private og kontrollere antallet af anmodninger.
- En plan for lagring af svar. Beslut, hvilke felter du har brug for, hvor længe de skal opbevares, og hvordan en transportørbegivenhed skal knyttes til en intern ordre.
En integrationsarbejdsgang for begyndere
1. Bekræft forretningskravet
Definér først, hvad “tracking” betyder i dit produkt. En kundevendt side har måske kun brug for den aktuelle status og oplysninger om forventet levering. Et lager- eller supportdashboard kan også have brug for scanhistorik, tidsstempler, beskrivelser af problemer og det oprindelige trackingnummer.
Undgå at anmode om alle tilgængelige felter uden en grund. En mindre datamodel er lettere at vedligeholde og mindre tilbøjelig til at eksponere oplysninger, som dine brugere ikke har brug for.
2. Registrer applikationen
Opret en applikation i UPS' udviklingsmiljø, og vælg det relevante trackingprodukt i henhold til de aktuelle instruktioner på portalen. Opbevar applikationsidentifikatoren sikkert. Hvis UPS kræver godkendelse, kontotilknytning eller yderligere opsætning for produktionsadgang, skal du gennemføre disse trin, før du lover en lanceringsdato.
Brug separate legitimationsoplysninger og konfiguration til test og produktion, hvis platformen understøtter denne model. Det reducerer risikoen for, at et testscript påvirker en aktiv arbejdsgang.
3. Implementer godkendelse
Godkendelse beviser, at din applikation har tilladelse til at kalde tjenesten. Følg den godkendelsesmetode, token-endpointet, kravene til scopes og headerformatet, der vises i den aktuelle UPS-dokumentation. Behandl access tokens som midlertidige hemmeligheder, og skriv dem ikke til applikationslogs.
En fornuftig implementering anmoder kun om et token, når det er nødvendigt, genbruger det i den tilladte levetid og henter et nyt efter udløb. Din kode bør også skelne mellem en godkendelsesfejl og en fejl ved trackingnummeret. Løsningen er forskellig: Den ene kræver kontrol af legitimationsoplysninger eller konfiguration, mens den anden kan kræve validering af input.
4. Send en trackinganmodning
Efter godkendelse skal du sende en anmodning ved hjælp af den trackingoperation og det identifikatorformat, som UPS angiver. Den præcise URL, HTTP-metode, headers og svarstruktur fremgår af den officielle dokumentation for den API-version, du vælger.
En konceptuel anmodning ser sådan ud:
POST /tracking-operation
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json
{
"trackingNumber": "YOUR_TRACKING_NUMBER"
}Dette er et læringseksempel og ikke en produktionsanmodning, der skal kopieres direkte. Erstat operationsnavn, endpoint, headers og body med værdierne i den aktuelle UPS API-reference. Nogle API'er bruger en sti-parameter eller en anden anmodningsstruktur.
5. Normalisér svaret
Transportørers svar er ikke altid skrevet på det sprog, dine kunder forventer. Opret en intern begivenhedsmodel med stabile felter som:
- Internt ordre- eller forsendelses-ID.
- Transportørens navn og trackingnummer.
- Seneste statuskode fra transportøren og den rå beskrivelse.
- En normaliseret status, der bruges af din applikation.
- Begivenhedens tidsstempel og, når det oplyses, lokation.
- Tidspunktet for den seneste vellykkede opdatering.
Bevar om muligt transportørens oprindelige status. En normaliseret betegnelse som “Under transport” er nyttig i en kundegrænseflade, men den rå beskrivelse kan hjælpe supportmedarbejdere med at undersøge en usædvanlig begivenhed.
6. Beslut, hvordan opdateringer hentes
Nogle systemer bruger planlagt polling: En backend kontrollerer kvalificerede forsendelser med udvalgte intervaller og gemmer ændringer. Andre bruger begivenhedsnotifikationer, når den relevante platform understøtter dem. Antag ikke, at alle UPS-trackingprodukter tilbyder den samme notifikationsmekanisme. Bekræft den aktuelle dokumentation og de kommercielle vilkår, før du designer en webhook-baseret arbejdsgang.
Polling bør være selektiv. Nyligt afsendte eller aktivt transporterende pakker kan berettige hyppigere kontroller end leverede eller annullerede forsendelser. Anvend retries med backoff ved midlertidige fejl, respekter de dokumenterede grænser, og stop unødvendige anmodninger efter en afsluttende status, medmindre din forretningsproces kræver senere kontrol.
Almindelige fejl, og hvordan de håndteres
| Situation | Sandsynligt svar | Praktisk handling |
|---|---|---|
| Godkendelsesfejl | Anmodningen er ikke godkendt. | Kontrollér legitimationsoplysninger, tokenhåndtering, scopes, miljø og påkrævede headers. |
| Ugyldigt trackinginput | Identifikatoren mangler, er forkert formateret eller accepteres ikke. | Validér input, og vis en tydelig besked om, hvad der skal rettes. |
| Ingen nyttig begivenhed endnu | En forsendelse har muligvis endnu ikke modtaget sin første scanning. | Erklær ikke leveringsfejl; vis en neutral afventende besked, og prøv igen senere. |
| Svar om hastighed eller kvote | Applikationen sender anmodninger for hurtigt eller har nået en tilladt grænse. | Reducér polling, sæt arbejdet i kø, og følg udbyderens vejledning. |
| Midlertidig server- eller netværksfejl | Tjenesten kan være utilgængelig i kort tid. | Prøv sikkert igen med backoff, og bevar den senest kendte status. |
Den vigtigste regel for brugeroplevelsen er ikke at omdanne manglende data til en sikker konklusion. “Ingen ny scanning” betyder ikke automatisk “bortkommet”, og “label oprettet” betyder ikke nødvendigvis “under transport”. Kortlæg statusser omhyggeligt, og sørg for, at håndtering af undtagelser er synlig for supportteams.
Hvornår er et API til flere transportører et bedre valg?
En direkte UPS-integration kan være et fornuftigt valg, når dine forsendelser primært håndteres af UPS, og dit team ønsker direkte kontrol over transportørforbindelsen. Ulempen er, at hver ekstra transportør kan kræve en anden godkendelsesmodel, datastruktur, fejlpolitik og vedligeholdelsesproces.
Hvis din drift bruger flere transportører, kan en tjeneste til flere transportører reducere antallet af separate integrationer. 17TRACK's Tracking API er designet til applikationsbaseret tracking af forsendelser, og dens officielle udviklerdokumentation forklarer den tilgængelige integrationsmodel. Det kan være værd at evaluere, når det reelle krav ikke kun er UPS-tracking, men et ensartet trackinglag på tværs af transportører.
Dette er ikke en grund til automatisk at erstatte en direkte UPS-forbindelse. Sammenlign den transportørdækning, du har brug for, begivenhedsdetaljer, krav til dataopbevaring, godkendelsesmodel, driftsgrænser, supportproces og den samlede implementeringsindsats. En udbyders offentlige dokumentation bør betragtes som udgangspunktet for et teknisk proof of concept og ikke som en erstatning for at teste dine egne forsendelsesmønstre.
Tjekliste til produktionsberedskab
- Legitimationsoplysninger opbevares i en secret manager og eksponeres aldrig for browseren.
- Test- og produktionsmiljøer er tydeligt adskilt.
- Anmodninger har timeouts, kontrollerede retries og nyttig fejllogning.
- Trackingnumre valideres, før de sendes.
- Systemet gemmer den seneste vellykkede opdatering og undgår at overskrive den med et tomt svar.
- Rå beskeder fra transportøren og kundevendte betegnelser håndteres separat.
- Pollingfrekvensen følger udbyderens offentliggjorte grænser og dit driftsbehov.
- Overvågning kan registrere godkendelsesfejl, forhøjede fejlprocenter og forsendelser uden aktuelle opdateringer.
- Supportmedarbejdere kan se tilstrækkelige detaljer til at undersøge et kundespørgsmål.
- Integrationen testes igen, når UPS ændrer dokumentation, legitimationsoplysninger, endpoints eller svarfelter.
Start med én komplet sti: godkend, track én testforsendelse, gem svaret, vis en enkel status, og håndtér fejl. Udvid først, når denne sti er pålidelig. Denne tilgang er normalt sikrere end at bygge en stor kundevendt trackingoplevelse, før de underliggende data og fejlforløb er forstået.
Ofte stillede spørgsmål
Har jeg brug for et API, hvis jeg kun tracker nogle få pakker?
Som regel ikke. Manuel tracking på transportørens website kan være mere praktisk ved lejlighedsvise opslag. Et API bliver mere værdifuldt, når tracking er en del af en gentagelig arbejdsgang eller skal vises i en anden applikation.
Kan jeg kalde UPS Tracking API fra et Shopify-tema eller en browser?
Et direkte browserkald kan eksponere legitimationsoplysninger og gøre det vanskeligt at kontrollere antallet af anmodninger. En tjeneste på serversiden eller en etableret trackingintegration er generelt sikrere. Bekræft de tekniske krav og den tilladte arkitektur i den aktuelle UPS-dokumentation.
Opretter et tracking API forsendelsesetiketter?
Ikke nødvendigvis. Tracking, oprettelse af etiketter, prisberegning, adressevalidering og andre logistikfunktioner kan være separate API-produkter. Vælg det produkt, der passer til den operation, du har brug for.
Hvorfor kan et gyldigt trackingnummer returnere få oplysninger?
En pakke har muligvis endnu ikke modtaget sin første scanning, dataene er måske endnu ikke tilgængelige, eller anmodningen matcher muligvis ikke API'ets påkrævede format eller adgangstilladelser. Behandl et tomt eller begrænset svar som en tilstand, der skal undersøges, og ikke som bevis på, at forsendelsen er bortkommet.
Bør jeg vælge UPS direkte eller et tracking API til flere transportører?
Vælg en direkte forbindelse, når UPS er den primære transportør, og du ønsker en fokuseret integration. Overvej en tjeneste til flere transportører, når dit driftsmål er én trackingarbejdsgang på tværs af flere transportører. Test de nødvendige transportører og begivenhedsscenarier, før du træffer en endelig beslutning.
