Skip to main content
AcasăBlogGhiduriCum se înregistrează un număr de urmărire prin API: câmpurile cererii, codurile transportatorilor și răspunsurile

Cum se înregistrează un număr de urmărire prin API: câmpurile cererii, codurile transportatorilor și răspunsurile

17TRACK

Pentru a înregistra un număr de urmărire prin API, trimiteți o solicitare de înregistrare autentificată care să conțină numărul de urmărire al expediției și, atunci când este necesar, un identificator al transportatorului. Apoi analizați răspunsul pentru fiecare expediție trimisă — nu doar codul de stare HTTP — și salvați dacă înregistrarea a reușit, a eșuat sau rămâne incertă. Înregistrarea inițiază fluxul de urmărire; aceasta nu dovedește că transportatorul a scanat coletul sau că evenimentele de urmărire sunt deja disponibile.

Cum se înregistrează un număr de urmărire prin câmpurile unei solicitări API

Acest ghid este destinat dezvoltatorilor care conectează un sistem de gestionare a comenzilor, o aplicație de depozit sau o platformă de comerț electronic la un API de urmărire. Utilizează 17TRACK ca exemplu concret de integrare și explică ce detalii trebuie verificate în documentația pentru versiunea API selectată.

Ce face înregistrarea — și ce nu face

O solicitare de înregistrare îi indică unui serviciu de urmărire ce expediție doriți să urmăriți. Aceasta este diferită de achiziționarea unei etichete de expediere, programarea unei ridicări sau solicitarea ca un transportator să creeze o expediție. Într-o integrare obișnuită, fluxul de expediere generează mai întâi un număr de urmărire, iar aplicația dumneavoastră înregistrează ulterior acel număr.

Păstrați aceste trei evenimente separate în aplicația dumneavoastră:

  • Expediere creată: sistemul dumneavoastră de expediere a atribuit un număr de urmărire.
  • Înregistrare acceptată: serviciul de urmărire a acceptat expedierea pentru urmărire.
  • Informații de urmărire primite: evenimentele transportatorului au devenit disponibile prin serviciul de urmărire.

Nu actualizați o comandă la starea „în tranzit” doar pentru că înregistrarea a reușit. Este posibil ca o etichetă nou creată să nu aibă încă o scanare fizică de acceptare. Starea expediției afișată clientului trebuie să provină din evenimentele de urmărire interpretate prin regulile dumneavoastră de mapare a stărilor, nu din răspunsul de înregistrare.

Pentru integrările 17TRACK, începeți cu prezentarea generală a Tracking API și utilizați documentația oficială a API-ului ca sursă de referință pentru endpoint-uri, definițiile câmpurilor, autentificare și codurile de răspuns. Exemplele de mai jos se concentrează pe înregistrare, nu pe activitățile separate de obținere a rezultatelor sau primire a actualizărilor.

Pregătiți câmpurile solicitării înainte de a scrie apelul API

Cea mai utilă pregătire este un mic contract de câmpuri între sistemul dumneavoastră de expediere și integrarea de urmărire. Decideți de unde provine fiecare valoare, dacă poate lipsi și cum va fi validată.

Câmp sau valoareScopRegulă de implementare
Număr de urmărireIdentifică expedierea care trebuie urmărită.Stocați-l și transmiteți-l ca șir de caractere; păstrați zerourile de la început.
Identificatorul transportatoruluiIdentifică transportatorul în sistemul furnizorului de urmărire.Utilizați identificatorul documentat de furnizor, nu un cod intern al depozitului.
Referință internăConectează înregistrarea la evidența expediției dumneavoastră.Utilizați un câmp de referință acceptat, dacă este disponibil; păstrați oricum propria mapare în baza de date.
Date suplimentare de identificarePot ajuta la identificarea unei expediții atunci când transportatorul solicită mai mult decât numărul de urmărire.Trimiteți numai câmpurile documentate pentru integrarea și transportatorul respectiv.
Credențial APIAutentifică contul apelant.Păstrați-o pe server și excludeți-o din jurnalele aplicației.

Tratați numărul de urmărire ca pe un identificator

Nu convertiți niciodată un număr de urmărire într-un număr întreg. Conversia numerică poate elimina zerourile de la început, iar valorile mari își pot pierde precizia în anumite medii de programare. Eliminați spațiile albe accidentale de la început și de la sfârșit, dar nu eliminați punctuația și nu modificați literele mari sau mici decât dacă documentația relevantă sau formatul transportatorului permite această normalizare.

Validați erorile evidente de introducere înainte de a apela API-ul: șiruri goale, întreruperi de linie neașteptate și un număr de comandă copiat în câmpul numărului de urmărire. Evitați impunerea unei singure reguli universale privind lungimea sau caracterele pentru toți transportatorii. O regulă de validare potrivită pentru un transportator poate respinge numere legitime ale altuia.

Păstrați separat referințele comenzilor și identitățile expedierilor

O comandă poate avea mai multe colete, iar o expediere de înlocuire poate introduce un alt număr de urmărire. Modelați înregistrarea la nivel de expediere sau colet, în loc să presupuneți că există un singur număr de urmărire pentru fiecare comandă.

Dacă utilizați o etichetă sau un câmp de referință acceptat de furnizor, preferați o referință opacă a expediției în locul adresei de e-mail sau al adresei poștale a clientului. Propria bază de date trebuie să rămână legătura de referință între comenzi, expedieri, numere de urmărire și mapările transportatorilor.

Alegeți codul corect al transportatorului

Un cod de transportator nu este neapărat un identificator universal al industriei. Valoarea recunoscută de o platformă de urmărire poate diferi de numele transportatorului stocat în software-ul dumneavoastră de expediere. Chiar și două sisteme care utilizează coduri numerice pot atribui numere diferite aceluiași transportator.

Mențineți o mapare explicită de la serviciul dumneavoastră de expediere la identificatorul transportatorului utilizat de furnizorul de urmărire. Când este necesar, diferențiați operațiunea regională sau serviciul unui transportator de marca sa generală. O mapare bazată doar pe un nume afișat poate deveni ambiguă atunci când sistemele de expediere folosesc aliasuri.

  • Când transportatorul este cunoscut: utilizați identificatorul documentat al transportatorului atunci când este acceptat, în special atunci când formatele numerelor de urmărire se suprapun.
  • Când transportatorul este necunoscut: utilizați detectarea automată numai prin mecanismul documentat. Nu presupuneți că omiterea, un șir gol, zero și null înseamnă același lucru.
  • Când rezultatul pare incorect: verificați eticheta originală, serviciul de expediere și maparea înainte de a înregistra în mod repetat același număr.

Detectarea automată este utilă, dar nu reprezintă o dovadă că un anumit transportator deține fizic expedierea. În mod similar, un cod valid de transportator nu garantează că numărul de urmărire furnizat aparține acelui transportator.

Păstrați mapările transportatorilor configurabile în loc să le distribuiți în codul aplicației. Înregistrați când a fost verificată ultima dată o mapare și includeți o expediere cunoscută în testele de regresie ori de câte ori o modificați.

Exemplu: trimiteți o solicitare de înregistrare 17TRACK

Exemplul următor ilustrează endpoint-ul de înregistrare 17TRACK v2.2, antetul de autentificare 17token și un tablou care conține un obiect cu un singur număr de urmărire. Confirmați că această versiune și cerințele sale pentru solicitări corespund contului dumneavoastră și documentației oficiale înainte de implementare. Numărul de urmărire este un substituent și trebuie înlocuit cu un identificator real al expediției.

curl --request POST \
  --url 'https://api.17track.net/track/v2.2/register' \
  --header "17token: ${TRACKING_API_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data '[
    {
      "number": "YOUR_TRACKING_NUMBER"
    }
  ]'

Acest exemplu minimal nu demonstrează selectarea transportatorului sau câmpurile suplimentare specifice transportatorului. Consultați documentația privind înregistrarea pentru a determina cum funcționează detectarea transportatorului atunci când câmpul transportatorului este omis și dacă expedierea dumneavoastră necesită informații suplimentare. Dacă furnizați un transportator, utilizați câmpul documentat carrier și identificatorul așteptat de versiunea respectivă a API-ului.

Executați această solicitare dintr-un mediu server-side. Nu includeți tokenul într-un magazin public, într-un script de browser sau într-o aplicație mobilă distribuită clienților. O variabilă de mediu este convenabilă pentru un exemplu local; implementările de producție trebuie să utilizeze controalele de gestionare a secretelor ale organizației dumneavoastră.

Înainte de a crește volumul, testați o expediere cunoscută și analizați răspunsul complet. Apoi testați o intrare invalidă și un lot care conține atât elemente valide, cât și invalide. Aceste verificări arată dacă integrarea dumneavoastră gestionează efectiv rezultatele la nivel de element, în loc să recunoască doar un răspuns HTTP de succes.

Citiți răspunsul la trei niveluri

Un gestionar fiabil al răspunsurilor trebuie să răspundă la trei întrebări separate: a ajuns solicitarea la serviciu, a acceptat serviciul operațiunea și ce s-a întâmplat cu fiecare expediere?

1. Rezultatul HTTP și al transportului

O expirare a conexiunii, o eroare TLS sau un răspuns întrerupt nu vă indică neapărat dacă serverul a procesat solicitarea. Marcați rezultatul ca incert până când îl puteți reconcilia. Un cod de stare HTTP de succes confirmă un schimb HTTP reușit, dar trebuie totuși să analizați răspunsul aplicației.

2. Rezultatul la nivelul solicitării

Analizați rezultatul de nivel superior și câmpurile de eroare documentate ale API-ului. Erorile de autentificare, JSON-ul malformat și restricțiile contului necesită acțiuni diferite. Stocați codul și mesajul de eroare originale ale furnizorului, în loc să reduceți fiecare eroare la „urmărire indisponibilă”.

Nu presupuneți că un cod numeric al aplicației are aceeași semnificație ca un cod de stare HTTP. Semnificațiile lor provin din niveluri diferite și trebuie interpretate separat.

3. Rezultatul la nivelul expediției

Pentru înregistrarea în loturi, țineți cont de fiecare element trimis. Un răspuns poate diferenția expedierile acceptate de cele respinse; analizatorul dumneavoastră trebuie să urmeze schema exactă documentată pentru versiunea selectată. Nu marcați întregul lot ca fiind înregistrat doar pentru că un singur element a reușit.

Normalizați răspunsurile furnizorului în propriile stări stabile ale aplicației. De exemplu, baza dumneavoastră de date poate utiliza accepted, rejected și uncertain. Acestea sunt stări interne sugerate, nu valori literale ale răspunsurilor 17TRACK. Păstrați disponibil răspunsul original al furnizorului în conformitate cu o politică adecvată de păstrare și acces, pentru ca dezvoltatorii să poată investiga discrepanțele.

O înregistrare utilă a înregistrării conține ID-ul intern al expediției, numărul trimis, selecția transportatorului, ora încercării, versiunea API, rezultatul și detaliile erorii furnizorului. Păstrați separat starea înregistrării de starea livrării.

Gestionați reîncercările fără a crea o buclă nesfârșită

Politica de reîncercare trebuie să depindă de eroare, nu doar de apariția unei excepții.

  • Intrare invalidă: corectați câmpul înainte de a reîncerca. Repetarea unei solicitări malformate neschimbate este puțin probabil să ajute.
  • Eșec de autentificare: verificați credențialele și configurarea contului. Evitați trimiterea repetată a aceluiași lot care eșuează.
  • Limitare de rată: respectați limitele documentate și orice instrucțiuni de reîncercare aplicabile. Utilizați o întârziere progresivă limitată, nu reîncercări paralele imediate.
  • Eșec temporar al serviciului: reîncercați într-un interval definit de încercări și timp.
  • Expirare după trimitere: reconciliați starea înregistrării expediției folosind comportamentul API documentat înainte de a presupune că prima încercare a eșuat.
  • Răspuns privind un duplicat: verificați dacă expedierea este deja înregistrată și asociată corect cu evidența aplicației dumneavoastră.

Nu presupuneți că înregistrarea este idempotentă decât dacă documentația definește acest comportament. Deduplicarea la nivelul aplicației reduce trimiterile repetate accidentale, dar nu stabilește politica furnizorului privind gestionarea duplicatelor.

Utilizați o regulă internă de unicitate adecvată modelului dumneavoastră de expediere. Numărul de urmărire singur poate să nu fie o cheie permanentă suficientă între transportatori și perioade lungi de păstrare. Păstrați contextul transportatorului și identificatorul propriu al expediției și documentați modul în care sunt gestionate înlocuirile și numerele corectate.

Monitorizați separat înregistrarea și actualizările de urmărire

Monitorizarea API trebuie să diferențieze un eșec al integrării de o expediere care pur și simplu nu are un eveniment nou al transportatorului. Aceste situații necesită responsabili și remedieri diferite.

Pentru înregistrare, monitorizați numărul de acceptări și respingeri, categoriile de erori, rezultatele incerte, restanțele de reîncercare și latența răspunsurilor. Pentru urmărirea ulterioară, monitorizați separat primirea actualizărilor sau erorile de obținere. Evitați stabilirea unor praguri numerice de alertare până când nu înțelegeți traficul normal și limitele operaționale documentate ale furnizorului.

O verificare practică de producție trebuie să răspundă la următoarele întrebări:

  1. Fiecare expediere care așteaptă urmărirea are o înregistrare de înregistrare?
  2. Fiecare înregistrare acceptată poate fi urmărită până la coletul corect?
  3. Elementele respinse sunt direcționate către cineva care poate corecta datele de bază?
  4. Solicitările incerte sunt reconciliate, nu abandonate sau reîncercate la nesfârșit?
  5. Stările afișate clienților sunt derivate din evenimentele expediției, nu din acceptarea înregistrării?
  6. Credențialele și informațiile personale inutile sunt excluse din jurnale?

Pentru operațiunile de comerț electronic, transferul operațional este la fel de important ca apelul API. Dezvoltatorii trebuie să dețină responsabilitatea pentru erorile de transport și analizare; echipele de expediere sau de onorare a comenzilor trebuie să poată investiga etichetele incorecte, mapările transportatorilor și informațiile lipsă despre expedieri.

Întrebări frecvente

Pot înregistra un număr de urmărire înainte de prima scanare a transportatorului?

Înregistrarea și scanările transportatorului sunt evenimente separate. Un serviciu poate accepta un număr înainte ca evenimentele de urmărire să fie disponibile, în funcție de regulile sale de validare. Nu interpretați acceptarea ca dovadă că transportatorul a primit coletul.

Trebuie să furnizez întotdeauna un cod de transportator?

Depinde de comportamentul de detectare documentat al API-ului și de expedierea implicată. Dacă transportatorul este cunoscut, un identificator explicit și mapat corect poate reduce ambiguitatea. Dacă este necunoscut, utilizați metoda documentată de detectare automată în loc să inventați o valoare pentru transportator.

De ce a returnat API-ul succes HTTP în timp ce o expediere a eșuat?

Solicitarea HTTP poate reuși în timp ce aplicația respinge un element individual. Citiți rezultatul aplicației la nivel superior și rezultatele la nivelul expediției. Această distincție este deosebit de importantă pentru solicitările în loturi.

Ce trebuie să fac atunci când o solicitare de înregistrare expiră?

Tratați rezultatul ca fiind incert. Este posibil ca serverul să fi procesat solicitarea înainte ca conexiunea să eșueze. Verificați comportamentul documentat al furnizorului privind duplicatele și metodele disponibile de căutare a înregistrării sau urmăririi, apoi reconciliați sau reîncercați în cadrul unei politici limitate.

Înregistrarea configurează automat notificările de urmărire?

Nu presupuneți că da. Înregistrarea, obținerea datelor de urmărire și configurarea webhook-urilor sunt preocupări separate ale integrării. Verificați documentația relevantă și testați întregul flux de actualizare înainte de a vă baza pe acesta pentru notificările către clienți.

Surse

  • Documentația API 17TRACK — referință pentru endpoint-urile de înregistrare, autentificare, câmpurile solicitării, identificatorii transportatorilor, schemele de răspuns și gestionarea erorilor. Adaptați detaliile implementării la versiunea API pe care o implementați.
  • Prezentarea generală a Tracking API 17TRACK — punctul oficial de pornire pentru produsul de API de urmărire și resursele de integrare pentru dezvoltatori.