Skip to main content
Faqja kryesoreBlogUdhëzuesSi të regjistroni një numër gjurmimi përmes API-së: fushat e kërkesës, kodet e transportuesve dhe përgjigjet

Si të regjistroni një numër gjurmimi përmes API-së: fushat e kërkesës, kodet e transportuesve dhe përgjigjet

17TRACK

Për të regjistruar një numër gjurmimi përmes API-së, dërgoni një kërkesë të autentikuar regjistrimi që përmban numrin e gjurmimit të dërgesës dhe, kur kërkohet, një identifikues të transportuesit. Më pas kontrolloni përgjigjen për çdo dërgesë të dorëzuar—jo vetëm statusin HTTP—dhe ruani nëse regjistrimi u krye me sukses, dështoi apo mbetet i pasigurt. Regjistrimi nis rrjedhën e gjurmimit; ai nuk provon se transportuesi e ka skanuar pakon ose se ngjarjet e gjurmimit janë tashmë të disponueshme.

Si të regjistroni një numër gjurmimi përmes fushave të kërkesës API

Ky udhëzues është për zhvilluesit që lidhin një sistem menaxhimi porosish, aplikacion magazine ose platformë ecommerce me një API gjurmimi. Ai përdor 17TRACK si shembull konkret integrimi dhe shpjegon se cilat detaje duhet të kontrollohen kundrejt dokumentacionit për versionin e zgjedhur të API-së.

Çfarë bën regjistrimi—dhe çfarë nuk bën

Një kërkesë regjistrimi i tregon një shërbimi gjurmimi se cilën dërgesë dëshironi të gjurmoni. Ajo ndryshon nga blerja e një etikete transporti, rezervimi i mbledhjes ose kërkesa ndaj një transportuesi për të krijuar një dërgesë. Në një integrim tipik, rrjedha e transportit prodhon fillimisht një numër gjurmimi dhe aplikacioni juaj e regjistron atë numër më pas.

Mbajini të ndara këto tri ngjarje në aplikacionin tuaj:

  • Dërgesa u krijua: sistemi juaj i transportit ka caktuar një numër gjurmimi.
  • Regjistrimi u pranua: shërbimi i gjurmimit e ka pranuar dërgesën për gjurmim.
  • Informacioni i gjurmimit u mor: ngjarjet e transportuesit janë bërë të disponueshme përmes shërbimit të gjurmimit.

Mos e përditësoni porosinë në “në tranzit” thjesht sepse regjistrimi ishte i suksesshëm. Një etiketë e krijuar rishtazi mund të mos ketë ende një skanim fizik pranimi. Statusi i dërgesës i shfaqur për klientët duhet të bazohet në ngjarjet e gjurmimit të interpretuara përmes rregullave tuaja të hartëzimit të statusit, jo në përgjigjen e regjistrimit.

Për integrimet me 17TRACK, filloni me përmbledhjen e Tracking API dhe përdorni dokumentacionin zyrtar të API-së si autoritet për endpoint-et, përkufizimet e fushave, autentikimin dhe kodet e përgjigjes. Shembujt më poshtë përqendrohen te regjistrimi dhe jo te detyrat e veçanta të marrjes së rezultateve ose pranimit të përditësimeve.

Përgatitni fushat e kërkesës para se të shkruani thirrjen API

Përgatitja më e dobishme është një kontratë e vogël fushash midis sistemit tuaj të transportit dhe integrimit të gjurmimit. Vendosni se nga buron secila vlerë, nëse mund të mungojë dhe si do të vlerësohet.

Fusha ose vleraQëllimiRregulli i zbatimit
Numri i gjurmimitIdentifikon dërgesën që duhet gjurmuar.Ruajeni dhe transmetojeni si varg; ruani zerot në fillim.
Identifikuesi i transportuesitIdentifikon transportuesin brenda sistemit të ofruesit të gjurmimit.Përdorni identifikuesin e dokumentuar nga ofruesi, jo një kod të brendshëm magazine.
Referenca e brendshmeLidh regjistrimin me të dhënat e dërgesës suaj.Përdorni një fushë reference të mbështetur, nëse është e disponueshme; gjithsesi ruani hartëzimin në bazën tuaj të të dhënave.
Të dhëna shtesë identifikimiMund të ndihmojnë në identifikimin e një dërgese kur transportuesi kërkon më shumë se numrin e gjurmimit.Dërgoni vetëm fushat e dokumentuara për atë integrim dhe transportues.
Kredenciali APIAutentikon llogarinë që kryen thirrjen.Mbajeni në server dhe përjashtojeni nga regjistrat e aplikacionit.

Trajtojeni numrin e gjurmimit si identifikues

Mos e konvertoni kurrë një numër gjurmimi në numër të plotë. Konvertimi numerik mund të heqë zerot në fillim dhe vlerat e mëdha mund të humbasin saktësinë në disa mjedise programimi. Hiqni hapësirat e rastësishme përreth, por mos hiqni shenjat e pikësimit dhe mos ndryshoni shkronjat e mëdha ose të vogla, përveçse kur dokumentacioni përkatës ose formati i transportuesit e mbështet një normalizim të tillë.

Vlerësoni gabimet e dukshme të hyrjes para thirrjes së API-së: vargje bosh, ndërprerje të papritura rreshti dhe një numër porosie të kopjuar në fushën e numrit të gjurmimit. Shmangni vendosjen e një rregulli universal për gjatësinë ose karakteret për të gjithë transportuesit. Një rregull që përshtatet me një transportues mund të refuzojë numra të vlefshëm nga një tjetër.

Mbajini veç referencat e porosisë nga identitetet e dërgesave

Një porosi mund të ketë disa pako dhe një dërgesë zëvendësuese mund të sjellë një numër tjetër gjurmimi. Modelojeni regjistrimin në nivel dërgese ose pakoje, në vend që të supozoni një numër gjurmimi për çdo porosi.

Nëse përdorni një etiketë ose fushë reference të mbështetur nga ofruesi, preferoni një referencë të paqartë të dërgesës në vend të adresës së emailit ose adresës së rrugës së klientit. Baza juaj e të dhënave duhet të mbetet lidhja autoritative midis porosive, dërgesave, numrave të gjurmimit dhe hartëzimeve të transportuesve.

Zgjidhni kodin e duhur të transportuesit

Një kod transportuesi nuk është domosdoshmërisht një identifikues universal i industrisë. Vlera e njohur nga një platformë gjurmimi mund të ndryshojë nga emri i transportuesit të ruajtur në softuerin tuaj të transportit. Edhe dy sisteme që përdorin kode numerike mund t'u caktojnë numra të ndryshëm të njëjtit transportues.

Mbani një hartëzim të qartë nga shërbimi juaj i transportit te identifikuesi i transportuesit të ofruesit të gjurmimit. Kur është e nevojshme, dalloni operacionin ose shërbimin rajonal të transportuesit nga marka e tij më e gjerë. Një hartëzim i bazuar vetëm në emrin e shfaqur mund të bëhet i paqartë kur sistemet e transportit përdorin pseudonime.

  • Kur transportuesi dihet: përdorni identifikuesin e dokumentuar të transportuesit kur mbështetet, veçanërisht kur formatet e numrave të gjurmimit mbivendosen.
  • Kur transportuesi nuk dihet: përdorni zbulimin automatik vetëm përmes mekanizmit të dokumentuar. Mos supozoni se mungesa, një varg bosh, zeroja dhe null kanë të njëjtin kuptim.
  • Kur rezultati duket i gabuar: verifikoni etiketën origjinale, shërbimin e transportit dhe hartëzimin para se të regjistroni vazhdimisht të njëjtin numër.

Zbulimi automatik është i dobishëm, por nuk është dëshmi se një transportues i caktuar e mban fizikisht dërgesën. Po kështu, një kod i vlefshëm transportuesi nuk garanton se numri i dhënë i gjurmimit i përket atij transportuesi.

Mbajini hartëzimet e transportuesve të konfigurueshme dhe mos i shpërndani nëpër kodin e aplikacionit. Regjistroni kur u kontrollua për herë të fundit një hartëzim dhe përfshini një dërgesë të njohur në testet e regresionit sa herë që e ndryshoni.

Shembull: dërgoni një kërkesë regjistrimi në 17TRACK

Shembulli vijues ilustron endpoint-in e regjistrimit të 17TRACK v2.2, kokën e autentikimit 17token dhe një varg që përmban një objekt me numër gjurmimi. Konfirmoni që ky version dhe kërkesat e tij për kërkesën përputhen me llogarinë tuaj dhe dokumentacionin zyrtar para vendosjes. Numri i gjurmimit është një vendmbajtës dhe duhet zëvendësuar me një identifikues real dërgese.

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"
    }
  ]'

Ky shembull minimal nuk demonstron zgjedhjen e transportuesit ose fushat plotësuese specifike për transportuesin. Kontrolloni dokumentacionin e regjistrimit për të përcaktuar se si funksionon zbulimi i transportuesit kur fusha e transportuesit mungon dhe nëse dërgesa juaj kërkon informacion shtesë. Nëse jepni një transportues, përdorni fushën e dokumentuar carrier dhe identifikuesin që pret ai version i API-së.

Kryejeni këtë kërkesë nga një mjedis në anën e serverit. Mos e vendosni token-in në një vitrinë publike, skript shfletuesi ose aplikacion celular të shpërndarë te klientët. Një variabël mjedisi është i përshtatshëm për një shembull lokal; vendosjet në prodhim duhet të përdorin kontrollet e menaxhimit të sekreteve të organizatës suaj.

Para se të rrisni vëllimin, testoni një dërgesë të njohur dhe kontrolloni përgjigjen e plotë. Më pas testoni një hyrje të pavlefshme dhe një grup që përmban artikuj të vlefshëm dhe të pavlefshëm. Këto kontrolle tregojnë nëse integrimi juaj trajton vërtet rezultatet në nivel artikulli dhe jo vetëm njeh një përgjigje suksesi HTTP.

Lexojeni përgjigjen në tri nivele

Një trajtues i besueshëm i përgjigjes u përgjigjet tri pyetjeve të veçanta: a arriti kërkesa te shërbimi, a e pranoi shërbimi veprimin dhe çfarë ndodhi me secilën dërgesë?

1. Rezultati HTTP dhe i transportit

Një skadim lidhjeje, dështim TLS ose përgjigje e ndërprerë nuk ju tregon domosdoshmërisht nëse serveri e përpunoi kërkesën. Shënojeni atë rezultat si të pasigurt derisa të mund ta rakordoni. Një status suksesi HTTP konfirmon një shkëmbim të suksesshëm HTTP, por ende duhet të kontrolloni përgjigjen e aplikacionit.

2. Rezultati në nivel kërkese

Kontrolloni rezultatin kryesor dhe fushat e gabimit të dokumentuara nga API-ja. Gabimet e autentikimit, JSON-i i formatuar gabim dhe kufizimet e llogarisë kërkojnë veprime të ndryshme. Ruani kodin dhe mesazhin origjinal të gabimit të ofruesit, në vend që çdo dështim ta reduktoni në “gjurmimi nuk është i disponueshëm”.

Mos supozoni se një kod numerik i aplikacionit ka të njëjtin kuptim si një kod statusi HTTP. Kuptimet e tyre vijnë nga shtresa të ndryshme dhe duhet të interpretohen veçmas.

3. Rezultati në nivel dërgese

Për regjistrimin në grup, llogarisni çdo artikull të dorëzuar. Një përgjigje mund të dallojë dërgesat e pranuara nga ato të refuzuara; analizuesi juaj duhet të ndjekë skemën e saktë të dokumentuar për versionin e zgjedhur. Mos e shënoni të gjithë grupin si të regjistruar vetëm sepse një artikull pati sukses.

Normalizoni përgjigjet e ofruesit në gjendje të qëndrueshme të aplikacionit tuaj. Për shembull, baza juaj e të dhënave mund të përdorë accepted, rejected dhe uncertain. Këto janë gjendje të sugjeruara të brendshme, jo vlera fjalë për fjalë të përgjigjes së 17TRACK. Mbajeni të disponueshme përgjigjen origjinale të ofruesit sipas një politike të përshtatshme ruajtjeje dhe aksesi, në mënyrë që zhvilluesit të mund të hetojnë mospërputhjet.

Një regjistrim i dobishëm regjistrimi përmban ID-në e brendshme të dërgesës, numrin e dorëzuar, zgjedhjen e transportuesit, kohën e përpjekjes, versionin e API-së, rezultatin dhe detajet e gabimit të ofruesit. Mbajeni statusin e regjistrimit të ndarë nga statusi i dorëzimit.

Trajtojini riprovimet pa krijuar një cikël të pafund

Politika e riprovimit duhet të varet nga dështimi dhe jo thjesht nga fakti nëse ndodhi një përjashtim.

  • Hyrje e pavlefshme: korrigjojeni fushën para riprovimit. Përsëritja e një kërkese të pandryshuar dhe të formatuar gabim nuk ka gjasa të ndihmojë.
  • Dështim autentikimi: verifikoni kredencialet dhe konfigurimin e llogarisë. Shmangni dërgimin e përsëritur të të njëjtit grup që dështon.
  • Kufizim norme: ndiqni kufijtë e dokumentuar dhe udhëzimet e zbatueshme për riprovim. Përdorni tërheqje të kufizuar në vend të riprovimeve të menjëhershme paralele.
  • Dështim i përkohshëm i shërbimit: riprovoni brenda një buxheti të përcaktuar për përpjekjet dhe kohën.
  • Skadim kohe pas dorëzimit: rakordoni gjendjen e regjistrimit të dërgesës duke përdorur sjelljen e dokumentuar të API-së para se të supozoni se përpjekja e parë dështoi.
  • Përgjigje e lidhur me dublikatat: kontrolloni nëse dërgesa është regjistruar tashmë dhe është lidhur saktë me të dhënat e aplikacionit tuaj.

Mos supozoni se regjistrimi është idempotent, përveçse nëse dokumentacioni e përcakton këtë sjellje. Dedublikimi në anën e aplikacionit redukton dërgimet e përsëritura aksidentale, por nuk përcakton politikën e ofruesit për trajtimin e dublikatave.

Përdorni një rregull unik të brendshëm të përshtatshëm për modelin e dërgesave tuaja. Vetëm numri i gjurmimit mund të mos jetë një çelës i përhershëm i mjaftueshëm nëpër transportues dhe periudha të gjata ruajtjeje. Ruani kontekstin e transportuesit dhe identifikuesin tuaj të dërgesës, dhe dokumentoni mënyrën e trajtimit të zëvendësimeve dhe numrave të korrigjuar.

Monitoroni regjistrimin veçmas nga përditësimet e gjurmimit

Monitorimi i API-së duhet të dallojë një dështim integrimi nga një dërgesë që thjesht nuk ka ngjarje të re transportuesi. Këto kushte kërkojnë përgjegjës dhe zgjidhje të ndryshme.

Për regjistrimin, monitoroni numërimet e pranimeve dhe refuzimeve, kategoritë e gabimeve, rezultatet e pasigurta, numrin e riprovimeve në pritje dhe vonesën e përgjigjes. Për gjurmimin e mëvonshëm, monitoroni veçmas marrjen e përditësimeve ose dështimet e marrjes së tyre. Shmangni caktimin e pragjeve numerike të alarmit derisa të kuptoni trafikun normal dhe kufijtë e dokumentuar të funksionimit të ofruesit.

Një kontroll praktik i prodhimit duhet t'u përgjigjet këtyre pyetjeve:

  1. A ka çdo dërgesë që pret gjurmim një regjistrim regjistrimi?
  2. A mund të gjurmohet çdo regjistrim i pranuar deri te pakoja e saktë?
  3. A u drejtohen artikujt e refuzuar personave që mund të korrigjojnë të dhënat bazë?
  4. A rakordohen kërkesat e pasigurta në vend që të braktisen ose të riprovohen pafundësisht?
  5. A nxirren statuset e shfaqura për klientët nga ngjarjet e dërgesës dhe jo nga pranimi i regjistrimit?
  6. A përjashtohen kredencialet dhe informacioni personal i panevojshëm nga regjistrat?

Për operacionet ecommerce, dorëzimi operacional ka po aq rëndësi sa thirrja API. Zhvilluesit duhet të zotërojnë dështimet e transportit dhe analizimit; ekipet e transportit ose përmbushjes duhet të jenë në gjendje të hetojnë etiketat e pasakta, hartëzimet e transportuesve dhe informacionin e munguar të dërgesave.

FAQ

A mund ta regjistroj një numër gjurmimi para skanimit të parë nga transportuesi?

Regjistrimi dhe skanimet e transportuesit janë ngjarje të ndara. Një shërbim mund ta pranojë një numër para se ngjarjet e gjurmimit të jenë të disponueshme, në varësi të rregullave të tij të vlerësimit. Mos e interpretoni pranimin si provë se transportuesi e ka marrë pakon.

A duhet të jap gjithmonë një kod transportuesi?

Kjo varet nga sjellja e dokumentuar e zbulimit nga API-ja dhe nga dërgesa në fjalë. Nëse transportuesi dihet, një identifikues i qartë dhe i hartëzuar saktë mund të ulë paqartësinë. Nëse nuk dihet, përdorni metodën e dokumentuar të zbulimit automatik në vend që të shpikni një vlerë transportuesi.

Pse API-ja ktheu sukses HTTP ndërsa një dërgesë dështoi?

Kërkesa HTTP mund të ketë sukses ndërsa aplikacioni refuzon një artikull individual. Lexoni rezultatin kryesor të aplikacionit dhe rezultatet në nivel dërgese. Ky dallim është veçanërisht i rëndësishëm për kërkesat në grup.

Çfarë duhet të bëj kur një kërkesë regjistrimi skadon?

Trajtojeni rezultatin si të pasigurt. Serveri mund ta ketë përpunuar kërkesën para se lidhja të dështonte. Kontrolloni sjelljen e dokumentuar të ofruesit për dublikatat dhe metodat e disponueshme të kërkimit të regjistrimit ose gjurmimit, më pas rakordojeni ose riprovojeni sipas një politike të kufizuar.

A i konfigur​on automatikisht regjistrimi njoftimet e gjurmimit?

Mos supozoni se po. Regjistrimi, marrja e gjurmimit dhe konfigurimi i webhook-ut janë çështje të veçanta integrimi. Verifikoni dokumentacionin përkatës dhe testoni të gjithë rrugën e përditësimit para se të mbështeteni tek ajo për njoftimet e klientëve.

Burimet

  • Dokumentacioni API i 17TRACK — referencë për endpoint-et e regjistrimit, autentikimin, fushat e kërkesës, identifikuesit e transportuesve, skemat e përgjigjes dhe trajtimin e gabimeve. Përputhini detajet e zbatimit me versionin e API-së që vendosni.
  • Përmbledhja e 17TRACK Tracking API — pikënisja zyrtare për produktin e tracking API dhe burimet e integrimit për zhvilluesit.