Kako koristiti Ups Tracking Api: Vodič za podešavanje korak po korak

Da biste koristili UPS Tracking API, kreirajte UPS Developer nalog, registrujte aplikaciju, pribavite OAuth 2.0 akreditive, zatražite pristupni token i šaljite autentifikovane zahteve za praćenje sa važećim UPS brojem za praćenje. Tačne oznake u portalu, koraci odobravanja i zahtevi API-ja mogu se promeniti, zato potvrdite aktuelna uputstva na zvaničnom UPS Developer Portalu pre nego što pustite integraciju u produkciju.

Ovaj vodič je namenjen programerima i timovima za ecommerce operacije kojima je potreban status pošiljke unutar internet prodavnice, sistema za upravljanje porudžbinama, skladišnog procesa, alata za korisničku podršku ili internog kontrolnog panela. Usredsređen je na redosled integracije, odluke koje utiču na pouzdanost i provere koje sprečavaju uobičajene greške pri praćenju.

Šta UPS Tracking API radi

API integracija omogućava softveru da zatraži informacije o pošiljci od kompanije UPS, umesto da zaposleni ili korisnik ručno otvaraju stranicu prevoznika za praćenje. Vaša aplikacija može koristiti odgovor za prikaz poslednjeg poznatog statusa, prepoznavanje događaja isporuke, podršku korisničkim istragama ili pokretanje internog procesa.

API nije isto što i stranica za praćenje. Stranica za praćenje namenjena je čitanju od strane ljudi. API odgovor je strukturirani podatak koji softver mora da obradi, sačuva i prikaže. Vaš sistem je i dalje odgovoran za autentifikaciju, obradu grešaka, periodično proveravanje ili prikupljanje događaja, čuvanje podataka, dizajn korisničkog interfejsa i sva poslovna pravila zasnovana na događajima isporuke.

Pre nego što počnete

Pripremite sledeće stavke pre otvaranja developerskog portala:

• UPS Developer nalog ili tip naloga koji zahteva aktuelni UPS proces uvođenja.
• Registrovanu aplikaciju i akreditive izdate za tu aplikaciju.
• Testni broj za praćenje ili drugi odobreni način testiranja. Nemojte počinjati sa podacima korisnika uživo ako UPS dokumentacija navodi posebno testno okruženje ili proceduru testiranja.
• Jasnu odluku o tome koji sistem je zadužen za evidenciju pošiljki, događaje praćenja i poruke o statusu namenjene korisnicima.
• Bezbedno mesto za čuvanje akreditiva klijenta i pristupnih tokena. Nikada ne stavljajte tajne u kod pregledača, javne repozitorijume, snimke ekrana ili mobilne aplikacije koje korisnici mogu da pregledaju.

Takođe treba da odlučite da li je vašoj aplikaciji potrebno samo praćenje ili šira UPS integracija. Praćenje, obračun cena, slanje, validacija adrese i usluge dokumenata mogu imati različite proizvode, dozvole, formate zahteva i operativne zahteve.

Korak 1: Otvorite UPS Developer Portal

Počnite na zvaničnom UPS Developer Portalu. Pregledajte aktuelni katalog API-ja, smernice za autentifikaciju, zahteve za uvođenje, uslove i informacije o okruženju. Posebno potražite dokumentaciju za Tracking API, umesto da pretpostavite da se uputstva za drugu UPS uslugu odnose i na praćenje.

Portal je odgovarajući izvor za aktuelna polja zahteva, opsege autorizacije, definicije odgovora, ograničenja brzine, kodove grešaka i detalje o okruženju. Ovi detalji mogu da se promene, a primer koda treće strane može koristiti stariji UPS interfejs ili zastareli metod autentifikacije.

Korak 2: Registrujte aplikaciju

Kreirajte aplikaciju na developerskom portalu i izaberite UPS API-je koji su aplikaciji zaista potrebni. Za projekat koji koristi samo praćenje zatražite samo mogućnost praćenja, osim ako vaš proces zahteva dodatne usluge. Ograničavanje dozvola smanjuje složenost konfiguracije i olakšava kasnije rešavanje problema.

Sačuvajte identifikator aplikacije i tajnu u upravljaču tajnama na serverskoj strani ili zaštićenom sistemu promenljivih okruženja. Tretirajte tajnu kao lozinku. Ako bude otkrivena, promenite je kroz proces koji obezbeđuje UPS i pregledajte evidencije zbog neovlašćenog korišćenja.

Ako portal traži podatke o nalogu, naplati, poslovanju ili aplikaciji, navedite tačne informacije. Nemojte izmišljati produkcioni slučaj upotrebe niti koristiti tuđe podatke naloga samo da biste završili test. Pristup usluzi može zavisiti od konfiguracije naloga i aktuelnog UPS procesa odobravanja.

Korak 3: Implementirajte OAuth 2.0 autentifikaciju

Aktuelna UPS dokumentacija za developere koristi autentifikaciju zasnovanu na OAuth-u za svoje API-je. Vaš server obično razmenjuje akreditive aplikacije kroz dokumentovani tok za dobijanje tokena i prima pristupni token. Zatim taj token uključuje u zaglavlje autorizacije API zahteva.

Držite autentifikaciju odvojeno od logike praćenja. Praktičan dizajn ima jednu komponentu koja pribavlja i kešira važeći token i drugu koja poziva krajnju tačku za praćenje. Komponenta za tokene treba da:

• Šalje akreditive samo na dokumentovanu UPS krajnju tačku za autorizaciju.
• Koristi tip sadržaja i parametre dodele navedene u aktuelnoj UPS dokumentaciji.
• Privremeno čuva token i ponovo ga koristi dok ne istekne, umesto da zahteva novi token za svaki broj za praćenje.
• Osvežava ili ponovo pribavlja token kada nastupi dokumentovani uslov isteka.
• Uklanja akreditive i tokene iz evidencija aplikacije, izveštaja o greškama i zahteva podršci.

Nemojte kopirati token iz sesije pregledača u trajnu integraciju. Backend servis je generalno bezbednije mesto za upravljanje akreditivima jer čuva tajne izvan javnog koda klijenta.

Korak 4: Napravite zahtev za praćenje

Koristite format zahteva prikazan u zvaničnoj referenci Tracking API-ja. Tipičan zahtev uključuje broj za praćenje u putanji ili parametrima zahteva, pristupni token u zaglavlju autorizacije i zaglavlja koja zahteva UPS API. Nemojte pretpostaviti da je broj za praćenje jedina obavezna vrednost: aktuelna referenca može navoditi verziju, transakciju, tip sadržaja ili zaglavlja za korelaciju.

Pojednostavljeni obrazac zahteva izgleda ovako:

GET [UPS tracking endpoint]/[tracking-number]
Authorization: Bearer [access-token]
Accept: application/json

Ovo je strukturni primer, a ne krajnja tačka koju treba kopirati i odmah koristiti. Koristite krajnju tačku, verziju, zaglavlja i nazive parametara objavljene u UPS dokumentaciji za vašu aplikaciju. Normalizujte broj za praćenje u skladu sa pravilima sopstvenih podataka o porudžbinama, ali nemojte uklanjati znakove osim ako dokumentacija prevoznika potvrđuje da je to bezbedno.

Korak 5: Mapirajte događaje u svoj model podataka

Odgovori prevoznika često sadrže više informacija od jedne oznake statusa. Pre izrade stranice namenjene korisnicima mapirajte odgovor u interni model, kao što su identifikator pošiljke, prevoznik, najnoviji status, kod događaja, opis događaja, vremenska oznaka događaja, lokacija, informacije o procenjenoj isporuci i vremenska oznaka isporuke kada je dostupna.

Sačuvajte originalni odgovor prevoznika kada to dozvoljavaju vaše politike čuvanja i privatnosti. Sirovi odgovor može pomoći u dijagnostikovanju greške u mapiranju ili objašnjenju zašto se vaš normalizovani status razlikuje od formulacije prevoznika. Istovremeno, izbegavajte prikazivanje tehničkih kodova događaja korisnicima bez razumljivog objašnjenja.

Nemojte svaki status tretirati kao konačan ishod isporuke. Na primer, događaj „u tranzitu“, izuzetak, pokušaj isporuke i događaj isporuke ne treba svesti na istu poruku korisniku. Napravite eksplicitna mapiranja i definišite šta se dešava kada UPS doda vrednost događaja koju vaš kod ne prepoznaje.

Korak 6: Dodajte ponovne pokušaje, validaciju i nadzor

Produkcijskoj integraciji je potrebno više od uspešnog zahteva u razvojnoj konzoli. Dodajte validaciju i operativne zaštitne mere:

• Validacija unosa: odbijte prazne, neispravne ili očigledno nepotpune brojeve za praćenje pre slanja zahteva.
• Vremenska ograničenja: sprečite da spor odgovor prevoznika blokira ceo proces naplate, podrške ili rada skladišta.
• Pravila ponovnih pokušaja: pažljivo ponovite privremene mrežne ili servisne greške uz odloženo ponovno slanje. Nemojte neprestano ponavljati pokušaje kod grešaka autentifikacije ili nevažećih brojeva za praćenje.
• Ograničenja brzine: pratite ograničenja i pravila korišćenja iz UPS dokumentacije. Keširajte nedavne rezultate kada vaš poslovni proces to dozvoljava.
• Nepoznate vrednosti: sačuvajte neprepoznati događaj za pregled umesto da ga pogrešno označite kao isporučen ili izgubljen.
• Uočljivost: beležite vreme zahteva, kategoriju odgovora i informacije o korelaciji bez zapisivanja tajni ili nepotrebnih ličnih podataka.

Sistem za praćenje takođe treba da definiše koliko često osvežava pošiljku. Prečesto periodično proveravanje može stvoriti nepotrebno opterećenje i možda neće doneti nove informacije. Preretko proveravanje može učiniti da stranica namenjena korisnicima deluje zastarelo. Izaberite interval na osnovu obima pošiljki, operativne hitnosti, pravila prevoznika i svežine podataka koja je korisnicima zaista potrebna.

Korak 7: Testirajte realistične scenarije

Testirajte više od uspešno isporučene pošiljke. Uključite nepoznat broj za praćenje, pošiljku u tranzitu, izuzetak, pošiljku sa više događaja, istekli token, vremensko ograničenje, neuspeh autorizacije i odgovor koji sadrži polja koja vaš parser ne očekuje. Ako UPS obezbeđuje zasebno testno okruženje ili testne akreditive, prvo pratite tu proceduru.

Proverite kompletan put od zahteva do korisničkog interfejsa. Potvrdite da odgovarajuća porudžbina dobija odgovarajuću pošiljku, da se vremenske oznake prikazuju u predviđenoj vremenskoj zoni, da duplirani događaji ne stvaraju duplirane poruke korisnicima i da prekid rada prevoznika ne prepisuje prethodno važeći status obmanjujućim tekstom.

Kada je API za praćenje više prevoznika bolji izbor

Direktna UPS integracija može biti odgovarajuća kada vaša operacija uglavnom šalje preko UPS-a i zahteva tesnu kontrolu nad procesom prevoznika. Postaje manje praktična kada se porudžbine mogu kretati kroz više prevoznika, tržišta, poštanskih operatera ili regionalnih dostavnih kompanija. U toj situaciji odvojeni ak kreditive, formati odgovora, rečnici statusa i pravila ponovnih pokušaja mogu povećati obim održavanja.

Usluga za više prevoznika, kao što je 17TRACK Tracking API, može ponuditi alternativni model integracije za aplikacije kojima je potrebno praćenje preko više prevoznika. Njenu developersku dokumentaciju treba direktno pregledati zbog podržanih prevoznika, formata zahteva, autentifikacije, uslova korišćenja i dostupnih mogućnosti. To ne znači da je automatski bolja od direktne UPS veze: pravi izbor zavisi od kombinacije prevoznika, zahteva za podacima, kontrole nad integracijom i komercijalnih ili regulatornih ograničenja.

Za pretragu namenjenu potrošačima, a ne developersku integraciju, 17TRACK stranica za praćenje može biti prikladnija od izgradnje API veze. Za internet prodavnicu kojoj su potrebna brendirana ažuriranja nakon kupovine, zasebno pregledajte relevantnu integraciju platforme umesto da dodajete API posao koji prodavnici nije potreban.

Uobičajene greške pri implementaciji

• Korišćenje starih primera: primer koda može upućivati na povučenu verziju, stari metod autentifikacije ili drugu UPS uslugu.
• Stavljanje tajni u frontend kod: sve što se isporučuje pregledaču treba tretirati kao dostupno za pregled.
• Pretpostavka da prazan rezultat znači da pošiljka ne postoji: proverite broj za praćenje, dozvole naloga, okruženje i poruku odgovora pre donošenja poslovnog zaključka.
• Mapiranje samo teksta: opisi statusa mogu da se razlikuju. Koristite dokumentovane kodove i sačuvajte nepoznate vrednosti za pregled.
• Zanemarivanje zahteva naloga i korišćenja: tehnički kod može biti ispravan, dok aplikacija nije konfigurisana za traženu uslugu.
• Osvežavanje bez poslovnog pravila: nepotrebno periodično proveravanje može povećati troškove, opterećenje i operativnu buku bez poboljšanja korisničkog iskustva.

Praktična lista za puštanje u rad

1. Potvrdite da aplikacija koristi aktuelnu UPS dokumentaciju i odobreno okruženje.
2. Proverite da se akreditive čuvaju na serverskoj strani i da se mogu promeniti.
3. Testirajte neuspeh autentifikacije, greške prevoznika, neispravan unos i vremenska ograničenja.
4. Uporedite normalizovane statuse sa originalnim odgovorom za reprezentativne pošiljke.
5. Postavite pravila osvežavanja i pratite obim zahteva.
6. Definišite odgovornost za neidentifikovane događaje, odložena ažuriranja i eskalacije korisnika.
7. Dokumentujte integraciju kako bi drugi programer mogao bezbedno da ažurira akreditive, verzije krajnjih tačaka i mapiranja statusa.

Česta pitanja

Da li mi je potreban UPS nalog za korišćenje Tracking API-ja?

Pregledajte aktuelne UPS zahteve za uvođenje i pristup na Developer Portalu. Pristup API-ju može zavisiti od registracije aplikacije, akreditiva, konfiguracije naloga i konkretne usluge koja se zahteva. Nemojte pretpostaviti da je prijava na javnu stranicu za praćenje zamenljiva sa pristupom developerskom API-ju.

Da li je UPS Tracking API besplatan?

Nemojte pretpostaviti da pristup API-ju nema komercijalne uslove ili uslove korišćenja. UPS objavljuje aktuelne informacije o uslugama i nalozima putem svojih zvaničnih kanala, a neki zahtevi mogu zavisiti od proizvoda, naloga ili ugovora. Direktno potvrdite primenljive uslove pre planiranja produkcionog budžeta.

Mogu li da pozovem UPS API direktno iz JavaScript-a u pregledaču?

Poziv iz pregledača može otkriti akreditive aplikacije i izazvati probleme sa zahtevima između različitih izvora, bezbednošću i kontrolom korišćenja. Integracija na serverskoj strani generalno je bezbedniji obrazac za čuvanje tajni, pribavljanje tokena, primenu pravila ponovnih pokušaja i ograničavanje pristupa podacima o pošiljkama.

Koliko često moja aplikacija treba da zahteva ažuriranja praćenja?

Koristite pravila osvežavanja zasnovana na dokumentovanim ograničenjima prevoznika, obimu pošiljki, operativnoj hitnosti i svežini koja je potrebna korisnicima. Keširajte nedavne rezultate kada je prikladno, koristite odloženo ponovno slanje nakon privremenih grešaka i nemojte ponavljano periodično proveravanje tretirati kao zamenu za dokumentovanu mogućnost događaja ili obaveštenja.

Da li treba da koristim direktnu UPS integraciju ili API za više prevoznika?

Direktna UPS integracija može odgovarati procesu usmerenom na UPS koji zahteva kontrolu specifičnu za prevoznika. API za više prevoznika može smanjiti broj integracija kada vaše pošiljke koriste više prevoznika. Pre izbora uporedite podržane prevoznike, autentifikaciju, polja podataka, zahteve pouzdanosti, uslove korišćenja i napor potreban za implementaciju.

Izvori

• UPS Developer Portal — zvanični katalog API-ja, pristup aplikacijama, autentifikacija i developerska dokumentacija.
• UPS Technology Integration — zvanične informacije o integraciji UPS tehnologije sa poslovnim sistemima.
• 17TRACK Tracking API — zvanična stranica proizvoda i developerska početna tačka za praćenje preko više prevoznika.
• 17TRACK API Documentation — zvanična API dokumentacija za autentifikaciju, zahteve i obradu odgovora.