Kako pratiti pošiljke iz Kine za Evropu i SAD pomoću jednog API-ja

Da biste pratili pošiljke iz Kine ka Evropi i SAD pomoću jednog API-ja, povežite svoj sistem za naručivanje sa uslugom za praćenje više prevoznika, registrujte svaku pošiljku pomoću njenog broja za praćenje i svih potrebnih podataka o prevozniku, a zatim ažuriranja praćenja objedinite u zajedničkom zapisu o pošiljci. Integracija mora da uzme u obzir međunarodne primopredaje, zakašnjela skeniranja i zasebne brojeve za praćenje dostave na poslednjoj deonici. Jedan API može objediniti pristup informacijama o praćenju, ali ne može kreirati događaje koje prevoznik nije prijavio.

Za programere i timove koji upravljaju e-trgovinom, cilj nije samo prikazivanje statusa. Potrebno je povezati svaku fizičku pošiljku sa odgovarajućom porudžbinom, obaveštavati kupce bez slanja obmanjujućih ažuriranja i prepoznati pošiljke koje zahtevaju intervenciju. Ovaj vodič objašnjava kako da napravite takav tok rada i kako da procenite uslugu kao što je 17TRACK Tracking API u odnosu na svoje stvarne rute slanja.

Počnite od rute slanja, a ne samo od zemlje odredišta

Pošiljka koja putuje iz Kine na adresu u Evropi ili SAD može proći kroz servis za prikupljanje, međunarodnu transportnu mrežu, carinsku obradu i prevoznika za dostavu u odredištu. Neke usluge slanja prikazuju sva ta kretanja pod jednim brojem za praćenje. Druge kasnije tokom putovanja obezbeđuju zasebnu referencu za dostavu.

Zato pokrivenost na nivou zemlje nije dovoljna za potvrdu integracije praćenja. Pružalac usluge može prepoznati prevoznika, a da pritom ne vrati svaki događaj koji vam je potreban za određeni proizvod slanja. Isto tako, skeniranje na mestu porekla ne potvrđuje da će skeniranja dostave na odredištu biti dostupna.

Pre integracije napravite inventar ruta koristeći pošiljke koje vaše poslovanje zaista šalje. Zabeležite izvornog pružaoca logističkih usluga, uslugu slanja, ciljno tržište, poznatog prevoznika za dostavu i formate brojeva za praćenje. Tokom testiranja evropska tržišta posmatrajte pojedinačno, umesto da pretpostavite da uspešna dostava u jednoj zemlji dokazuje pokrivenost čitavog regiona.

• Za operacije: utvrdite gde nedostaci u praćenju trenutno stvaraju ručni rad ili kontakte sa kupcima.
• Za razvoj: utvrdite koji sistemi kreiraju pošiljke, a koji sistemi zahtevaju ažuriranja.
• Za nabavku: proverite podršku za konkretne prevoznike i usluge u tom inventaru ruta.

Šta jedan API za praćenje treba da radi — i šta ne može da uradi

API za praćenje više prevoznika vašoj aplikaciji pruža zajednički integracioni sloj, umesto da ona zasebno obrađuje vezu sa svakim prevoznikom. U zavisnosti od usluge i načina integracije, aplikacija može preuzimati ažuriranja, primati povratne pozive ili koristiti kombinaciju oba pristupa. Pre projektovanja produkcionog toka rada proverite podržane mehanizme u dokumentaciji pružaoca usluge.

Korisna apstrakcija je dosledan model pošiljke. Vaš sistem za upravljanje porudžbinama ne bi trebalo da zahteva različitu poslovnu logiku za formulacije svakog prevoznika, iako bi trebalo da sačuva izvorne informacije radi podrške i istrage.

Objedinjeno praćenje ne garantuje neprekidnu fizičku vidljivost, procenu vremena dostave niti kompletnu carinsku istoriju. API veza može ispravno funkcionisati dok prevoznik nema novo skeniranje koje bi prijavio. Praćenje je takođe odvojeno od kupovine nalepnica za slanje, pripreme carinskih deklaracija i organizovanja usluga dostave. Nemojte pretpostaviti da su te funkcije uključene.

Izgradite integraciju oko zapisa na nivou pošiljke

1. Razdvojite porudžbine, pošiljke i identifikatore za praćenje

Jedna porudžbina u e-trgovini može sadržati više paketa, a ti paketi mogu stići u različito vreme. Koristite interni ID paketa ili pošiljke kao stabilni identifikator. Povežite porudžbinu kupca sa tim zapisom, a zatim mu pridružite identifikatore za praćenje prevoznika.

Praktični interni model treba da obuhvata:

• Interni ID porudžbine i ID paketa.
• Originalni broj za praćenje i identifikator prevoznika koji koristi API.
• Svaki potvrđeni broj za praćenje prevoznika u odredištu.
• Uslugu slanja i zemlju odredišta.
• Trenutni normalizovani status i originalni opis prevoznika.
• Vreme događaja, lokaciju događaja kada je navedena i vreme kada je vaš sistem primio ažuriranje.
• Status registracije, poslednju uspešnu sinhronizaciju i nerešene greške integracije.

Ovo su preporučena polja aplikacije, a ne tvrdnja da ih svaki pružalac usluge vraća. Držite internu šemu odvojeno od formata odgovora pružaoca kako buduća promena API-ja ne bi zahtevala redizajn baze podataka porudžbina.

2. Registrujte pakete na osnovu pouzdanog poslovnog događaja

Registrujte praćenje kada se paketu dodeli važeći broj, a ne svaki put kada neko pregleda stranicu porudžbine. Događaj kreiranja pošiljke iz vašeg skladišta ili sistema za porudžbine obično je bolji okidač. Ako je nalepnica poništena ili zamenjena, ažurirajte odnose između identifikatora paketa umesto da napušteni broj ostavite kao jedinu referencu za praćenje.

Proverite da li je broj prisutan i da li ga formatiranje u tabeli nije oštetilo. Sačuvajte značajne početne nule. Kada vaš sistem za slanje zna prevoznika, zadržite tu informaciju umesto da se u potpunosti oslanjate na automatsku identifikaciju: formati brojeva mogu da se preklapaju.

Pročitajte odgovor na registraciju na nivou pojedinačne pošiljke. Uspešan HTTP zahtev ne znači nužno da je svaka stavka u grupi prihvaćena. Greške čuvajte u redu za ponovni pokušaj i omogućite operativnom timu da reši nevažeće ili dvosmislene prijave.

3. Osmislite isporuku ažuriranja pre povezivanja obaveštenja kupcima

Ako izabrana usluga podržava webhooks, koristite njen dokumentovani mehanizam povratnih poziva za prijem ažuriranja. Proverite dostupni metod autentifikacije ili potpisivanja umesto da sami izmišljate zaglavlje za verifikaciju. Čuvajte akreditive na serveru, zahtevajte HTTPS i izbegavajte uključivanje API tajni u kod pregledača ili linkove namenjene kupcima.

Vaš prijemnik treba trajno da prihvati ažuriranje pre nego što ga potvrdi, a zatim da ga obrađuje asinhrono. Predvidite duplirane isporuke i događaje koji stižu van redosleda. Koristite ID događaja pružaoca kada je dostupan; u suprotnom definišite dokumentovano pravilo za uklanjanje duplikata koristeći stabilne atribute događaja.

Ako je potrebno periodično preuzimanje, rasporedite ga u okviru dokumentovanih ograničenja pružaoca i svojih operativnih potreba. Nakon odgovora o ograničenju učestalosti smanjite učestalost zahteva, izbegavajte sinhronizovane nalete ponovnih pokušaja i obustavite nepotrebne provere završenih pošiljaka u skladu sa pravilima čuvanja i usaglašavanja podataka. Planirani posao za usaglašavanje takođe može pomoći u otkrivanju propuštenih ažuriranja tamo gde usluga dozvoljava njihovo preuzimanje.

4. Normalizujte statuse bez gubitka značenja

Koristite mali skup internih statusa koje vaš sistem za porudžbine i tim za podršku mogu dosledno da tumače. Primeri obuhvataju informacije primljene, u transportu, kod dostavljača, dostavljeno, problem pri dostavi i vraćeno. Ovo su predložene kategorije aplikacije, a ne opis tačnih kodova statusa bilo kog pružaoca usluge.

Detaljan događaj prevoznika čuvajte zajedno sa normalizovanim statusom. Neuspešan pokušaj dostave, problem sa adresom i kašnjenje povezano sa carinom mogu zahtevati pažnju, ali ne zahtevaju isti odgovor. Mapiranje svega u generički izuzetak olakšalo bi čuvanje podataka, ali bi ih učinilo manje korisnim za postupanje.

Nemojte prevoditi kreiranje nalepnice u fizičko preuzimanje. Isto tako, nemojte označiti paket kao ocarinjen samo zato što događaj pominje carinski objekat. Koristite jezik koji odgovara stvarnom značenju događaja.

Izričito obradite međunarodne primopredaje

Najvažniji test integracije često je prelaz između mreže porekla i dostave na odredištu. Sačuvajte i originalnu referencu i svaku potvrđenu referencu za poslednju deonicu dostave. Novi broj za praćenje treba da postane još jedan identifikator iste pošiljke, a ne automatski druga pošiljka.

Identifikatore povezujte samo kada odnos potiče iz pouzdanog izvora, kao što su logistički pružalac, odgovor za praćenje ili vaš sistem za slanje. Slično vreme događaja ili podudarne zemlje odredišta nisu dovoljni da dokažu da dva broja pripadaju istoj pošiljci.

Vreme događaja držite odvojeno od vremena unosa. Stariji događaj može stići u vaš sistem posle novijeg, naročito kada se informacije kreću između mreža. Sačuvajte navedene pomake vremenske zone, normalizujte vremenske oznake radi obrade i zadržite dvosmislene izvorne vrednosti umesto da im dodelite nepodržanu vremensku zonu.

Kupcima prikažite najnoviji smisleni status sa vidljivim vremenom ažuriranja. Ako prevoznik na odredištu još nije prijavio skeniranje, objasnite da praćenje čeka novo ažuriranje. Nemojte zaključivati da je paket izgubljen, da se i dalje fizički nalazi na mestu poslednjeg skeniranja ili da se već nalazi u zemlji odredišta.

Gde se 17TRACK uklapa u ovaj tok rada

Ponuda Tracking API-ja kompanije 17TRACK relevantna je kada vašoj aplikaciji treba integracija praćenja više prevoznika. Njena zvanična API dokumentacija treba da usmerava implementaciju autentifikacije, registracije, obrade odgovora i podržanih tokova ažuriranja. Koristite dokumentovani API ugovor umesto da korisničku stranicu za praćenje tretirate kao integracioni interfejs.

Procenite ga prema istim operativnim zahtevima koje biste primenili na sopstvenu implementaciju: ispravna identifikacija prevoznika, korisni događaji na vašim rutama, kontinuitet primopredaje, oporavak od grešaka i upravljiva isporuka ažuriranja. Pre nego što se obavežete na produkcioni dizajn, potvrdite komercijalne uslove, obračun korišćenja, ograničenja zahteva i svu potrebnu konfiguraciju naloga.

Najvažniji razlog za izbor objedinjenog API-ja jeste smanjena složenost integracije za rute kojima zaista upravljate. Tu korist ipak treba potvrditi reprezentativnim paketima. Nijedan pružalac usluge ne bi trebalo da bude izabran samo zato što njegov opšti opis pokrivenosti zvuči široko.

Sprovedite pilot-projekat zasnovan na rutama pre uvođenja

Koristite skup za testiranje koji obuhvata uobičajene dostave i teške slučajeve. Istorijske pošiljke pomažu pri testiranju mapiranja statusa, dok aktivne pošiljke otkrivaju isporuku ažuriranja i operativno vreme. Nijedan test sam po sebi ne daje odgovor na svako pitanje.

• Dostava iz Kine u SAD: proverite događaje na mestu porekla, eventualnu međunarodnu primopredaju i konačni događaj dostave.
• Dostave iz Kine u Evropu: testirajte zemlje odredišta i usluge slanja koje zaista koristite.
• Nova nalepnica: potvrdite da paket bez fizičkog skeniranja nije predstavljen kao da se kreće.
• Promenjena referenca za dostavu: potvrdite da odnos ostaje povezan sa ispravnim paketom.
• Problem pri dostavi: proverite da li detaljan razlog stiže do odgovarajućeg operativnog reda.
• Podeljena porudžbina: potvrdite da dostava jednog paketa ne zatvara celu porudžbinu.
• Duplirano ili zakašnjelo ažuriranje: potvrdite da ne stvara ponovljene poruke niti pogrešno prepisuje noviji status.
• Privremeni kvar integracije: proverite ponovni pokušaj, usaglašavanje i vidljivost za podršku.

Postavite kriterijume prihvatanja pre pregleda rezultata. Merite uspešnost registracije, pogrešna dodeljivanja prevoznika, nedostajuće ključne događaje, kašnjenja u obradi ažuriranja i duplirane poruke kupcima. Definišite prihvatljive pragove za svoje poslovanje umesto da preuzimate nepodržanu univerzalnu referentnu vrednost. Nedostajući događaj proverite u sopstvenom zapisu prevoznika pre nego što prazninu pripišete API-ju.

Pratite svežinu podataka odvojeno od dostupnosti API-ja

API Monitoring treba da odgovori na dva različita pitanja: da li integracija funkcioniše i da li su informacije o pošiljci korisne? Uspešni zahtevi odgovaraju samo na prvo pitanje. Takođe morate znati da li se greške pri registraciji gomilaju, da li povratni pozivi ne uspevaju ili je ruta prestala da proizvodi očekivane ključne događaje.

• Zdravlje integracije: greške autentifikacije, greške zahteva, odgovori o ograničenju učestalosti, neuspeli povratni pozivi i zaostaci u redovima.
• Kvalitet podataka: nepoznati statusi, neispravne vremenske oznake, nerešeni identiteti prevoznika i neočekivane promene identifikatora.
• Svežina pošiljke: vreme od poslednjeg događaja prevoznika, segmentirano po ruti i usluzi slanja.
• Poslovni uticaj: opterećenje izazvano izuzecima, neuspešna obaveštenja i porudžbine pogrešno označene kao završene.

Dug period bez skeniranja može biti normalan kod jedne usluge slanja, a neuobičajen kod druge. Koristite očekivanja specifična za rutu i zabeleženu istoriju pošiljaka da biste odredili prioritete istraga. Upozorenje o grešci integracije držite odvojeno od upozorenja o kašnjenju pošiljke kako bi ga primio pravi tim.

Obaveštenja kupcima treba da prate potvrđene ključne događaje, a ne svaki sirovi događaj. Potisnite duplikate, razlikujte pokušaj dostave od završene dostave i izbegavajte obećavanje datuma dolaska koje osnovni podaci ne podržavaju. Ograničite pristup podacima praćenja i čuvajte lične podatke samo tamo gde ih vaš tok rada zahteva.

Česta pitanja

Može li jedan API da prati i kineskog prevoznika na mestu porekla i prevoznika za dostavu na odredištu?

Usluga za više prevoznika može objediniti događaje iz oba dela putovanja kada su relevantne usluge i odnosi između identifikatora podržani. Potvrdite celu rutu stvarnim paketima. Samo prepoznavanje izvornog broja za praćenje ne dokazuje da će informacije o dostavi na odredištu biti dostupne.

Zašto praćenje prestaje da se ažurira nakon što paket napusti Kinu?

Mogući razlozi obuhvataju prazninu između fizičkih skeniranja, zakašnjelo prijavljivanje ili primopredaju drugoj referenci za dostavu. Proverite sirove događaje i svaki navedeni broj za poslednju deonicu dostave, a zatim ih uporedite sa zapisom relevantnog prevoznika. Sama praznina u praćenju ne dokazuje da je paket izgubljen ili zadržan na carini.

Da li aplikacija treba da koristi webhooks ili periodično preuzimanje?

Koristite mehanizme koje je dokumentovao vaš pružalac usluge. Kada su podržani, webhooks mogu smanjiti broj ponovljenih provera, dok dozvoljeni zahtevi za preuzimanje mogu podržati usaglašavanje. U oba pristupa pre oslanjanja na ažuriranja za komunikaciju sa kupcima uvedite obradu duplikata, kontrolu ponovnih pokušaja i nadzor.

Može li API za praćenje garantovati datum dostave ili carinjenje?

Podaci o praćenju ne predstavljaju garanciju ni za jedno od toga. Ako je naveden procenjeni datum dostave, sačuvajte njegov izvor i prikažite ga kao procenu. Skeniranja povezana sa carinom treba opisati prema njihovoj stvarnoj formulaciji, a ne tumačiti kao carinjenje osim ako izričito ukazuju na takav ishod.

Šta treba proveriti pre izbora API plana?

Potvrdite svoje prevoznike i usluge slanja, zahteve za registraciju, načine ažuriranja, obračun korišćenja, ograničenja zahteva, dostupnost podataka i aranžmane podrške. Pitajte kako se komercijalno tretiraju zamenjeni brojevi, ponovljene registracije i istorijska pretraživanja. Za zahteve koji utiču na budžet ili arhitekturu koristite aktuelnu dokumentaciju i pisanu potvrdu.

Izvori

• 17TRACK Tracking API — zvanična referenca proizvoda za ponudu API-ja za praćenje.
• 17TRACK API documentation — zvanična tehnička referenca za implementaciju integracije. Pre razvoja ovde potvrdite tačne formate zahteva, podržane tokove rada i ograničenja.