Skip to main content
Faqja kryesoreBlogUdhëzuesRrjedha e punës së API-së së gjurmimit të dërgesës: nga regjistrimi i një dërgese deri te marrja e detajeve të gjurmimit

Rrjedha e punës së API-së së gjurmimit të dërgesës: nga regjistrimi i një dërgese deri te marrja e detajeve të gjurmimit

17TRACK

Një rrjedhë pune e API-së për gjurmimin e dërgesave fillon me dërgimin e një numri gjurmimi dhe çdo informacioni të kërkuar për transportuesin, kontrollimin nëse regjistrimi u krye me sukses, lejimin që të dhënat e gjurmimit të bëhen të disponueshme dhe marrjen e statusit dhe historikut të ngjarjeve të dërgesës. Për një integrim në prodhim, zhvilluesit duhet gjithashtu të lidhin çdo regjistrim gjurmimi me një porosi, të trajtojnë dështimet e pjesshme, të përpunojnë përditësimet në mënyrë të sigurt dhe të dallojnë një regjistrim të pranuar nga një skanim real i transportuesit.

Rrjedha e punës së API-së për gjurmimin e dërgesave nga regjistrimi i një dërgese deri te marrja e të dhënave

Ky udhëzues shpjegon këtë rrjedhë pune për zhvilluesit që lidhin një platformë ecommerce, sistem menaxhimi porosish, aplikacion magazine ose mjet shërbimi ndaj klientit. Ai veçon rekomandimet për projektimin e aplikacionit nga kërkesat specifike të API-së së ofruesit. Për një integrim me 17TRACK, përdorni dokumentacionin zyrtar të API-së për të konfirmuar skemën e kërkesës, autentikimin, operacionet e mbështetura dhe fushat e përgjigjes përpara se të zbatoni shembujt më poshtë.

Kuptoni çfarë bën dhe çfarë nuk bën regjistrimi

Regjistrimi i një dërgese me një shërbim gjurmimi nënkupton dërgimin e një identifikuesi në mënyrë që shërbimi ta gjurmojë ose menaxhojë atë dërgesë sipas kontratës së API-së. Ky nuk është i njëjti operacion me blerjen e tarifës postare, gjenerimin e etiketës së transportit, rezervimin e marrjes ose dorëzimin e pakos te transportuesi.

Mbani të ndara tre rezultatet në aplikacionin tuaj:

  • Kërkesa u mor: API-ja ktheu një përgjigje ndaj kërkesës suaj HTTP.
  • Regjistrimi u pranua: Shërbimi pranoi regjistrimin individual të gjurmimit për përpunim.
  • Informacioni i gjurmimit është i disponueshëm: Shërbimi ka informacion për dërgesën që aplikacioni juaj mund ta marrë ose ta pranojë.

Këto rezultate nuk duhet të bashkohen në një flamur të vetëm “suksesi”. Një numër gjurmimi i pranuar mund të mos ketë ende ngjarje nga transportuesi. Po kështu, një përgjigje e suksesshme HTTP për një kërkesë në grup nuk vërteton se çdo artikull i grupit u pranua; kontrolloni strukturën e rezultatit në nivel aplikacioni të përcaktuar nga ofruesi.

1. Përgatitni identitetin e dërgesës dhe konfigurimin e API-së

Përpara se të bëni një kërkesë regjistrimi, vendosni se si do të identifikohet një dërgesë brenda sistemit tuaj. Vetëm një identifikues porosie zakonisht nuk mjafton, sepse një porosi mund të ndahet në disa pako. Jepini çdo dërgese ose pakoje regjistrimin e vet të brendshëm dhe lidheni atë me porosinë përkatëse.

Një regjistrim i dobishëm i brendshëm përfshin informacionin e mëposhtëm. Këto janë fusha të sugjeruara të aplikacionit, jo një skemë kërkese e 17TRACK.

  • ID-ja e brendshme e dërgesës: Identifikuesi juaj i qëndrueshëm për pakon.
  • Referenca e porosisë: Porosia ose regjistrimi i përmbushjes të cilit i përket.
  • Numri i gjurmimit: Identifikuesi i dhënë nga transportuesi, i ruajtur si tekst për të ruajtur zerot në fillim.
  • Informacioni i transportuesit: Identiteti i transportuesit i dhënë nga sistemi juaj i përmbushjes, nëse dihet.
  • Referenca e ofruesit: Çdo identifikues i kthyer nga shërbimi i gjurmimit që nevojitet për operacionet e mëvonshme.
  • Gjendja e regjistrimit: Regjistrimi juaj nëse dërgimi është në pritje, i pranuar, i refuzuar ose në pritje të rakordimit.
  • Gjendja e gjurmimit: Statusi më i fundit i dërgesës, i mirëmbajtur veçmas nga gjendja e regjistrimit.

Vërtetoni të dhënat përpara dërgimit. Hiqni hapësirat e tepërta aksidentale përreth, por mos e rishkruani numrin e gjurmimit bazuar në supozime për formatin e transportuesit. Ruani vlerën origjinale për zgjidhjen e problemeve. Nëse transportuesi dihet, hartojeni atë me identifikuesin e dokumentuar të transportuesit nga ofruesi, në vend që të dërgoni një emër joformal shfaqjeje.

Konfiguroni autentikimin në anën e serverit. Mbajini kredencialet jashtë kontrollit të versioneve, ndani konfigurimin e zhvillimit nga ai i prodhimit dhe fshihni sekretet nga regjistrat. Konfirmoni versionin e dokumentuar të API-së, kufijtë e kërkesave, kufijtë e grupeve dhe kërkesat e llogarisë, në vend që të merrni vlera nga një integrim që nuk lidhet me këtë.

2. Regjistroni dërgesën dhe ruani rezultatin në nivel artikulli

Dërgoni regjistrimin e gjurmimit duke përdorur operacionin e regjistrimit të përshkruar në dokumentacionin e ofruesit tuaj. Përfshini vetëm fushat e kërkuara dhe informacionin opsional që shërben për një qëllim të përcaktuar. Shmangni dërgimin e emrave, adresave ose të dhënave të tjera personale të klientëve vetëm sepse ato janë të disponueshme në bazën tuaj të të dhënave të porosive.

Pseudokodi i mëposhtëm ilustron sekuencën e aplikacionit. Emrat e funksioneve janë ilustrues; nuk janë endpoint-e API-je ose metoda SDK-je.

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)

Ruani informacion të mjaftueshëm për të shpjeguar çfarë ndodhi: ID-në e brendshme të dërgesës, kohën e dërgimit, numrin e përpjekjes, rezultatin në nivel artikulli dhe çdo referencë kërkese të ofruesit. Mos u mbështetni vetëm te regjistri kalimtar i punonjësit. Ekipet tuaja të shërbimit ndaj klientit dhe operacioneve kanë nevojë për një përgjigje të qëndrueshme nëse një dërgesë u regjistrua me sukses.

Trajtoni veçmas dërgimet në grup

Nëse API-ja mbështet regjistrimin në grup, lidhni çdo artikull të kthyer me dërgesën e tij origjinale. Mos e shënoni të gjithë grupin si të pranuar vetëm sepse kërkesa HTTP përfundoi me sukses. Ruani artikujt e pranuar, veçoni artikujt e refuzuar dhe hetoni veçmas rezultatet e paqarta.

Kjo parandalon që një numër gjurmimi i formatuar gabim të shkaktojë përsëritje të panevojshme të regjistrimeve që tashmë kanë përfunduar me sukses. Gjithashtu u jep stafit të operacioneve një listë të zbatueshme të regjistrimeve që kërkojnë korrigjim.

Trajtojini skadimet e kohës si rezultat të panjohur

Një skadim kohe nuk provon se regjistrimi dështoi. Ofruesi mund ta ketë pranuar kërkesën përpara se lidhja juaj të ndërpritej. Përdorni sjelljen e dokumentuar të idempotencës, trajtimin e dublikatave ose operacionet e kërkimit për të rakorduar rezultatin përpara se ta ridërgoni verbërisht.

Kur sjellja e ofruesit ndaj dublikatave është e paqartë, provojeni me regjistrime të kontrolluara dhe konfirmoni kontratën përpara se të aktivizoni përsëritjet automatike. Dedublikimi i brendshëm i punëve të regjistrimit është ende i dobishëm, por nuk zëvendëson kuptimin e mënyrës se si shërbimi në distancë trajton kërkesat e përsëritura.

3. Lejoni që informacioni i parë i gjurmimit të mbërrijë

Pas pranimit të regjistrimit, detajet e gjurmimit mund të mos jenë menjëherë të disponueshme. Një etiketë mund të ekzistojë përpara se transportuesi të ketë regjistruar një ngjarje fizike trajtimi. Mungesa e informacionit mund të kërkojë gjithashtu kontrollimin e numrit të gjurmimit, zgjedhjes së transportuesit ose kërkesave të kërkimit specifik për dërgesën.

Paraqiteni këtë gjendje në mënyrë të qartë. “U regjistrua; në pritje të informacionit të gjurmimit” është më e saktë se “Në transit” ose “Regjistrimi dështoi”. Mos shpikni një vlerësim dorëzimi ose një ngjarje lëvizjeje për të mbushur një ndërfaqe bosh.

Kur një regjistrim mbetet bosh, hetojeni sipas rendit praktik:

  1. Konfirmoni që regjistrimi individual u pranua.
  2. Krahasoni numrin e dërguar të gjurmimit me regjistrimin e përmbushjes.
  3. Kontrolloni hartëzimin e transportuesit dhe çdo kërkesë shtesë të dokumentuar për kërkim.
  4. Kontrolloni faqen e vetë transportuesit për gjurmimin e së njëjtës dërgesë.
  5. Nëse transportuesi ka ngjarje, por integrimi juaj jo, kontrolloni përgjigjet e marrjes së të dhënave dhe kontaktoni ofruesin e API-së me informacion diagnostik të anonimizuar.

Shmangni miratimin e një periudhe universale pritjeje pa prova. Rregullat e përshkallëzimit duhet të pasqyrojnë shërbimin e transportit, procesin e pritshëm të dorëzimit dhe angazhimet tuaja operacionale.

4. Merrni detajet e gjurmimit dhe interpretojini saktë

Pasi regjistrimi të jetë i disponueshëm, thirrni operacionin e dokumentuar të detajeve të gjurmimit duke përdorur identifikuesit që kërkon. Mos supozoni se regjistrimi dhe marrja e të dhënave pranojnë fusha identike. Disa kontrata API bëjnë dallim midis numrave të gjurmimit, identifikuesve të transportuesit dhe referencave të regjistrimeve të gjeneruara nga ofruesi.

Aplikacioni juaj duhet të dallojë tre nivele informacioni:

  • Përmbledhja e dërgesës: Gjendja e përgjithshme e përdorur në panelet e kontrollit, faqet e porosive dhe filtrat operacionalë.
  • Historiku i ngjarjeve: Vëzhgimet individuale, duke përfshirë përshkrimet e ngjarjeve, vulat kohore dhe vendndodhjet kur jepen.
  • Metadatat e marrjes: Kur aplikacioni juaj e mori ose e kërkoi informacionin dhe nëse kërkesa përfundoi me sukses.

Një kërkim i suksesshëm do të thotë se operacioni i marrjes përfundoi me sukses. Nuk do të thotë se pakoja ka lëvizur që nga kërkimi i mëparshëm. Krahasoni informacionin e kthyer të gjurmimit me regjistrimin tuaj të ruajtur përpara se të gjeneroni një njoftim ose rrjedhë pune pasuese.

Mbani të ndarë kohën e ngjarjes nga koha e marrjes

Ruani veçmas kohën e lidhur me një ngjarje të transportuesit nga koha kur sistemi juaj e mori atë. Një ngjarje e marrë këtë pasdite mund të përshkruajë një skanim të mëparshëm. Zëvendësimi i kohës së ngjarjes me kohën e marrjes do ta bënte një përditësim të vjetër të dukej si lëvizje e re fizike.

Ruani vulën kohore origjinale dhe çdo zhvendosje të dhënë. Normalizoni vulat kohore për krahasim vetëm kur zona kohore dihet. Nëse një ngjarje nuk ka informacion për zonën kohore, ruajeni këtë pasiguri në vend që t'i caktoni në heshtje zonën kohore të serverit tuaj.

Ruani kuptimin e papërpunuar së bashku me statusin e normalizuar

Një status i normalizuar është i dobishëm për grupimin e dërgesave nëpër transportues, por përshkrimi origjinal i ngjarjes mund të shpjegojë më saktë një problem operacional. Mbajini të dyja kur janë të disponueshme. Vetëm një kategori e gjerë përjashtimi mund të mos i tregojë agjentit të mbështetjes nëse veprimi i radhës është kontrollimi i adresës, kontaktimi i marrësit ose pritja e një përditësimi tjetër.

Mos nxirrni përfundimin për një garanci dorëzimi, humbje të konfirmuar ose rezultat të caktuar doganor nga një status i paqartë. Përshkallëzojeni sipas informacionit bazë dhe politikës suaj të operimit.

5. Mbajini regjistrimet të përditësuara përmes sondimit ose webhook-eve

Marrja e detajeve një herë mjafton për të testuar lidhjen, por jo për të ruajtur dukshmërinë e dërgesës. Projektimi juaj në prodhim ka nevojë për një mekanizëm përditësimi. Konfirmoni mekanizmat e mbështetur nga ofruesi i zgjedhur dhe kushtet që lidhen me ta.

Me sondim, aplikacioni juaj kërkon detajet e gjurmimit sipas një orari. Planifikoni kërkesat brenda kufijve të dokumentuar, shmangni kërkimin e përsëritur të regjistrimeve të pandryshuara pa arsye dhe përdorni vonesë progresive për dështimet që mund të përsëriten. Hapja e faqes së porosisë nga një klient nuk duhet të shkaktojë automatikisht një kërkesë të pakufizuar te shërbimi i jashtëm; një pamje e ruajtur e gjurmimit mund ta shërbejë faqen, ndërsa një proces i kontrolluar në sfond e rifreskon atë.

Nëse përdorni webhook-e, vërtetoni kërkesat hyrëse duke përdorur mekanizmin e dokumentuar të verifikimit të ofruesit. Ruani ose vendosini në një radhë të qëndrueshme mesazhet e pranuara përpara se t'i konfirmoni sipas kontratës së webhook-ut, më pas përpunojini ngjarjet në mënyrë asinkrone.

Ndërtoni marrësin që të tolerojë dublikatat dhe rendin e papritur të mbërritjes, përveç rasteve kur kontrata e dokumentuar e dorëzimit garanton të kundërtën. Përdorni një identifikues ngjarjeje të ofruesit për dedublikim kur është i disponueshëm. Përndryshe, përcaktoni dhe testoni një gjurmë identifikuese të bazuar në fusha të përshtatshme të ngjarjes, duke pranuar se kjo gjurmë mund të kërkojë përshtatje për të dhënat tuaja.

Një integrim i drejtuar nga webhook-et mund të përdorë gjithashtu marrjen e kontrolluar të të dhënave për rakordim. Për shembull, një punë rikuperimi mund të kontrollojë regjistrimet e prekura nga një ndërprerje e marrësit. Ky është një model qëndrueshmërie, jo leje për të shpërfillur kufijtë e shpejtësisë ose udhëzimet specifike të ofruesit.

6. Shndërrojeni informacionin e gjurmimit në veprime të sigurta biznesi

Përditësoni regjistrimin e brendshëm të dërgesës përpara se të aktivizoni veprime që u shfaqen klientëve. Mbani një regjistrim të qëndrueshëm të njoftimeve dhe kalimeve të rrjedhës së punës, në mënyrë që një ngjarje e përsëritur të mos gjenerojë mesazhe të përsëritura.

Lidhini veprimet e biznesit me ndryshime domethënëse, jo me çdo përgjigje të API-së. Një ngjarje e re dorëzimi e vëzhguar mund të justifikojë një njoftim për dorëzimin. Një përgjigje e përsëritur që përmban të njëjtën ngjarje nuk duhet ta bëjë këtë. Një përjashtim mund të justifikojë një shqyrtim të brendshëm, por mesazhi për klientin duhet të pasqyrojë atë që thotë realisht ngjarja.

Përcaktoni se si do të trajtoni ngjarjet e marra pasi një dërgesë është konsideruar e përfunduar. Mos e fshini historikun e ngjarjeve ose mos i bllokoni përgjithmonë të gjitha përditësimet e mëvonshme vetëm sepse një përmbledhje arriti një gjendje përfundimtare. Rregullat tuaja të ruajtjes, rakordimit dhe njoftimeve duhet të marrin parasysh korrigjimet legjitime pa rihapur vazhdimisht rrjedhat e përfunduara të punës.

Zbatimi i rrjedhës së punës në një integrim me 17TRACK

Për një integrim të personalizuar gjurmimi, pikat përkatëse të nisjes janë faqja e API-së së gjurmimit të 17TRACK dhe dokumentacioni i zhvilluesve. Përdorni faqen e produktit për të vlerësuar ofertën dhe dokumentacionin për të përcaktuar kontratën reale të integrimit. Faqet e gjurmimit për konsumatorët nuk zëvendësojnë specifikimet e API-së.

Përpara se të shkruani përshtatësin tuaj, konfirmoni formatin e autentikimit, operacionet e regjistrimit dhe marrjes së të dhënave, rregullat e identifikimit të transportuesit, trajtimin e përgjigjeve në nivel artikulli dhe kufijtë e zbatueshëm të kërkesave. Për përpunimin e bazuar në webhook-e, konfirmoni gjithashtu skemën e ngarkesës, procesin e verifikimit, kërkesat e konfirmimit dhe sjelljen e përsëritjeve.

Mbajini këto detaje specifike të ofruesit brenda një përshtatësi, në vend që të shpërndani supozime për fushat e përgjigjes në të gjithë sistemin tuaj të porosive. Më pas pjesa tjetër e aplikacionit tuaj mund të punojë me koncepte të brendshme si rezultati i regjistrimit, statusi i dërgesës, historiku i ngjarjeve dhe sinkronizimi i fundit i suksesshëm.

Kontrollet para nisjes që zbulojnë gabime të kushtueshme

  • Regjistrim i pranuar, por bosh: Ndërfaqja tregon se informacioni i gjurmimit është në pritje, jo se pakoja po lëviz.
  • Rezultat i përzier i grupit: Çdo dërgesë merr rezultatin e vet të ruajtur.
  • Skadim kohe pas dërgimit: Punonjësi rakordon rezultatin e pasigurt në vend që të supozojë dështim.
  • Ngjarje e përsëritur: Afati kohor i dërgesës dhe njoftimi i klientit mbeten të dedublikuara.
  • Ngjarje më e vjetër e marrë më vonë: Ngjarja ruhet pa zëvendësuar verbërisht një përmbledhje më të re.
  • Shërbim i jashtëm i padisponueshëm: Faqja e klientit mund të shfaqë rezultatin e fundit të ruajtur me një tregues të përshtatshëm freskie.
  • Hartëzim i pasaktë i transportuesit: Regjistrimi mund të korrigjohet përmes një rruge të dokumentuar rikuperimi.
  • Porosi e ndarë: Çdo pako ruan gjendjen dhe historikun e vet të gjurmimit.
  • Ekspozim i kredencialeve ose ngarkesës: Regjistrat përmbajnë referenca diagnostike pa nxjerrë sekrete ose informacion personal të panevojshëm.

Kriteri praktik i përfundimit nuk është thjesht marrja e një përgjigjeje të suksesshme regjistrimi. Është aftësia për të gjurmuar një pako nga dërgimi deri te përditësimet, për të shpjeguar një rezultat bosh ose të dështuar dhe për t'u rikuperuar nga përpunimi i ndërprerë pa humbur ngjarje ose pa dyfishuar veprimet ndaj klientëve.

Pyetje të shpeshta

A krijon një dërgesë regjistrimi i një numri gjurmimi?

Jo në rrjedhën e punës të përshkruar këtu. Regjistrimi i gjurmimit dërgon një identifikues ekzistues te një shërbim gjurmimi. Krijimi i etiketës, blerja e tarifës postare dhe rezervimi me transportuesin janë operacione të ndara, përveç rasteve kur një API e caktuar i bashkon shprehimisht.

Pse detajet e gjurmimit janë bosh pasi regjistrimi përfundon me sukses?

Pranimi i regjistrimit dhe disponueshmëria e të dhënave të gjurmimit janë kushte të ndryshme. Transportuesi mund të mos ketë regjistruar ende një ngjarje, ose mund të duhet të kontrollohet numri i gjurmimit, hartëzimi i transportuesit ose informacioni shtesë i kërkimit. Kontrolloni rezultatin në nivel artikulli përpara se ta trajtoni regjistrimin si të suksesshëm.

A duhet ta regjistroj dërgesën sa herë që marr statusin e saj?

Mos përdorni regjistrimin e përsëritur si mekanizëm të parazgjedhur rifreskimi. Ruani gjendjen e regjistrimit të pranuar dhe përdorni mekanizmin e dokumentuar të marrjes ose përditësimit. Ndiqni rregullat e qarta të ofruesit për korrigjimet, riaktivizimin ose dërgimet dublikatë.

A duhet të përdor sondimin apo webhook-et?

Përdorni mekanizmin që përshtatet me kontratën e dokumentuar të API-së dhe kërkesat tuaja operacionale. Sondimi kërkon një orar të kontrolluar kërkesash. Webhook-et kërkojnë një marrës të sigurt e të qëndrueshëm dhe përpunim të sigurt ndaj dublikatave. Kur mbështeten, përditësimet përmes webhook-eve me rakordim të synuar mund të ofrojnë një rrugë praktike rikuperimi.

A mund ta përdor një numër gjurmimi si identifikuesin e vetëm të dërgesës në bazën time të të dhënave?

Përdorni në vend të tij një identifikues të brendshëm të dërgesës. Ruani numrin e gjurmimit dhe kontekstin përkatës të transportuesit si atribute të atij regjistrimi. Kjo i bën porositë e ndara, numrat e korrigjuar të gjurmimit dhe referencat specifike të ofruesit më të lehta për t'u menaxhuar pa ndryshuar identitetin e dërgesës suaj të brendshme.

Burimet

  • API-ja e gjurmimit të 17TRACK — pikënisja zyrtare e produktit për vlerësimin e një integrimi me API-në e 17TRACK.
  • Dokumentacioni i API-së së 17TRACK — referencë zyrtare për formatet e kërkesave, operacionet, përgjigjet dhe kërkesat e integrimit specifike për zbatimin. Pseudokodi dhe sugjerimet për fushat e brendshme në këtë udhëzues janë shembuj të projektimit të aplikacionit, jo citime të kësaj kontrate API-je.