Skip to main content
ПочетакБлогVodičiKako povezati podatke o praćenju pošiljke sa Oms-om: Mapiranje porudžbina i pravila sinhronizacije

Kako povezati podatke o praćenju pošiljke sa Oms-om: Mapiranje porudžbina i pravila sinhronizacije

17TRACK

Da biste povezali podatke o praćenju pošiljki sa sistemom za upravljanje porudžbinama (OMS), mapirajte svaki praćeni paket na interni zapis pošiljke, a zatim povežite tu pošiljku sa njenom porudžbinom i stavkama ispunjenja. Primajte ažuriranja praćenja preko interfejsa koji provajder podržava, sačuvajte originalne događaje i primenite eksplicitna pravila za duplikate, zakašnjela ažuriranja, status pošiljke i završetak porudžbine. Nemojte koristiti samo broj za praćenje kao identifikator porudžbine niti dozvoliti da jedan događaj dostave automatski zatvori porudžbinu sa više paketa.

Kako povezati podatke o praćenju pošiljki sa OMS porudžbinom

Ovaj vodič je namenjen inženjerima za integraciju i timovima za operacije u e-trgovini koji implementiraju ovu vezu. Preporučeni dizajn razdvaja zapažanja prevoznika od poslovnih odluka: podaci o praćenju opisuju putanju paketa, dok OMS odlučuje šta ta putanja znači za ispunjenje, komunikaciju sa kupcem i zatvaranje porudžbine.

Definišite koji sistem je vlasnik svakog zapisa

Pre izgradnje API veze, dogovorite vlasništvo sa administratorom OMS-a, timom za ispunjenje i timom korisničke službe. U suprotnom, tehnički uspešna integracija i dalje može prebrisati važeće poslovne podatke.

  • OMS: Vlasnik je porudžbina, stavki porudžbina, potrebnih količina, otkazivanja i pravila za završetak porudžbine.
  • Sistem za ispunjenje: Vlasnik je zapisa pošiljki ili paketa koje kreira, uključujući raspodele pakovanja i dodelu nalepnica. To može biti sam OMS ili zaseban sistem skladišta.
  • Provajder praćenja: Dostavlja zapažanja o praćenju i sve klasifikacije statusa koje definiše provajder.
  • Integracioni sloj: Vlasnik je unakrsnih referenci identifikatora, obrade događaja, normalizacije, rukovanja ponovnim pokušajima i revizorskih zapisa sinhronizacije.

Ove granice tretirajte kao preporučene, a ne kao pretpostavke o vašem softveru. Dokumentujte izuzetke. Na primer, ako skladište može zameniti transportnu nalepnicu, integraciji je potrebno eksplicitno ažuriranje iz tog sistema, umesto nagađanja da novouočeni broj zamenjuje stari.

Izgradite mapiranje porudžbine na paket pre sinhronizacije statusa

Praktična veza je porudžbina → ispunjenje → paket → dodela praćenja. Vaš OMS može koristiti drugačije nazive ili kombinovati neke od ovih zapisa. Sačuvajte veze čak i ako se struktura baze podataka razlikuje.

Porudžbina može imati više ispunjenja, a ispunjenje može sadržati više paketa. Paket takođe može dobiti zamensku dodelu praćenja ili povezani identifikator poslednje milje. Ti identifikatori ne treba da stvaraju dodatne naručene količine.

ZapisPreporučena poljaSvrha
PorudžbinaID zakupca ili prodavnice, nepromenljivi OMS ID porudžbineRazdvaja trgovce i sprečava zavisnost od prikazanih brojeva porudžbina.
IspunjenjeID ispunjenja, ID porudžbine, ID-ovi stavki i količine raspodeleIdentifikuje koji se kupljeni artikli ispunjavaju.
PaketInterni ID paketa, ID ispunjenja, raspodele paketa kada su dostupneObezbeđuje stabilan identitet nezavisan od transportnih nalepnica.
Dodela praćenjaID dodele, ID paketa, nalog provajdera, identifikator prevoznika, broj za praćenje, period aktivacijePovezuje pristigla zapažanja o praćenju sa odgovarajućim paketom i životnim ciklusom dodele.

Usklađujte ažuriranja putem sačuvane unakrsne reference

Kada se pošiljka kreira, sačuvajte njene interne ID-ove pre nego što je registrujete za praćenje. Sačuvajte svaki ID zapisa praćenja koji provajder vrati kroz dokumentovani proces registracije. Ako provajder podržava referencu trgovca, koristite neprozirnu internu referencu i lokalno sačuvajte mapiranje.

Za pristigla ažuriranja najpre pronađite sačuvani ID zapisa provajdera u okviru odgovarajućeg naloga provajdera i zakupca. Ako taj identifikator nije dostupan, koristite dokumentovanu kombinaciju broja za praćenje, identiteta prevoznika, konteksta naloga i istorije dodele. Tretirajte ovo kao strategiju pretrage, a ne kao garanciju da je kombinacija globalno jedinstvena.

Nemojte uparivati na osnovu imena kupca, imejl adrese ili prikazanog broja porudžbine bez opsega. Brojeve za praćenje čuvajte kao stringove kako bi početne nule ostale sačuvane. Izbegavajte uklanjanje znakova ili promenu veličine slova, osim ako relevantni ugovor sa prevoznikom ili provajderom dozvoljava takvu normalizaciju.

Ako pretraga ne vrati nijedno podudaranje ili vrati više mogućih podudaranja, stavite ažuriranje u karantin radi istrage. Nerazrešen događaj je bezbedniji od samouverenog ažuriranja porudžbine pogrešnog kupca.

Rukujte podeljenim porudžbinama bez izmišljanja raspodele paketa

Razmotrite ilustrativnu porudžbinu koja sadrži tri jedinice. Paket A nosi dve jedinice, a paket B jednu. Dostava paketa A znači da postoje dokazi o dostavi za dve jedinice; to ne znači da je cela porudžbina dostavljena.

Ako sistem za ispunjenje beleži samo da oba paketa pripadaju istom ispunjenju, nemojte izmišljati raspodele na nivou jedinice. I dalje možete izračunati da li su svi potrebni paketi dostavljeni, ali izveštavanje o dostavi na nivou artikla treba da ostane nedostupno ili izričito neizvesno dok podaci o raspodeli ne budu dostupni.

Povežite API za praćenje preko trajnog sloja za unos

Koristite proces koji komunikaciju sa provajderom drži odvojenom od upisa u OMS:

Kreiranje pošiljke → registracija praćenja → pristiglo ažuriranje ili zakazano preuzimanje → trajno čuvanje događaja → mapiranje i normalizacija → ažuriranje OMS-a → usaglašavanje

Za implementaciju 17TRACK-a, stranica proizvoda Tracking API i zvanična API dokumentacija predstavljaju relevantne početne tačke. Pre implementacije adaptera potvrdite primenljivi interfejs za registraciju, identifikatore prevoznika, opcije dostave ažuriranja, zahteve za autentifikaciju, definicije statusa i ograničenja naloga. Model podataka u ovom vodiču predstavlja preporuku za integraciju, a ne tvrdnju da 17TRACK koristi ova imena polja ili obezbeđuje nativni konektor za vaš OMS.

Ako vaš izabrani provajder podržava webhook-ove, autentifikujte pristigle zahteve koristeći njegov dokumentovani mehanizam i trajno sačuvajte prihvaćene poruke pre potvrde prijema. Spore OMS operacije držite izvan putanje zahteva. Pratite stvarni ugovor provajdera o potvrdi prijema i ponovnim pokušajima, umesto pretpostavke o određenom telu odgovora ili vremenskom ograničenju.

Ako je potrebno periodično preuzimanje, sačuvajte napredak preuzimanja tamo gde ga API podržava, kontrolišite konkurentnost i poštujte dokumentovana ograničenja brzine. Ni prijem webhook-a ni uspešan zahtev za periodično preuzimanje ne dokazuju da je OMS ažuriran; te rezultate beležite zasebno.

Definišite pravila sinhronizacije koja podnose ponovne pokušaje i zakašnjele događaje

1. Učinite obradu idempotentnom

Obrada istog zapažanja dva puta ne bi trebalo da duplira pošiljku, dvaput uveća količine ili ponovo pošalje isto obaveštenje kupcu. HTTP ne čini proizvoljnu POST operaciju idempotentnom; integracija mora implementirati zaštitu od duplikata. RFC 9110 objašnjava idempotentnost HTTP metoda.

Koristite stabilan ID događaja provajdera kada je dokumentovan i dostupan. U suprotnom, definišite otisak na osnovu ID-a dodele i relevantnih polja događaja, kao što su vremenska oznaka događaja, izvorni status i lokacija. Dokumentujte mogućnost kolizija ili promenjenih opisa događaja. Sačuvajte sirovo zapažanje čak i kada ne proizvodi novu radnju u OMS-u.

Zaštitite svaki neželjeni efekat zasebno. Na primer, upis statusa u OMS i imejl obaveštenje zahtevaju sopstvene kontrole deduplikacije. Koristite transakcioni outbox ili ekvivalentan trajan zapis rada kako pad procesa ne bi ostavio prihvaćeni događaj bez zakazanog ažuriranja.

2. Čuvajte vreme događaja i vreme prijema odvojeno

Vreme nastanka događaja i vreme kada ga je vaša integracija primila odgovaraju na različita pitanja. Čuvajte oba podatka, zajedno sa originalnim oblikom vremenske oznake i svim dostavljenim pomakom vremenske zone. Nemojte neprimetno dodeljivati vremensku zonu skladišta događaju čija vremenska zona nije poznata.

Zakašnjelo skeniranje pošiljke u tranzitu obično treba da obogati istoriju, a ne da zameni novije stanje „dostavljeno“. Međutim, same vremenske oznake nisu dovoljne: provajder može izdati ispravku, a događaji mogu imati nepotpune vremenske podatke. Kada su dostupna, koristite dokumentovana polja sekvence ili revizije, uz eksplicitnu politiku ispravki.

3. Normalizujte statuse bez brisanja detalja izvora

Kreirajte mali interni rečnik koji OMS razume, kao što su čeka se prihvatanje prevoznika, u tranzitu, kod dostavljača, dostavljeno, izuzetak i vraća se. Mapirajte dokumentovane statuse provajdera u njega. To su predložene interne kategorije, a ne univerzalne definicije prevoznika.

Čuvajte originalni kod statusa, opis, lokaciju događaja, referencu zapisa provajdera i verziju pravila mapiranja. Nemapirana vrednost treba da stvori stanje koje se može pregledati, a ne da podrazumevano postane dostavljeno ili neuspešno. Kreiranje nalepnice ne treba tretirati kao dokaz fizičkog prihvatanja od strane prevoznika, osim ako izvorni događaj izričito podržava takvo tumačenje.

4. Koristite pravila prelaza, a ne jednostavno numeričko rangiranje

Stanja pošiljke ne formiraju uvek pravu liniju. Nakon izuzetka može uslediti normalan tranzit, a pokušaj dostave nije isto što i dostava. Kretanje povrata može početi nakon ranijeg događaja dostave.

  • Dozvolite da se izuzetak ukloni kada naknadni dokazi podrže nastavak kretanja.
  • Sprečite da običan istorijski sken neprimetno zameni stanje „dostavljeno“.
  • Dozvolite dokumentovanu ispravku kroz kontrolisani put revizije.
  • Pratite kretanje povrata odvojeno od završetka odlazne pošiljke kada ga OMS podržava.
  • Nejasne ili protivrečne dokaze usmerite u operativni red čekanja.

Verzija ovih pravila. Kada se mapiranje promeni, odlučite da li se primenjuje samo na nove događaje ili istorijski zapisi zahtevaju kontrolisani ponovni obračun.

Izračunajte status porudžbine na osnovu potrebnih obaveza ispunjenja

Status paketa i status porudžbine treba da budu odvojena polja. Paket označen kao dostavljen pruža dokaz za taj paket; završetak porudžbine zavisi od preostalih potrebnih količina i vaše poslovne politike.

Korisna podrazumevana postavka je da se porudžbina označi kao u potpunosti dostavljena tek kada sve količine za koje je potrebna dostava imaju važeći dokaz o dostavi na nivou paketa i nijedna potrebna raspodela ne ostane nerešena. Otkazane količine izuzmite u skladu sa pravilima otkazivanja OMS-a. Digitalne artikle, porudžbine za preuzimanje i druge obaveze koje ne uključuju isporuku obradite kroz sopstvene uslove završetka.

Zamenske pošiljke zahtevaju eksplicitne veze. Ako se izgubljeni paket zameni, odlučite da li zamena potiskuje prvobitnu obavezu dostave. U suprotnom, prvobitni paket može neograničeno blokirati završetak ili oba paketa mogu biti uračunata u ispunjenje. Zabeležite odluku umesto da je izvedete samo iz statusa praćenja.

Završetak dostave držite odvojenim od finansijskog zatvaranja, podobnosti za refundaciju i rešavanja sporova. Događaj dostave prevoznika ne treba automatski da odobri refundaciju ili reši reklamaciju kupca.

Oporavite se od grešaka bez gubitka revizorskog traga

Ponovite pokušaj kod prolaznih grešaka koristeći ograničeno povećavanje intervala i sva dokumentovana uputstva za ponovne pokušaje. Razdvojite privremene greške povezivanja od nevažećih identifikatora, isteklih akreditiva, grešaka dozvola i nekompatibilnosti šeme. Za poslednje su potrebne korektivne radnje, a ne beskonačni ponovni pokušaji.

Održavajte red čekanja neuspešnog rada koji sadrži pogođenog zakupca, paket, referencu događaja, pokušanu operaciju, klasifikaciju greške i narednu radnju. Zabeležite dovoljno konteksta za istragu, ali bez kopiranja nepotrebnih podataka o kupcima ili akreditiva u dnevnike.

Pokrenite usaglašavanje pored uobičajenog puta ažuriranja. Pregledajte aktivne pošiljke sa zastarelim informacijama o praćenju, prihvaćene događaje čiji upisi u OMS nisu uspeli, neusaglašena zapažanja i razlike između stanja koje je izračunala integracija i OMS-a. Učestalost pregleda odredite na osnovu obaveza dostave, ograničenja API-ja i operativnog rizika, umesto primene proizvoljnog univerzalnog rasporeda.

Dodelite vlasništvo: inženjering rešava unos i greške pri upisu; operacije ispunjenja rešavaju nedostajuće veze paketa; korisnička služba pregleda izuzetke koji zahtevaju komunikaciju sa kupcem. Red čekanja bez odgovornog vlasnika samo je lokacija za skladištenje.

Testirajte mapiranje i poslovna pravila pre pokretanja

Koristite kontrolisane testne podatke i ograničeno pokretanje u produkciji. Testirajte sledeće slučajeve u odnosu na istoriju događaja i rezultujući OMS zapis:

  • Porudžbina sa jednim paketom normalno napreduje do dostave.
  • Podeljena porudžbina ima jedan dostavljeni paket i jedan koji je još u kretanju.
  • Isti događaj se prima više puta bez duplih neželjenih efekata.
  • Stariji sken tranzita stiže nakon dostave.
  • Nepoznati prevoznik ili status ulazi u red za pregled.
  • Nalepnica se zamenjuje bez stvaranja nove obaveze ispunjenja.
  • Zamenska pošiljka potiskuje prvobitni paket prema odobrenom pravilu.
  • OMS nije dostupan nakon prihvatanja događaja.
  • Proces se ponovo pokreće između upisa u OMS i njegove potvrde.
  • Isti prikazani broj porudžbine postoji u dve prodavnice bez uparivanja između zakupaca.

Pokrenite sistem kada svaki prihvaćeni događaj ima sledljiv ishod obrade, kada nejasna podudaranja ne mogu automatski ažurirati porudžbine i kada operateri mogu bezbedno ponovo pokrenuti neuspešan rad. To su korisniji kriterijumi prihvatanja od jednostavnog dokazivanja da API zahtev uspeva.

Česta pitanja

Mogu li direktno povezati brojeve za praćenje sa porudžbinama?

Za strogo radno okruženje sa jednim paketom, direktna veza u početku može biti dovoljna. Ipak, koristite interni identitet pošiljke između porudžbine i dodele praćenja. On obezbeđuje put migracije za podeljene pošiljke, ponovno označavanje i zamene bez promene značenja zapisa porudžbine.

Da li integracija treba da koristi webhook-ove ili periodično preuzimanje?

Koristite mehanizam dostave koji provajder podržava i koji je kompatibilan sa vašom infrastrukturom. Webhook-ovi mogu smanjiti ponovljeno preuzimanje, dok periodično preuzimanje može podržati tokove zasnovane na preuzimanju i usaglašavanje kada je dostupno. Nijedan pristup ne uklanja potrebu za trajnim čuvanjem, rukovanjem duplikatima i oporavkom.

Šta treba da se desi kada događaj praćenja nema odgovarajuću porudžbinu?

Sačuvajte ga u redu čekanja neusaglašenih događaja i istražite zapis registracije, kontekst zakupca, identitet prevoznika i vreme kreiranja pošiljke. Nemojte automatski kreirati porudžbinu ili povezivati događaj sa verovatnim kupcem. Ponovo ga obradite nakon ispravke mapiranja.

Da li obaveštenja o dostavi treba da dolaze iz OMS-a ili sistema za praćenje?

Izaberite jednog vlasnika za svaku vrstu obaveštenja i okidača. Ako dva sistema mogu poslati istu poruku, onemogućite jedan put ili delite trajan dnevnik obaveštenja. Takođe odlučite da li se poruka odnosi na jedan paket ili celu porudžbinu, naročito kod podeljenog ispunjenja.

Da li status izuzetka znači da je porudžbina neuspešna?

Ne. Izuzetak je zapažanje koje zahteva tumačenje, a ne nužno trajan ishod. Sačuvajte razlog, pratite naknadne događaje i koristite svoju politiku eskalacije da odlučite kada operacije treba da intervenišu.

Izvori