Kako objediniti praćenje pošiljki širom Australije i Novog Zelanda pomoću jednog API-ja

Da biste objedinili praćenje pošiljaka širom Australije i Novog Zelanda pomoću jednog API-ja, povežite svoj sistem za porudžbine ili ispunjavanje porudžbina sa uslugom za praćenje više prevoznika, registrujte svaku pošiljku sa ispravnim identitetom prevoznika i prevedite pristigla ažuriranja praćenja u dosledan interni model događaja. Integracija treba da zadrži detalje specifične za prevoznika, a da vašem operativnom timu i korisnicima pruži jedinstveno iskustvo praćenja za domaće i trans-Tasmanske isporuke.

Za programere, operatere u elektronskoj trgovini i logističke timove, glavni izazov nije slanje prvog API zahteva. Izazov je održati doslednost identiteta pošiljaka, statusa isporuke, predaje između prevoznika i obaveštenja korisnicima kada različiti prevoznici na različite načine opisuju isto putovanje. Ovaj vodič objašnjava kako da osmislite takvu integraciju, procenite API za praćenje i testirate ga pre nego što se na njega oslonite u produkciji.

Definišite šta jedan API treba da objedini

Zajednički API vašoj aplikaciji pruža jedinstvenu tačku integracije. On ne primorava svakog prevoznika da objavljuje identične informacije ili da skenira pakete istom učestalošću. Vaša arhitektura treba da razlikuje dosledan interfejs od potpune vidljivosti.

Počnite od inventara pošiljaka zasnovanog na stvarnoj aktivnosti ispunjavanja porudžbina, a ne od opšte liste prevoznika koji posluju u bilo kojoj od dve zemlje. Uključite domaće pošiljke u Australiji, domaće pošiljke na Novom Zelandu i prekogranična kretanja u oba smera. Dodajte i druge međunarodne polazne tačke ako su deo vašeg poslovanja.

• Prevoznik i usluga: Zabeležite prevoznika, korišćenu uslugu i svakog poznatog partnera za isporuku.
• Ruta: Razlikujte polazište i odredište pošiljke od lokacije njenog poslednjeg skeniranja.
• Identifikatori: Sačuvajte referencu porudžbine, referencu ispunjavanja porudžbine, broj za praćenje i svaki zamenski ili partnerski broj.
• Operativna svrha: Navedite da li ažuriranja podržavaju praćenje korisnika, upravljanje izuzecima, potvrdu isporuke ili sve navedeno.
• Potrebni detalji: Odlučite da li je dovoljan opšti status isporuke ili su agentima potrebni i opisi skeniranja, lokacije i vremenske oznake.

Ovaj inventar postaje vaša kontrolna lista za prihvatanje. Opšta pokrivenost prevoznika koju pruža neki provajder korisna je za uži izbor, ali odluka treba da se zasniva na tome da li vaše stvarne kombinacije prevoznika i usluga vraćaju upotrebljive informacije o praćenju.

Procenite API za praćenje u odnosu na strukturu svojih pošiljaka

17TRACK nudi Tracking API, što ga čini relevantnom opcijom za procenu u integraciji sa više prevoznika. Koristite njegovu zvaničnu API dokumentaciju da proverite aktuelne zahteve za integraciju. Podršku prevoznika, polja događaja, ponašanje ažuriranja, ograničenja naloga i komercijalne uslove tretirajte kao stavke koje treba proveriti za svoju implementaciju, a ne kao pretpostavke izvedene iz kategorije proizvoda.

Postavite ista praktična pitanja za svaki API koji razmatrate:

• Može li da identifikuje i prati prevoznike i usluge iz vašeg inventara pošiljaka?
• Kada je detekcija prevoznika nejasna, možete li proslediti eksplicitni identifikator prevoznika?
• Kako vaša aplikacija prima ažuriranja i koji mehanizam oporavka postoji ako se ažuriranje propusti?
• Koji izvorni detalji prevoznika ostaju dostupni uz normalizovane statuse?
• Šta se dešava kada je broj za praćenje nevažeći, još nije prepoznat ili je povezan sa više mogućih prevoznika?
• Kako su za vaš nalog definisani korišćenje, naplata, trajanje praćenja i ograničenja pristupa?

Preporučeno pravilo odlučivanja: birajte na osnovu uspešnih testova stvarnih obrazaca slanja, a ne najvećeg istaknutog broja prevoznika. Integracija je odgovarajuća kada pruža dovoljno informacija za podršku vašim operativnim odlukama i dovoljno jasno prikazuje greške da biste mogli da ih otklonite.

Izgradite interni model koji podnosi razlike među prevoznicima

Razdvojite porudžbine, pošiljke i deonice praćenja

Nemojte koristiti broj za praćenje kao primarni ključ porudžbine. Jedna porudžbina može sadržati više paketa, a putovanje jednog paketa može uključivati više identifikatora za praćenje. Umesto toga, kreirajte interni ID pošiljke i povežite zapise o praćenju sa njim.

Praktičan model ima tri nivoa: porudžbinu korisnika, njene fizičke pošiljke i deonice praćenja povezane sa svakom pošiljkom. Domaćem paketu možda je potrebna samo jedna deonica praćenja. Prekograničnom paketu mogu biti potrebni povezani zapisi kada drugi prevoznik ili identifikator postane relevantan.

Odredite zapis o praćenju prema prevozniku, kao i prema broju za praćenje, i zadržite njegovu vezu sa ID-jem pošiljke. Ako se pojavi novi broj partnera za isporuku, dodajte ga kao povezani identifikator umesto da zamenite originalni. Time se čuva istorija koja je agentima podrške potrebna pri ispitivanju predaje pošiljke.

Čuvajte sirovi događaj i normalizovani događaj

Koristite mali interni rečnik statusa na osnovu kog vaše poslovanje može da postupa. Na primer, možete definisati: pre tranzita, u tranzitu, kod kurira za isporuku, dostupno za preuzimanje, isporučeno, izuzetak i nepoznato. To su predložene interne kategorije, a ne tvrdnja o šemi statusa određenog provajdera.

Sačuvajte originalni opis prevoznika uz mapirani status. Događaj na mestu za preuzimanje i problem sa adresom mogu zahtevati reakciju korisnika, ali ne bi trebalo da proizvedu istu poruku. Isto tako, kreiranje etikete ne bi automatski trebalo da postane dokaz da prevoznik fizički poseduje paket.

Dokumentujte odluke o mapiranju u verzionisanoj konfiguraciji. Kada se pojavi novi opis događaja, stavite ga u red za proveru ako njegovo značenje nije jasno. Eksplicitno stanje „nepoznato“ bezbednije je od samouverenog dodeljivanja pogrešnog ishoda isporuke.

Razlikujte vreme događaja od vremena prijema

Čuvajte vreme kada se događaj desio odvojeno od vremena kada ga je vaš sistem primio. Starije skeniranje može stići nakon novijeg, naročito kada su ažuriranja odložena ili kada se istorijski događaji dostavljaju zajedno.

Za Australiju i Novi Zeland izbegavajte primenu jednog fiksnog pomeranja vremena na svaku pošiljku. Sačuvajte izvorne vremenske oznake i pomeranja kada su dostupni. Za prikaz koristite odgovarajuću imenovanu vremensku zonu kada imate pouzdan kontekst lokacije i uzmite u obzir razlike zbog letnjeg računanja vremena. Ako izvorna vremenska zona nedostaje, zadržite tu neizvesnost umesto da izmišljate preciznu UTC konverziju.

Implementirajte pouzdan tok prijema podataka

1. Prvo kreirajte internu pošiljku. Zabeležite njenu vezu sa porudžbinom, rutu, izbor prevoznika i identifikator za praćenje pre registracije kod usluge za praćenje.
2. Pošaljite registraciju praćenja. Koristite dokumentovani format zahteva provajdera. Sačuvajte odgovor i razlikujte uspešnu registraciju od kasnije dostupnosti događaja prevoznika.
3. Klasifikujte greške. Razdvojite nevažeći unos i probleme sa autentifikacijom od privremenih kvarova usluge. Ponovite zahtev samo tamo gde ponavljanje razumno može pomoći.
4. Primajte ili preuzimajte ažuriranja. Implementirajte mehanizam isporuke koji podržava izabrani API. Ako koristite webhooks, proverite pristigle zahteve metodom dokumentovanim od strane provajdera i obrađujte prihvaćene događaje kroz trajni red.
5. Uklonite duplikate pre primene promena. Koristite identifikator događaja provajdera kada je dostupan ili pažljivo osmišljen složeni ključ. Ponovljena isporuka ne sme pokrenuti ponovljena obaveštenja korisnicima.
6. Ponovo izračunajte stanje pošiljke. Procenu zasnivajte na značenju i hronologiji događaja, umesto da trenutni status zamenite onim ažuriranjem koje je poslednje stiglo.
7. Uskladite nepotpune zapise. Kada API podržava preuzimanje, koristite ga za ispitivanje propuštenih ažuriranja ili zastarelih zapisa u okviru važećih ograničenja korišćenja.

Autentifikaciju specifičnu za provajdera, nazive polja i obradu grešaka držite unutar adaptera. Vaš sistem za upravljanje porudžbinama treba da koristi vaš interni model pošiljke, a ne da direktno zavisi od svakog detalja odgovora provajdera. To razdvajanje takođe olakšava testiranje budućih promena API-ja.

Obradite trans-Tasmanska putovanja bez izmišljanja izvesnosti

Prekograničnom praćenju potrebno je više konteksta od niza oznaka statusa. Vaša aplikacija treba da razlikuje izvozni događaj, događaj povezan sa carinom, predaju između prevoznika i događaj konačne isporuke kada izvorni podaci podržavaju te razlike.

Nemojte zaključivati da je carinjenje završeno na osnovu opšteg skeniranja „u tranzitu“. Isto tako, odsustvo nedavnog skeniranja ne dokazuje da carina zadržava paket. Korisna poruka korisniku navodi poslednji potvrđeni događaj i njegovo vreme, a zatim objašnjava narednu radnju koju vaš tim zaista može da podrži.

Polazište i odredište držite odvojeno od lokacije skeniranja. Pošiljka koja putuje iz Australije na Novi Zeland ne postaje domaća novozelandska pošiljka samo zato što je primila skeniranje po dolasku. Ta razlika je važna za izveštavanje o rutama i odgovornost za izuzetke.

Ako se uključi partner za isporuku, povežite njegov zapis o praćenju samo kada je odnos podržan podacima o pošiljci, uslugom za praćenje ili operativno proverenim zapisom. Nemojte spajati pakete samo zato što njihovi identifikatori izgledaju slično.

Pretvorite događaje praćenja u korisna ažuriranja za korisnike

Stranica namenjena korisnicima treba da odgovori na četiri pitanja: koji je poslednji potvrđeni status, kada se to dogodilo, gde je zabeleženo ako je poznato i da li korisnik treba da preduzme nešto?

Pravila za obaveštenja držite odvojeno od prijema događaja. Nije svako skeniranje zaslužuje imejl ili tekstualnu poruku. Definišite značajne prelaze, kao što su prvo potvrđeno kretanje, pokušaj isporuke, zahtev za preuzimanje ili događaj isporuke, i sprečite ponovljena upozorenja za isti prelaz.

• Zastarelo praćenje: Navedite kada je došlo do poslednjeg ažuriranja, a da tišinu ne predstavljate kao dokaz gubitka.
• Procene isporuke: Razlikujte procenu koju je obezbedio prevoznik od obećanja trgovca. Nemojte izmišljati datum kada nijedan od njih ne postoji.
• Izuzeci: Kada je poznat, navedite konkretan sledeći korak umesto prikazivanja neobjašnjene oznake greške.
• Prigovori na isporuku: Sačuvajte izvorni događaj i prosledite slučaj podršci; sam status „isporučeno“ ne rešava svaki spor sa korisnikom.

Zaštitite stranice za praćenje, kao i API akreditive. Izbegavajte izlaganje nepotrebnih podataka o adresi ili kontaktu, čuvajte servisne akreditive na serveru i primenite kontrole pristupa primerene prikazanim informacijama.

Sprovedite pilot zasnovan na rutama pre uvođenja

Testirajte domaće australijske, domaće novozelandske, australijsko-novozelandske i novozelandsko-australijske pošiljke tamo gde su te rute relevantne za vaše poslovanje. Uključite uobičajene isporuke i operativne granične slučajeve: podeljene porudžbine, neprepoznate brojeve, predaje, pokušaje isporuke, događaje preuzimanja, povrate i kasno pristigla skeniranja.

Koristite stvarne zapise pošiljaka sa odgovarajućom dozvolom za proveru prevoznika. Koristite sintetičke događaje za testiranje otpornosti sopstvene aplikacije, ali sintetičke rezultate nemojte tretirati kao dokaz aktivne pokrivenosti prevoznika.

• Provera identiteta: Svako ažuriranje stiže do ispravne pošiljke i porudžbine.
• Provera hronologije: Događaji van redosleda ne vraćaju napredak isporuke pogrešno unazad.
• Provera oporavka: Privremene greške i duplirana ažuriranja ne dovode do gubitka podataka ili ponavljanja upozorenja.
• Provera podrške: Agenti mogu da pregledaju originalni događaj i razumeju status prikazan korisniku.
• Komercijalna provera: Očekivano korišćenje odgovara potvrđenom modelu naplate i ograničenjima naloga.

Postavite pragove prihvatanja pre procene pilota. Merite ishode registracije, nemapirane događaje, kašnjenja obrade, duplikate obaveštenja i nerešene zastarele pošiljke. Razdvojite kašnjenja podataka prevoznika od kašnjenja unutar sopstvene aplikacije kako bi otklanjanje problema dospelo do odgovorne osobe.

Implementacija je spremna kada vaš tim može da objasni i oporavi se od nepotpunog praćenja, a ne samo da prikaže uspešne isporuke. Jedan API pojednostavljuje povezivanje; vaš model pošiljke, pravila događaja i operativne procedure čine to povezivanje pouzdanim.

Česta pitanja

Da li jedan API za praćenje zamenjuje integracije za slanje kod prevoznika?

Ne nužno. Praćenje, kreiranje etiketa, zakazivanje preuzimanja, obračun cena i carinska dokumentacija predstavljaju odvojene funkcije. Proverite obim izabranog proizvoda i zadržite druge integracije tamo gde ih vaš proces ispunjavanja porudžbina zahteva.

Mogu li da registrujem broj za praćenje pre prvog skeniranja prevoznika?

Proverite pravila registracije API-ja. Osmislite aplikaciju tako da razlikuje prihvaćenu registraciju praćenja od potvrđenog fizičkog kretanja. Zapis bez događaja ne treba automatski prikazivati kao „u tranzitu“.

Da li će jedan API pružati ažuriranja u realnom vremenu za svakog prevoznika?

Nemojte to pretpostavljati. Svežina od početka do kraja zavisi od toga kada prevoznik objavljuje podatke, kada ih usluga za praćenje preuzima i kada ih vaša aplikacija obrađuje. Potvrdite ponašanje ažuriranja za kombinacije prevoznika i usluga koje koristite.

Šta treba da se desi kada se broj za praćenje promeni?

Zadržite originalni identifikator i povežite potvrđeni zamenski ili partnerski identifikator sa istom internom pošiljkom. Sačuvajte obe istorije i sprečite da duplirani zapisi generišu protivrečna obaveštenja.

Da li je 17TRACK relevantan za ovu integraciju?

Da. Njegov Tracking API relevantan je za integraciju sa više prevoznika opisanu ovde. Procenite ga pomoću uzoraka svojih australijskih i novozelandskih pošiljaka i pre uvođenja potvrdite podršku prevoznika, tehničko ponašanje i uslove naloga putem zvaničnih API resursa.

Izvori

• 17TRACK Tracking API — zvanični resurs proizvoda za API opciju razmatranu u ovom vodiču.
• 17TRACK API documentation — zvanična tehnička referenca za proveru formata zahteva, zahteva integracije i podržanog ponašanja.