UPS Tracking API: En nybegynnerveiledning for å komme i gang
UPS Tracking API lar en virksomhet hente forsendelsesstatus og vise leveringsoppdateringer på sitt eget nettsted, i sin egen app, sitt eget ordrebehandlingssystem eller sine egne kundeserviceverktøy. Kom i gang innebærer vanligvis å opprette en UPS-utviklerkonto, registrere en applikasjon, skaffe autentiseringsopplysninger, sende en sporingsforespørsel og oversette svaret til nyttige hendelser som kundene kan se. Denne veiledningen forklarer prosessen uten å forutsette tidligere erfaring med API-er.
Eksemplene fokuserer på sporing, ikke oppretting av etiketter, prisberegning eller adressevalidering. UPS vedlikeholder separate API-produkter og egen dokumentasjon, så bekreft at applikasjonen du registrerer, har tilgang til sporingsfunksjonen du trenger før du bygger arbeidsflyter for produksjon.
Hva gjør UPS Tracking API?
Et API er en strukturert måte for ett programvaresystem å be om informasjon fra et annet. I en sporingsarbeidsflyt sender systemet ditt en forsendelsesidentifikator, for eksempel et sporingsnummer, til en transportør eller sporingsplattform. Tjenesten returnerer forsendelsesdata som kan inneholde gjeldende status, statusbeskrivelse, stedsinformasjon, datoer og milepæler for pakken, avhengig av tjenesten, forsendelsen og svarfeltene som er tilgjengelige på forespørselstidspunktet.
Disse dataene kan støtte flere praktiske funksjoner:
- En sporingsside innebygd i en nettbutikk.
- Forsendelsesinnsyn i et ordrebehandlings- eller ressursplanleggingssystem.
- Kundeserviceskjermer som reduserer behovet for å sjekke transportørens nettsted manuelt.
- Interne varsler om leveringsavvik, forsinkelser eller fullførte leveranser.
- Etterkjøpsmeldinger basert på forsendelseshendelser.
API-et erstatter ikke programlogikken din. Du må fortsatt bestemme hvor ofte oppdateringer skal hentes, hvordan svar skal lagres, hvordan ufullstendige data skal håndteres, og hvordan transportørens statuser skal forklares for kundene.
UPS Tracking API sammenlignet med UPS-nettstedet
UPS-nettstedet er utformet for at en person skal skrive inn et sporingsnummer og lese resultatet. Et API er utformet for programvare. Det er nyttig når sporingsinformasjon automatisk må vises i et annet system eller utløse en intern prosess.
Dette skillet er viktig fordi en API-integrasjon medfører ansvar som et manuelt oppslag ikke gjør. Teamet ditt må beskytte påloggingsopplysninger, validere brukerinndata, registrere forespørsler og svar på riktig måte, håndtere midlertidige feil og overvåke om integrasjonen fortsatt fungerer etter endringer på transportørens plattform.
UPS-utviklerplattformen er det riktige utgangspunktet for gjeldende registrerings- og tekniske krav. Dokumentasjonen bør ha forrang fremfor eldre veiledninger, kodeeksempler eller foruminnlegg, fordi autentiseringsmetoder, API-versjoner, obligatoriske headere og regler for produkttilgang kan endres.
Hva du trenger før du sender en forespørsel
Forbered følgende før du skriver integrasjonen:
- En UPS-utviklerkonto. Bruk den offisielle UPS Developer Portal for å se tilgjengelige API-er og opprette en applikasjon.
- Applikasjonsopplysninger. De nøyaktige navnene på opplysningene og autentiseringsflyten bør hentes fra den gjeldende UPS-dokumentasjonen. Ikke plasser klienthemmeligheter i nettleserkode, mobilapplikasjoner, offentlige kodearkiver eller sider som er synlige for kunder.
- Et gyldig sporingsnummer for testing. Test med forsendelser organisasjonen din har tillatelse til å få tilgang til, og unngå å eksponere personopplysninger eller kommersielle forsendelsesdata i logger.
- Et integrasjonspunkt på serversiden. En backend-tjeneste er normalt sikrere enn å kalle transportøren direkte fra en offentlig nettside, fordi den kan holde opplysningene private og kontrollere forespørselsvolumet.
- En plan for lagring av svar. Bestem hvilke felt du trenger, hvor lenge de skal oppbevares, og hvordan en transportørhendelse skal knyttes til en intern ordre.
En nybegynnervennlig integrasjonsarbeidsflyt
1. Bekreft forretningskravet
Definer først hva «sporing» betyr i produktet ditt. En kundevendt side trenger kanskje bare gjeldende status og forventet leveringsinformasjon. Et lager- eller støttedashboard kan også trenge skannehistorikk, tidsstempler, beskrivelser av avvik og det opprinnelige sporingsnummeret.
Unngå å be om alle tilgjengelige felt uten en grunn. En mindre datamodell er enklere å vedlikeholde og mindre sannsynlig å eksponere informasjon brukerne dine ikke trenger.
2. Registrer applikasjonen
Opprett en applikasjon i UPS-utviklingsmiljøet og velg det relevante sporingsproduktet i henhold til gjeldende instruksjoner i portalen. Lagre applikasjonsidentifikatoren på en sikker måte. Hvis UPS krever godkjenning, kontotilknytning eller ytterligere oppsett for produksjonstilgang, må du fullføre disse trinnene før du lover en dato for lansering.
Hold separate opplysninger og konfigurasjoner for testing og produksjon der plattformen støtter dette. Det reduserer risikoen for at et testskript påvirker en aktiv arbeidsflyt.
3. Implementer autentisering
Autentisering beviser at applikasjonen din har tillatelse til å kalle tjenesten. Følg autentiseringsmetoden, token-endepunktet, kravene til scope og header-formatet som vises i den gjeldende UPS-dokumentasjonen. Behandle tilgangstokener som midlertidige hemmeligheter, og ikke skriv dem til applikasjonslogger.
En fornuftig implementering ber bare om et token når det trengs, gjenbruker det i den tillatte levetiden og henter et nytt etter utløp. Koden bør også skille mellom en autentiseringsfeil og en feil med sporingsnummeret. Løsningen er forskjellig: Den ene krever gjennomgang av opplysninger eller konfigurasjon, mens den andre kan kreve validering av inndata.
4. Send en sporingsforespørsel
Etter autentisering sender du en forespørsel ved å bruke sporingsoperasjonen og identifikatorformatet som er angitt av UPS. Den nøyaktige URL-en, HTTP-metoden, headerne og svarskjemaet hører til den offisielle dokumentasjonen for API-versjonen du velger.
En konseptuell forespørsel ser slik ut:
POST /tracking-operation
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json
{
"trackingNumber": "YOUR_TRACKING_NUMBER"
}Dette er et læringseksempel, ikke en produksjonsforespørsel som kan kopieres og limes inn. Erstatt operasjonsnavnet, endepunktet, headerne og innholdet med verdiene i den gjeldende UPS API-referansen. Noen API-er bruker en sti-parameter eller en annen forespørselsstruktur.
5. Normaliser svaret
Transportørsvar er ikke alltid skrevet på språket kundene dine forventer. Opprett en intern hendelsesmodell med stabile felt som:
- Intern ordre- eller forsendelses-ID.
- Transportørens navn og sporingsnummer.
- Transportørens nyeste statuskode og rå beskrivelse.
- En normalisert status som brukes av applikasjonen.
- Hendelsestidsstempel og, når det oppgis, sted.
- Tidspunkt for siste vellykkede oppdatering.
Behold den opprinnelige transportørstatusen der det er mulig. En normalisert etikett som «Under transport» er nyttig i et kundegrensesnitt, men den rå beskrivelsen kan hjelpe støttepersonell med å undersøke en uvanlig hendelse.
6. Bestem hvordan oppdateringer skal hentes
Noen systemer bruker planlagt polling: En backend kontrollerer kvalifiserte forsendelser med valgte intervaller og lagrer endringer. Andre bruker hendelsesvarsler når den relevante plattformen støtter dette. Ikke anta at alle UPS-sporingsprodukter tilbyr samme varslingsmekanisme. Bekreft gjeldende dokumentasjon og kommersielle vilkår før du utformer en webhook-basert arbeidsflyt.
Polling bør være selektiv. Nylig sendte eller aktivt transporterte pakker kan begrunne hyppigere kontroller enn leverte eller kansellerte forsendelser. Bruk nye forsøk med økende ventetid ved midlertidige feil, respekter dokumenterte grenser, og stopp unødvendige forespørsler etter en sluttstatus med mindre forretningsprosessen krever senere bekreftelse.
Vanlige feil og hvordan de håndteres
| Situasjon | Sannsynlig svar | Praktisk tiltak |
|---|---|---|
| Autentiseringsfeil | Forespørselen er ikke autorisert. | Kontroller opplysninger, tokenhåndtering, scopes, miljø og obligatoriske headere. |
| Ugyldig sporingsinndata | Identifikatoren mangler, har feil format eller godtas ikke. | Valider inndata og vis en tydelig melding om hvordan feilen kan rettes. |
| Ingen nyttig hendelse ennå | En forsendelse har kanskje ikke fått sin første skanning. | Unngå å erklære leveringssvikt; vis en nøytral ventemelding og prøv igjen senere. |
| Svar om rate eller kvote | Applikasjonen sender forespørsler for raskt eller har nådd en grense. | Reduser polling, legg arbeidet i kø og følg leverandørens retningslinjer. |
| Midlertidig server- eller nettverksfeil | Tjenesten kan være utilgjengelig en kort periode. | Prøv trygt igjen med økende ventetid og behold den sist kjente statusen. |
Den viktigste regelen for brukeropplevelsen er å ikke gjøre manglende data om til en sikker konklusjon. «Ingen ny skanning» betyr ikke automatisk «borte», og «etikett opprettet» betyr ikke nødvendigvis «under transport». Kartlegg statuser nøye, og sørg for at håndtering av avvik er synlig for støttepersonell.
Når et API for flere transportører passer bedre
En direkte UPS-integrasjon kan være et fornuftig valg når forsendelsene dine hovedsakelig håndteres av UPS og teamet ditt ønsker direkte kontroll over transportørtilkoblingen. Avveiningen er at hver ekstra transportør kan kreve en ny autentiseringsmodell, et nytt dataskjema, en ny feilpolicy og en egen vedlikeholdsprosess.
Hvis virksomheten din bruker flere transportører, kan en tjeneste for flere transportører redusere antallet separate integrasjoner. 17TRACK's Tracking API er utviklet for applikasjonsbasert forsendelsessporing, og den offisielle utviklerdokumentasjonen forklarer den tilgjengelige integrasjonsmodellen. Det kan være verdt å vurdere når det egentlige kravet ikke bare er UPS-sporing, men et enhetlig sporingslag på tvers av transportører.
Dette er ikke en grunn til automatisk å erstatte en direkte UPS-tilkobling. Sammenlign transportørdekningen du trenger, hendelsesdetaljer, krav til datalagring, autentiseringsmodell, driftsgrenser, støtteprosess og samlet implementeringsinnsats. En leverandørs offentlige dokumentasjon bør behandles som utgangspunktet for en teknisk prøveimplementering, ikke som en erstatning for testing med dine egne forsendelsesmønstre.
Sjekkliste for produksjonsklarhet
- Påloggingsopplysninger lagres i en hemmelighetsbehandler og eksponeres aldri for nettleseren.
- Test- og produksjonsmiljøer er tydelig adskilt.
- Forespørsler har tidsavbrudd, kontrollerte nye forsøk og nyttig feillogging.
- Sporingsnumre valideres før de sendes.
- Systemet lagrer den siste vellykkede oppdateringen og unngår å overskrive den med et tomt svar.
- Rå transportørmeldinger og kundevendte etiketter håndteres separat.
- Pollingfrekvensen følger leverandørens offentliggjorte grenser og det operasjonelle behovet.
- Overvåkingen kan oppdage autentiseringsfeil, økte feilrater og foreldede forsendelser.
- Støttepersonell kan se nok detaljer til å undersøke et kundespørsmål.
- Integrasjonen testes på nytt når UPS endrer dokumentasjon, opplysninger, endepunkter eller svarfelt.
Start med én komplett bane: autentiser, spor én testforsendelse, lagre svaret, vis en enkel status og håndter feil. Utvid først når denne banen er pålitelig. Denne tilnærmingen er vanligvis sikrere enn å bygge en stor kundevendt sporingsopplevelse før de underliggende dataene og feiloppførselen er forstått.
Vanlige spørsmål
Trenger jeg et API hvis jeg bare sporer noen få pakker?
Vanligvis ikke. Manuell sporing på transportørens nettsted kan være mer praktisk ved sporadiske oppslag. Et API blir mer verdifullt når sporing er en del av en gjentakbar arbeidsflyt eller må vises i en annen applikasjon.
Kan jeg kalle UPS Tracking API fra et Shopify-tema eller en nettleser?
Et direkte nettleserkall kan eksponere påloggingsopplysninger og gjøre det vanskelig å kontrollere forespørsler. En tjeneste på serversiden eller en etablert sporingsintegrasjon er generelt sikrere. Bekreft de tekniske kravene og den tillatte arkitekturen i den gjeldende UPS-dokumentasjonen.
Oppretter et sporings-API fraktetiketter?
Ikke nødvendigvis. Sporing, oppretting av etiketter, prisberegning, adressevalidering og andre logistikkfunksjoner kan være separate API-produkter. Velg produktet som samsvarer med operasjonen du trenger.
Hvorfor kan et gyldig sporingsnummer returnere lite informasjon?
En pakke har kanskje ikke fått sin første skanning, dataene er kanskje ikke tilgjengelige ennå, eller forespørselen samsvarer kanskje ikke med API-ets påkrevde format eller tilgangstillatelser. Behandle et tomt eller begrenset svar som en tilstand som må undersøkes, ikke som bevis på at forsendelsen er borte.
Bør jeg velge UPS direkte eller et sporings-API for flere transportører?
Velg en direkte tilkobling når UPS er hovedtransportøren og du ønsker en fokusert integrasjon. Vurder en tjeneste for flere transportører når det operasjonelle målet ditt er én sporingsarbeidsflyt på tvers av flere transportører. Test de nødvendige transportørene og hendelsesscenarioene før du tar en endelig beslutning.
