Fluxul de lucru al API-ului de urmărire a expedierilor: de la înregistrarea unei expedieri la obținerea detaliilor de urmărire
Un flux de lucru API pentru urmărirea unei expedieri începe prin trimiterea unui număr de urmărire și a oricăror informații necesare despre transportator, verificarea reușitei înregistrării, permiterea ca datele de urmărire să devină disponibile și obținerea stării expedierii și a istoricului evenimentelor. Pentru o integrare în producție, dezvoltatorii trebuie, de asemenea, să conecteze fiecare înregistrare de urmărire la o comandă, să gestioneze eșecurile parțiale, să proceseze actualizările în siguranță și să distingă între o înregistrare acceptată și o scanare efectivă realizată de transportator.
Acest ghid explică fluxul de lucru pentru dezvoltatorii care conectează o platformă de comerț electronic, un sistem de gestionare a comenzilor, o aplicație pentru depozit sau un instrument de servicii pentru clienți. Acesta separă recomandările privind proiectarea aplicației de cerințele API specifice furnizorului. Pentru o integrare 17TRACK, utilizați documentația oficială API pentru a confirma schema solicitării, autentificarea, operațiunile acceptate și câmpurile răspunsului înainte de a implementa exemplele de mai jos.
Înțelegeți ce face și ce nu face înregistrarea
Înregistrarea unei expedieri la un serviciu de urmărire înseamnă trimiterea unui identificator, astfel încât serviciul să poată urmări sau gestiona expedierea în conformitate cu contractul său API. Aceasta nu este aceeași operațiune cu achiziționarea taxelor poștale, generarea unei etichete de expediere, programarea unei ridicări sau predarea unui colet către un transportator.
Mențineți separate în aplicație trei rezultate:
- Solicitare primită: API-ul a returnat un răspuns la solicitarea HTTP.
- Înregistrare acceptată: Serviciul a acceptat înregistrarea individuală de urmărire pentru procesare.
- Informații de urmărire disponibile: Serviciul deține informații despre expediere pe care aplicația le poate obține sau primi.
Aceste rezultate nu ar trebui combinate într-un singur indicator de „succes”. Un număr de urmărire acceptat poate să nu aibă încă evenimente de la transportator. În mod similar, un răspuns HTTP reușit pentru o solicitare în lot nu demonstrează că fiecare element din lot a fost acceptat; inspectați structura rezultatului la nivel de aplicație definită de furnizor.
1. Pregătiți identitatea expedierii și configurația API
Înainte de a face o solicitare de înregistrare, decideți cum va fi identificată o expediere în propriul sistem. De obicei, un identificator de comandă nu este suficient, deoarece o comandă poate fi împărțită în mai multe colete. Atribuiți fiecărei expedieri sau fiecărui colet propria înregistrare internă și asociați înregistrarea cu comanda relevantă.
O înregistrare internă utilă include următoarele informații. Acestea sunt câmpuri de aplicație sugerate, nu o schemă de solicitare 17TRACK.
- ID intern al expedierii: Identificatorul stabil al coletului în sistemul dumneavoastră.
- Referință comandă: Comanda sau înregistrarea de onorare căreia îi aparține.
- Număr de urmărire: Identificatorul atribuit de transportator, stocat ca text pentru păstrarea zerourilor de la început.
- Informații despre transportator: Identitatea transportatorului furnizată de sistemul dumneavoastră de onorare, dacă este cunoscută.
- Referință furnizor: Orice identificator returnat de serviciul de urmărire care este necesar pentru operațiuni ulterioare.
- Starea înregistrării: Evidența dumneavoastră privind faptul că trimiterea este în așteptare, acceptată, respinsă sau în așteptarea reconcilierii.
- Starea urmăririi: Cea mai recentă stare a expedierii, menținută separat de starea înregistrării.
Validați datele de intrare înainte de trimitere. Eliminați spațiile albe accidentale de la început și de la sfârșit, dar nu rescrieți numărul de urmărire pe baza unor presupuneri despre formatul transportatorului. Păstrați valoarea originală pentru depanare. Dacă transportatorul este cunoscut, asociați-l cu identificatorul documentat al transportatorului din furnizor, în loc să trimiteți o denumire informală afișată.
Configurați autentificarea pe partea de server. Păstrați acreditările în afara sistemului de control al versiunilor, separați configurațiile de dezvoltare și producție și eliminați datele secrete din jurnale. Confirmați versiunea API documentată, limitele solicitărilor, limitele loturilor și cerințele contului, în loc să preluați valori dintr-o integrare fără legătură.
2. Înregistrați expedierea și salvați rezultatul la nivel de element
Trimiteți înregistrarea de urmărire folosind operațiunea de înregistrare descrisă în documentația furnizorului. Includeți doar câmpurile obligatorii și informațiile opționale care au un scop clar. Evitați să trimiteți numele clienților, adresele sau alte date cu caracter personal doar pentru că sunt disponibile în baza de date a comenzilor.
Următorul pseudocod ilustrează secvența aplicației. Numele funcțiilor sunt orientative; nu reprezintă endpoint-uri API sau metode SDK.
shipment = load_internal_shipment(shipment_id)
validate_tracking_input(shipment)
result = tracking_adapter.register(shipment)
if result.item_accepted:
save_registration_result(shipment_id, result)
elif result.outcome_unknown:
schedule_registration_reconciliation(shipment_id)
else:
save_registration_error(shipment_id, result)
route_for_retry_or_correction(result)
Păstrați suficiente informații pentru a explica ce s-a întâmplat: ID-ul intern al expedierii, momentul trimiterii, numărul încercării, rezultatul la nivel de element și orice referință a solicitării furnizorului. Nu vă bazați exclusiv pe un jurnal temporar al procesului. Echipele de servicii pentru clienți și operațiuni au nevoie de un răspuns durabil privind înrolarea cu succes a unei expedieri.
Gestionați individual trimiterile în lot
Dacă API-ul acceptă înregistrarea în lot, corelați fiecare element returnat cu expedierea sa originală. Nu marcați întregul lot ca acceptat doar pentru că solicitarea HTTP s-a finalizat cu succes. Salvați elementele acceptate, izolați elementele respinse și investigați separat rezultatele ambigue.
Astfel evitați ca un număr de urmărire incorect să forțeze reîncercări inutile pentru înregistrări care au fost deja procesate cu succes. De asemenea, oferiți personalului operațional o listă clară de înregistrări care necesită corectare.
Tratați expirarea conexiunii ca pe un rezultat necunoscut
O expirare a conexiunii nu dovedește că înregistrarea a eșuat. Este posibil ca furnizorul să fi acceptat solicitarea înainte ca legătura dumneavoastră să fie întreruptă. Utilizați comportamentul de idempotență documentat, gestionarea duplicatelor sau operațiunile de căutare pentru a reconcilia rezultatul înainte de a retrimite orbește.
Atunci când comportamentul furnizorului pentru duplicate nu este clar, testați-l cu înregistrări controlate și confirmați contractul înainte de a activa reîncercările automate. Deduplicarea internă a lucrărilor de înregistrare este în continuare utilă, dar nu înlocuiește înțelegerea modului în care serviciul la distanță gestionează solicitările repetate.
3. Așteptați apariția primelor informații de urmărire
După acceptarea înregistrării, detaliile de urmărire este posibil să nu fie disponibile imediat. O etichetă poate exista înainte ca transportatorul să fi înregistrat un eveniment fizic de manipulare. Lipsa informațiilor poate necesita, de asemenea, verificarea numărului de urmărire, a selecției transportatorului sau a cerințelor de căutare specifice expedierii.
Reprezentați explicit această stare. „Înregistrată; se așteaptă informațiile de urmărire” este mai precis decât „În tranzit” sau „Înregistrarea a eșuat”. Nu inventați o estimare a livrării sau un eveniment de mișcare pentru a umple o interfață goală.
Când o înregistrare rămâne goală, investigați în următoarea ordine practică:
- Confirmați că înregistrarea individuală a fost acceptată.
- Comparați numărul de urmărire trimis cu înregistrarea de onorare.
- Verificați asocierea transportatorului și orice cerințe suplimentare documentate pentru căutare.
- Verificați pagina proprie de urmărire a transportatorului pentru aceeași expediere.
- Dacă transportatorul are evenimente, dar integrarea dumneavoastră nu le afișează, inspectați răspunsurile de obținere și contactați furnizorul API cu informații de diagnostic anonimizate.
Evitați adoptarea unei perioade universale de așteptare fără dovezi. Regulile de escaladare ar trebui să reflecte serviciul de expediere, procesul așteptat de predare și angajamentele operaționale proprii.
4. Obțineți detaliile de urmărire și interpretați-le corect
Odată ce înregistrarea este disponibilă, apelați operațiunea documentată pentru detaliile de urmărire folosind identificatorii solicitați. Nu presupuneți că înregistrarea și obținerea acceptă câmpuri identice. Unele contracte API fac distincție între numerele de urmărire, identificatorii transportatorilor și referințele înregistrărilor generate de furnizor.
Aplicația dumneavoastră ar trebui să distingă trei niveluri de informații:
- Rezumatul expedierii: Starea generală utilizată în tablouri de bord, pagini de comenzi și filtre operaționale.
- Istoricul evenimentelor: Observațiile individuale, inclusiv descrierile evenimentelor, marcajele temporale și locațiile, atunci când sunt furnizate.
- Metadatele obținerii: Momentul în care aplicația a primit sau a preluat informațiile și dacă solicitarea s-a finalizat cu succes.
O căutare reușită înseamnă că operațiunea de obținere s-a finalizat cu succes. Nu înseamnă că coletul s-a deplasat de la ultima căutare. Comparați informațiile de urmărire returnate cu înregistrarea stocată înainte de a genera o notificare sau un flux de lucru ulterior.
Păstrați separat momentul evenimentului și momentul obținerii
Stocați separat momentul asociat unui eveniment al transportatorului de momentul la care sistemul dumneavoastră l-a primit. Un eveniment obținut în această după-amiază poate descrie o scanare anterioară. Înlocuirea momentului evenimentului cu momentul obținerii ar face ca o actualizare veche să pară o mișcare fizică nouă.
Păstrați marcajul temporal original și orice decalaj furnizat. Normalizați marcajele temporale pentru comparație numai atunci când fusul orar este cunoscut. Dacă un eveniment nu conține informații despre fusul orar, păstrați această incertitudine în loc să atribuiți în tăcere fusul orar al serverului.
Păstrați semnificația brută alături de starea normalizată
O stare normalizată este utilă pentru gruparea expedierilor între transportatori, dar descrierea originală a evenimentului poate explica mai precis o problemă operațională. Păstrați-le pe ambele atunci când sunt disponibile. Doar o categorie generală de excepție este posibil să nu îi spună unui agent de asistență dacă următoarea acțiune este verificarea unei adrese, contactarea destinatarului sau așteptarea unei alte actualizări.
Nu deduceți o garanție de livrare, o pierdere confirmată sau un anumit rezultat vamal dintr-o stare vagă. Escaladați conform informațiilor de bază și politicii operaționale.
5. Mențineți înregistrările actualizate prin interogare periodică sau webhook-uri
Obținerea detaliilor o singură dată este suficientă pentru testarea conectivității, dar nu pentru menținerea vizibilității asupra expedierii. Proiectarea pentru producție are nevoie de un mecanism de actualizare. Confirmați mecanismele acceptate de furnizorul ales și condițiile asociate acestora.
În cazul interogării periodice, aplicația solicită detaliile de urmărire conform unui program. Programați solicitările în limitele documentate, evitați interogarea repetată a înregistrărilor neschimbate fără un motiv și utilizați o perioadă de așteptare progresivă pentru eșecurile care pot fi reîncercate. Deschiderea unei pagini de comandă de către un client nu ar trebui să declanșeze automat o solicitare nelimitată către serviciul extern; o vizualizare stocată a urmăririi poate servi pagina, în timp ce un proces controlat în fundal o actualizează.
Dacă utilizați webhook-uri, validați solicitările primite folosind mecanismul de verificare documentat al furnizorului. Păstrați sau puneți în coadă în mod durabil mesajele acceptate înainte de a le confirma primirea, conform contractului webhook-ului, apoi procesați evenimentele asincron.
Construiți receptorul astfel încât să accepte duplicatele și ordinea neașteptată de sosire, cu excepția cazului în care contractul de livrare documentat garantează contrariul. Utilizați un identificator de eveniment al furnizorului pentru deduplicare, atunci când este disponibil. În caz contrar, definiți și testați o amprentă bazată pe câmpuri de eveniment potrivite, ținând cont că această amprentă poate necesita ajustări pentru datele dumneavoastră.
O integrare bazată pe webhook-uri poate utiliza și obținerea controlată pentru reconciliere. De exemplu, o lucrare de recuperare poate verifica înregistrările afectate de o întrerupere a receptorului. Acesta este un model de reziliență, nu o permisiune de a ignora limitele de frecvență sau recomandările specifice furnizorului.
6. Transformați informațiile de urmărire în acțiuni comerciale sigure
Actualizați înregistrarea internă a expedierii înainte de a declanșa acțiuni adresate clienților. Păstrați o evidență durabilă a notificărilor și tranzițiilor fluxului de lucru, astfel încât un eveniment repetat să nu genereze mesaje repetate.
Asociați acțiunile comerciale cu modificări semnificative, nu cu fiecare răspuns API. Un eveniment de livrare observat recent poate justifica o notificare de livrare. Un răspuns repetat care conține același eveniment nu ar trebui să o facă. O excepție poate justifica o verificare internă, dar mesajul către client ar trebui să reflecte ceea ce spune efectiv evenimentul.
Definiți modul în care gestionați evenimentele primite după ce o expediere a fost considerată finalizată. Nu ștergeți istoricul evenimentelor și nu blocați permanent toate actualizările ulterioare doar pentru că un rezumat a ajuns într-o stare finală. Regulile de păstrare, reconciliere și notificare ar trebui să țină cont de corecțiile legitime fără a redeschide repetat fluxurile de lucru finalizate.
Aplicarea fluxului de lucru unei integrări 17TRACK
Pentru o integrare personalizată de urmărire, punctele de pornire relevante sunt pagina API-ului de urmărire 17TRACK și documentația pentru dezvoltatori. Utilizați pagina produsului pentru a evalua oferta și documentația pentru a stabili contractul real de integrare. Paginile de urmărire pentru consumatori nu înlocuiesc specificațiile API.
Înainte de a scrie adaptorul, confirmați formatul autentificării, operațiunile de înregistrare și obținere, regulile de identificare a transportatorului, gestionarea răspunsurilor la nivel de element și limitele aplicabile solicitărilor. Pentru procesarea bazată pe webhook-uri, confirmați și schema sarcinii utile, procesul de verificare, cerințele de confirmare a primirii și comportamentul la reîncercare.
Păstrați aceste detalii specifice furnizorului în interiorul unui adaptor, în loc să răspândiți presupunerile despre câmpurile răspunsului în întregul sistem de comenzi. Astfel, restul aplicației poate lucra cu concepte interne precum rezultatul înregistrării, starea expedierii, istoricul evenimentelor și ultima sincronizare reușită.
Verificări înainte de lansare care previn greșelile costisitoare
- Înregistrare acceptată, dar goală: Interfața arată că informațiile de urmărire sunt în așteptare, nu că coletul se deplasează.
- Rezultat mixt al lotului: Fiecare expediere primește propriul rezultat stocat.
- Expirarea conexiunii după trimitere: Procesul reconciliază rezultatul incert în loc să presupună eșecul.
- Eveniment repetat: Cronologia expedierii și notificarea clientului rămân deduplicate.
- Eveniment mai vechi primit ulterior: Evenimentul este păstrat fără înlocuirea orbească a unui rezumat mai nou.
- Serviciu extern indisponibil: Pagina clientului poate afișa ultimul rezultat stocat, cu o indicație adecvată a actualității.
- Asociere incorectă a transportatorului: Înregistrarea poate fi corectată printr-o cale de recuperare documentată.
- Comandă împărțită: Fiecare colet își păstrează propria stare și propriul istoric de urmărire.
- Expunerea acreditărilor sau a sarcinii utile: Jurnalele conțin referințe de diagnostic fără divulgarea secretelor sau a informațiilor personale inutile.
Criteriul practic de finalizare nu este doar primirea unui răspuns de înregistrare reușit. Este capacitatea de a urmări un colet de la trimitere până la actualizări, de a explica un rezultat gol sau eșuat și de a recupera procesarea întreruptă fără pierderea evenimentelor sau duplicarea acțiunilor adresate clienților.
Întrebări frecvente
Înregistrarea unui număr de urmărire creează o expediere?
Nu în fluxul de lucru descris aici. Înregistrarea urmăririi trimite un identificator existent către un serviciu de urmărire. Crearea etichetei, achiziționarea taxelor poștale și programarea transportatorului sunt operațiuni separate, cu excepția cazului în care un anumit API le combină în mod explicit.
De ce sunt goale detaliile de urmărire după ce înregistrarea a fost acceptată?
Acceptarea înregistrării și disponibilitatea datelor de urmărire sunt condiții diferite. Este posibil ca transportatorul să nu fi înregistrat încă un eveniment sau să fie necesară verificarea numărului de urmărire, a asocierii transportatorului ori a informațiilor suplimentare pentru căutare. Inspectați rezultatul la nivel de element înainte de a considera înregistrarea ca fiind reușită.
Ar trebui să înregistrez expedierea de fiecare dată când îi obțin starea?
Nu utilizați înregistrarea repetată ca mecanism implicit de actualizare. Stocați starea înregistrării acceptate și utilizați mecanismul documentat de obținere sau actualizare. Respectați regulile explicite ale furnizorului pentru corecții, reactivare sau trimiteri duplicate.
Ar trebui să folosesc interogarea periodică sau webhook-urile?
Utilizați mecanismul care se potrivește contractului API documentat și cerințelor operaționale. Interogarea periodică necesită un program controlat de solicitări. Webhook-urile necesită un receptor sigur și durabil, precum și procesare sigură în cazul duplicatelor. Atunci când sunt acceptate, actualizările prin webhook împreună cu reconcilierea direcționată pot oferi o cale practică de recuperare.
Pot folosi un număr de urmărire drept singurul identificator al expedierii în baza mea de date?
Utilizați în schimb un identificator intern al expedierii. Stocați numărul de urmărire și contextul relevant al transportatorului ca atribute ale înregistrării respective. Astfel, comenzile împărțite, numerele de urmărire corectate și referințele specifice furnizorului sunt mai ușor de gestionat fără modificarea identității expedierii interne.
Surse
- API-ul de urmărire 17TRACK — punctul oficial de pornire al produsului pentru evaluarea unei integrări API 17TRACK.
- Documentația API 17TRACK — referința oficială pentru formatele solicitărilor specifice implementării, operațiuni, răspunsuri și cerințe de integrare. Pseudocodul și sugestiile privind câmpurile interne din acest ghid sunt exemple de proiectare a aplicației, nu citate din acest contract API.


