Skip to main content
AcasăBlogGhiduriCum să conectați datele de urmărire a expedierilor la un OMS: maparea comenzilor și regulile de sincronizare

Cum să conectați datele de urmărire a expedierilor la un OMS: maparea comenzilor și regulile de sincronizare

17TRACK

Pentru a conecta datele de urmărire a expedierilor la un sistem de gestionare a comenzilor (OMS), asociați fiecare colet urmărit cu o înregistrare internă a expedierii, apoi conectați expedierea la comandă și la liniile de procesare aferente. Primiți actualizările de urmărire prin interfața acceptată de furnizor, păstrați evenimentele originale și aplicați reguli explicite pentru duplicate, actualizări întârziate, starea expedierii și finalizarea comenzii. Nu utilizați doar numărul de urmărire ca identificator al comenzii și nu permiteți ca un singur eveniment de livrare să închidă automat o comandă cu mai multe colete.

Cum să conectați datele de urmărire a expedierilor la o comandă OMS

Acest ghid se adresează inginerilor de integrare și echipelor de operațiuni ecommerce care implementează această conexiune. Designul recomandat separă observațiile transportatorului de deciziile de afaceri: datele de urmărire descriu parcursul unui colet, în timp ce OMS decide ce înseamnă acel parcurs pentru procesarea comenzii, comunicarea cu clientul și închiderea comenzii.

Definiți ce sistem deține fiecare înregistrare

Înainte de a construi o conexiune API, conveniți asupra responsabilității cu administratorul OMS, echipa de procesare a comenzilor și echipa de servicii pentru clienți. În caz contrar, o integrare reușită din punct de vedere tehnic poate suprascrie în continuare date de afaceri valide.

  • OMS: Deține comenzile, liniile de comandă, cantitățile necesare, anulările și regulile pentru finalizarea comenzilor.
  • Sistemul de procesare a comenzilor: Deține înregistrările expedierilor sau coletelor pe care le creează, inclusiv alocările de ambalare și atribuirea etichetelor. Acesta poate fi chiar OMS sau un sistem separat de depozit.
  • Furnizorul de urmărire: Furnizează observații de urmărire și orice clasificări de stare definite de furnizor.
  • Stratul de integrare: Deține referințele încrucișate ale identificatorilor, procesarea evenimentelor, normalizarea, gestionarea reîncercărilor și înregistrările de audit ale sincronizării.

Considerați acestea limite recomandate, nu presupuneri despre software-ul dvs. Documentați excepțiile. De exemplu, dacă depozitul poate înlocui o etichetă de expediere, integrarea are nevoie de o actualizare explicită din partea acelui sistem, în loc să presupună că un număr observat recent îl înlocuiește pe cel vechi.

Construiți asocierea comandă–colet înainte de a sincroniza stările

O relație practică este comandă → procesare → colet → asociere de urmărire. OMS-ul dvs. poate folosi alte denumiri sau poate combina unele dintre aceste înregistrări. Păstrați relațiile chiar dacă structura bazei de date diferă.

O comandă poate avea mai multe procese de onorare, iar un proces poate conține mai multe colete. Un colet poate primi, de asemenea, o asociere de urmărire de înlocuire sau un identificator asociat pentru ultima etapă a livrării. Acești identificatori nu trebuie să creeze cantități comandate suplimentare.

ÎnregistrareCâmpuri recomandateScop
ComandăID-ul comerciantului sau al magazinului, ID OMS imuabil al comenziiSepară comercianții și evită dependența de numerele de comandă afișate.
ProcesareID-ul procesării, ID-ul comenzii, ID-urile și cantitățile liniilor alocateIdentifică articolele achiziționate care sunt procesate.
ColetID intern al coletului, ID-ul procesării, alocările coletului, acolo unde sunt disponibileOferă o identitate stabilă, independentă de etichetele de urmărire.
Asociere de urmărireID-ul asocierii, ID-ul coletului, contul furnizorului, identificatorul transportatorului, numărul de urmărire, perioada activăConectează observațiile de urmărire primite la coletul corect și la ciclul de viață al asocierii.

Potriviți actualizările printr-o referință încrucișată stocată

Când este creată o expediere, salvați ID-urile interne înainte de a o înregistra pentru urmărire. Stocați orice ID al înregistrării de urmărire emis de furnizor și returnat de procesul de înregistrare documentat. Dacă furnizorul acceptă o referință a comerciantului, utilizați o referință internă opacă și păstrați asocierea local.

Pentru actualizările primite, rezolvați mai întâi ID-ul înregistrării furnizorului stocat în contul corect al furnizorului și în cadrul comerciantului corect. Dacă acel identificator nu este disponibil, utilizați combinația documentată dintre numărul de urmărire, identitatea transportatorului, contextul contului și istoricul asocierii. Tratați aceasta ca pe o strategie de căutare, nu ca pe o garanție că acea combinație este unică la nivel global.

Nu potriviți după numele clientului, adresa de e-mail sau un număr de comandă afișat fără domeniu. Păstrați numerele de urmărire ca șiruri de caractere, astfel încât zerourile de la început să fie păstrate. Evitați eliminarea caracterelor sau schimbarea literelor în majuscule ori minuscule, cu excepția cazului în care contractul transportatorului sau al furnizorului permite normalizarea respectivă.

Dacă o căutare nu returnează nicio potrivire sau returnează mai multe potriviri posibile, izolați actualizarea pentru investigare. Un eveniment nerezolvat este mai sigur decât o actualizare sigură, dar greșită, a comenzii altui client.

Gestionați comenzile divizate fără a inventa alocări pentru colete

Luați în considerare o comandă exemplificativă care conține trei unități. Coletul A transportă două unități, iar coletul B una. Livrarea coletului A înseamnă că există dovezi de livrare pentru două unități; nu înseamnă că întreaga comandă a fost livrată.

Dacă sistemul de procesare înregistrează doar faptul că ambele colete aparțin aceleiași procesări, nu inventați alocări la nivel de unitate. Puteți calcula în continuare dacă toate coletele necesare au fost livrate, însă raportarea livrării la nivel de articol trebuie să rămână indisponibilă sau explicit incertă până când există date despre alocare.

Conectați API-ul de urmărire printr-un strat durabil de preluare

Utilizați un flux care menține comunicarea cu furnizorul separată de scrierile în OMS:

Crearea expedierii → înregistrarea urmăririi → actualizare primită sau preluare programată → stocarea durabilă a evenimentului → asocierea și normalizarea → actualizarea OMS → reconcilierea

Pentru o implementare 17TRACK, pagina produsului Tracking API și documentația oficială API sunt punctele de pornire relevante. Confirmați interfața de înregistrare aplicabilă, identificatorii transportatorilor, opțiunile de livrare a actualizărilor, cerințele de autentificare, definițiile stărilor și limitele contului înainte de a implementa adaptorul. Modelul de date din acest ghid este o recomandare de integrare, nu o afirmație că 17TRACK utilizează aceste denumiri de câmpuri sau oferă un conector nativ pentru OMS-ul dvs.

Dacă furnizorul selectat acceptă webhooks, autentificați cererile primite folosind mecanismul documentat de acesta și stocați durabil mesajele acceptate înainte de a le confirma. Păstrați operațiunile lente ale OMS în afara traseului cererii. Respectați contractul real al furnizorului privind confirmările și reîncercările, în loc să presupuneți un anumit corp de răspuns sau un anumit timeout.

Dacă este necesară interogarea periodică, stocați progresul preluării acolo unde API-ul permite, controlați concurența și respectați limitele de rată documentate. Nici primirea unui webhook, nici o cerere de interogare reușită nu dovedesc faptul că OMS a fost actualizat; înregistrați separat aceste rezultate.

Definiți reguli de sincronizare care rezistă la reîncercări și evenimente întârziate

1. Faceți procesarea idempotentă

Procesarea de două ori a aceleiași observații nu trebuie să duplice o expediere, să avanseze cantitățile de două ori sau să trimită din nou aceeași notificare clientului. HTTP nu face idempotentă o operațiune POST arbitrară; integrarea trebuie să implementeze protecția împotriva duplicatelor. RFC 9110 explică idempotența metodelor HTTP.

Utilizați un ID stabil al evenimentului furnizorului atunci când acesta este documentat și disponibil. În caz contrar, definiți o amprentă pe baza ID-ului asocierii și a câmpurilor relevante ale evenimentului, precum marca temporală a evenimentului, starea sursă și locația. Documentați posibilitatea coliziunilor sau a modificării descrierilor evenimentelor. Păstrați observația brută chiar și atunci când aceasta nu produce o altă acțiune în OMS.

Protejați separat fiecare efect secundar. De exemplu, o scriere a stării în OMS și o notificare prin e-mail au nevoie de propriile controale de deduplicare. Utilizați un outbox tranzacțional sau o înregistrare echivalentă de lucru durabilă, astfel încât o cădere a procesului să nu lase un eveniment acceptat fără o actualizare programată.

2. Stocați separat ora evenimentului și ora primirii

Momentul producerii unui eveniment și momentul la care integrarea dvs. l-a primit răspund la întrebări diferite. Stocați-le pe ambele, împreună cu reprezentarea originală a marcajului temporal și cu orice diferență de fus orar furnizată. Nu atribuiți în mod silențios fusul orar al depozitului unui eveniment al cărui fus orar este necunoscut.

O scanare întârziată în tranzit ar trebui, în mod normal, să îmbogățească istoricul fără să înlocuiască o stare mai nouă de livrare. Totuși, marcajele temporale nu sunt suficiente: un furnizor poate emite o corecție, iar evenimentele pot avea informații temporale incomplete. Utilizați câmpurile documentate de secvență sau revizie atunci când sunt disponibile, împreună cu o politică explicită de corectare.

3. Normalizați stările fără a șterge detaliile sursei

Creați un vocabular intern restrâns pe care OMS îl înțelege, precum în așteptarea acceptării de către transportator, în tranzit, în curs de livrare, livrat, excepție și în retur. Asociați stările documentate ale furnizorului cu acesta. Acestea sunt categorii interne sugerate, nu definiții universale ale transportatorilor.

Stocați codul original al stării, descrierea, locația evenimentului, referința înregistrării furnizorului și versiunea regulii de asociere. O valoare neasociată trebuie să creeze o situație care poate fi revizuită, nu să fie setată implicit ca livrată sau eșuată. Crearea etichetei nu trebuie tratată drept dovadă a acceptării fizice de către transportator, cu excepția cazului în care evenimentul sursă susține explicit această interpretare.

4. Utilizați reguli de tranziție, nu o ierarhie numerică simplă

Stările expedierii nu formează întotdeauna o linie dreaptă. O excepție poate fi urmată de tranzit normal, iar o încercare de livrare nu este o livrare. Mișcarea de retur poate începe după un eveniment anterior de livrare.

  • Permiteți eliminarea unei excepții atunci când dovezile ulterioare susțin reluarea mișcării.
  • Împiedicați înlocuirea silențioasă a unei stări livrate de către o scanare istorică obișnuită.
  • Permiteți o corecție documentată printr-un flux controlat de revizie.
  • Urmăriți separat mișcarea de retur față de finalizarea livrării outbound, acolo unde OMS permite acest lucru.
  • Direcționați dovezile ambigue sau contradictorii către o coadă operațională.

Versionați aceste reguli. Atunci când o asociere se modifică, decideți dacă aceasta se aplică doar evenimentelor noi sau dacă înregistrările istorice necesită o recalculare controlată.

Calculați starea comenzii pe baza obligațiilor de procesare necesare

Starea coletului și starea comenzii trebuie să fie câmpuri separate. Un colet marcat ca livrat furnizează dovezi pentru acel colet; finalizarea comenzii depinde de cantitățile necesare rămase și de politica dvs. de afaceri.

O valoare implicită utilă este să marcați o comandă ca livrată integral numai atunci când toate cantitățile care necesită livrare au dovezi valide de livrare la nivel de colet și nu mai există alocări necesare nerezolvate. Excludeți cantitățile anulate conform regulilor de anulare ale OMS. Gestionați articolele digitale, comenzile cu ridicare și alte obligații care nu implică expediere prin propriile condiții de finalizare.

Expedierile de înlocuire necesită relații explicite. Dacă un colet pierdut este înlocuit, decideți dacă înlocuitorul înlocuiește obligația inițială de livrare. În caz contrar, coletul inițial poate bloca finalizarea pe termen nelimitat sau ambele colete pot fi luate în calcul pentru procesare. Înregistrați decizia, în loc să o deduceți doar din starea urmăririi.

Păstrați finalizarea livrării separată de închiderea financiară, eligibilitatea pentru rambursare și soluționarea disputelor. Un eveniment de livrare al transportatorului nu trebuie să autorizeze automat o rambursare sau să soluționeze o reclamație a clientului.

Recuperați-vă după erori fără a pierde pista de audit

Reîncercați erorile tranzitorii folosind un backoff limitat și orice recomandări documentate privind reîncercarea. Separați erorile temporare de conexiune de identificatorii invalizi, acreditările expirate, erorile de permisiuni și incompatibilitățile de schemă. Acestea din urmă necesită acțiuni corective, nu reîncercări nesfârșite.

Mențineți o coadă de activități eșuate care să conțină comerciantul afectat, coletul, referința evenimentului, operațiunea încercată, clasificarea erorii și următoarea acțiune. Înregistrați suficient context pentru investigare fără a copia în jurnale date inutile despre clienți sau acreditări.

Rulați reconcilierea în plus față de fluxul normal de actualizare. Verificați expedierile active cu informații de urmărire învechite, evenimentele acceptate ale căror scrieri în OMS au eșuat, observațiile fără potrivire și diferențele dintre starea calculată de integrare și OMS. Alegeți frecvența verificărilor în funcție de angajamentele de livrare, limitele API și riscul operațional, nu prin aplicarea unui program universal arbitrar.

Stabiliți responsabilități: echipa de inginerie gestionează preluarea și erorile de scriere; operațiunile de procesare rezolvă relațiile lipsă dintre colete; serviciul pentru clienți verifică excepțiile care necesită comunicare cu clientul. O coadă fără un responsabil desemnat este doar o locație de stocare.

Testați asocierea și regulile de afaceri înainte de lansare

Utilizați date de test controlate și o lansare limitată în producție. Testați următoarele cazuri atât în raport cu istoricul evenimentelor, cât și cu înregistrarea OMS rezultată:

  • O comandă cu un singur colet evoluează normal până la livrare.
  • O comandă divizată are un colet livrat și unul încă în mișcare.
  • Același eveniment este primit repetat fără efecte secundare duplicate.
  • O scanare mai veche în tranzit sosește după livrare.
  • Un transportator sau o stare necunoscută intră în coada de verificare.
  • O etichetă este înlocuită fără a crea o altă obligație de procesare.
  • O expediere de înlocuire înlocuiește coletul inițial conform unei reguli aprobate.
  • OMS nu este disponibil după acceptarea unui eveniment.
  • Un proces repornește între scrierea în OMS și confirmarea acesteia.
  • Același număr de comandă afișat există în două magazine fără asociere între comercianți.

Lansați atunci când fiecare eveniment acceptat are un rezultat de procesare trasabil, potrivirile ambigue nu pot actualiza automat comenzile, iar operatorii pot relua în siguranță activitățile eșuate. Acestea sunt criterii de acceptare mai utile decât simpla demonstrare a faptului că o cerere API reușește.

Întrebări frecvente

Pot conecta direct numerele de urmărire la comenzi?

Pentru un flux strict cu un singur colet, o relație directă poate fi suficientă inițial. Totuși, utilizați o identitate internă a expedierii între comandă și asocierea de urmărire. Aceasta oferă o cale de migrare pentru expedieri divizate, reetichetare și înlocuiri, fără a schimba semnificația înregistrării comenzii.

Ar trebui ca integrarea să utilizeze webhooks sau interogarea periodică?

Utilizați mecanismul de livrare acceptat de furnizor și compatibil cu infrastructura dvs. Webhooks pot reduce preluarea repetată, în timp ce interogarea periodică poate susține fluxurile bazate pe preluare și reconcilierea, acolo unde este disponibilă. Niciuna dintre abordări nu elimină necesitatea stocării durabile, a gestionării duplicatelor și a recuperării.

Ce ar trebui să se întâmple atunci când un eveniment de urmărire nu are nicio comandă asociată?

Stocați-l într-o coadă de evenimente fără potrivire și investigați înregistrarea de înregistrare, contextul comerciantului, identitatea transportatorului și momentul creării expedierii. Nu creați automat o comandă și nu atașați evenimentul unui client plauzibil. Reluați procesarea după corectarea asocierii.

Notificările de livrare ar trebui să provină din OMS sau din sistemul de urmărire?

Alegeți un singur responsabil pentru fiecare tip și declanșator de notificare. Dacă două sisteme pot trimite același mesaj, dezactivați una dintre căi sau utilizați împreună un registru durabil al notificărilor. Decideți, de asemenea, dacă un mesaj se referă la un singur colet sau la întreaga comandă, în special în cazul procesării divizate.

Înseamnă o stare de excepție că această comandă a eșuat?

Nu. O excepție este o observație care necesită interpretare, nu neapărat un rezultat permanent. Păstrați motivul, monitorizați evenimentele ulterioare și utilizați politica de escaladare pentru a decide când trebuie să intervină operațiunile.

Surse