Skip to main content
Faqja kryesoreBlogUdhëzuesSi të merrni statusin më të fundit të dërgesës përmes API-së pa pritur një Webhook

Si të merrni statusin më të fundit të dërgesës përmes API-së pa pritur një Webhook

17TRACK

Për të marrë statusin më të fundit të disponueshëm të dërgesës pa pritur një webhook, dërgoni një kërkesë të autentifikuar te API-ja e ofruesit tuaj të gjurmimit për kërkimin e dërgesës. Përdorni përgjigjen për të përditësuar menjëherë aplikacionin tuaj, më pas mbajini webhook-et të aktivizuara për ndryshimet pasuese. Dallimi i rëndësishëm është se një kërkesë zakonisht merr informacionin më të fundit të ruajtur të gjurmimit nga ofruesi; ajo nuk shkakton domosdoshmërisht një kontroll të ri te transportuesi.

Si të merrni statusin më të fundit të dërgesës përmes API-së pa pritur

Kjo qasje është e dobishme kur një klient hap faqen e porosisë, kur një agjent i mbështetjes ka nevojë për një përditësim ose kur sistemi juaj duhet të rikuperohet nga një njoftim i humbur. Një zbatim i besueshëm kombinon kërkesat sipas nevojës, tregues të qartë të freskisë dhe masa mbrojtëse kundër përditësimeve të dyfishta ose jashtë rendit.

Vendosni se çfarë do të thotë “statusi më i fundit i dërgesës”

Para se të zgjidhni një endpoint, dalloni midis tre veprimeve që mund të duken të ngjashme, por japin rezultate të ndryshme.

VeprimiÇfarë bënÇfarë nuk përcakton
Lexon bazën tuaj të të dhënaveKthen informacionin e gjurmimit që aplikacioni juaj e ruan tashmë.Nëse ofruesi ka marrë një përditësim më të ri.
Kërkon API-në e gjurmimitMerr informacionin e disponueshëm përmes veprimit të kërkimit të ofruesit.Nëse gjatë kësaj kërkese është kryer një kërkim i ri te transportuesi.
Kërkon rifreskimin e gjurmimitKërkon një kontroll tjetër në burimin e sipërm, nëse ofruesi e ofron këtë veprim.Që transportuesi ka një skanim të ri ose që rifreskimi përfundon në mënyrë sinkrone.

Përdorni një kërkesë kur ju nevojitet një përgjigje tani. Hetoni një veprim rifreskimi vetëm kur ju duhet që ofruesi të provojë një kontroll tjetër në burimin e sipërm. Mos supozoni se shtimi i një parametri për anashkalimin e memories cache, përsëritja e një kërkese ose dërgimi i një header-i HTTP cache-control do ta detyrojë transportuesin të japë informacion të ri.

Shikueshmëria e dërgesës ka disa faza: transportuesi regjistron një ngjarje, ofruesi i gjurmimit e merr atë dhe aplikacioni juaj e pranon ose e kërkon. Një kërkesë e drejtpërdrejtë API mund të anashkalojë pritjen për dorëzimin e njoftimit, por nuk mund të eliminojë vonesat më të hershme në këtë zinxhir.

Kontrolloni kontratën e kërkimit para se të shkruani kodin

Zhvilluesi që integron shërbimin e gjurmimit është përgjegjës për këtë rrjedhë pune. Filloni me dokumentacionin aktual të ofruesit, jo me një endpoint të kopjuar nga një shembull i vjetër integrimi. Konfirmoni këto detaje:

  • Identiteti i dërgesës: A pranon kërkimi një numër gjurmimi, një ID të brendshme të dërgesës ose një numër gjurmimi të kombinuar me identifikuesin e transportuesit?
  • Kërkesat e regjistrimit: A duhet të regjistrohet dërgesa para se të mund të kërkohet?
  • Autentikimi: Cili header ose mekanizëm autentikimi kërkohet?
  • Kuptimi i përgjigjes: A kthen veprimi informacion të ruajtur, nis mbledhjen e të dhënave apo kthen një punë që duhet kontrolluar më vonë?
  • Trajtimi i rezultateve: A mund të përmbajë një përgjigje HTTP e suksesshme një dështim në nivel dërgese ose një rezultat në pritje?
  • Kufizimet e përdorimit: Cilat janë kufijtë e frekuencës, kufijtë e grupeve dhe kufizimet specifike të llogarisë?
  • Fushat e freskisë: Cilat vula kohore përfaqësojnë ngjarjet e transportuesit, përditësimet e ofruesit dhe gjenerimin e përgjigjes?

Për një integrim me 17TRACK, Tracking API është produkti përkatës, në vend të një faqeje konsumatore gjurmimi ose një ndërfaqeje gjurmimi të dyqanit. Përdorni dokumentacionin zyrtar të API-së për të konfirmuar veprimin e kërkimit të informacionit të gjurmimit, autentikimin, fushat e kërkesës dhe strukturën e përgjigjes për integrimin tuaj. Trajtojini kërkimet dhe menaxhimin e webhook-eve si shtigje të ndara të aplikacionit që përditësojnë të njëjtin regjistër dërgese.

Shmangni supozimet e koduara drejtpërdrejt për sjelljen e rifreskimit ose shpeshtësinë e kërkimeve. Këto detaje duhet të përputhen me veprimin dhe kushtet e shërbimit që përdorni realisht.

Ndërtoni një kërkim sipas nevojës përmes backend-it tuaj

Një dizajn praktik është të ekspozoni një endpoint të autentifikuar në aplikacionin tuaj. Shfletuesi kërkon një përditësim të dërgesës nga ky endpoint; serveri juaj kontrollon autorizimin, vendos nëse është e nevojshme një kërkesë te ofruesi dhe kthen një rezultat të normalizuar.

Rruga e mëposhtme është një shembull i një endpoint-i që do të krijonit në aplikacionin tuaj. Nuk është endpoint i 17TRACK ose specifikim kërkese i ofruesit.

GET /api/orders/{order_id}/shipment-status

Përdorni identifikuesin e porosisë për të kërkuar dërgesën në server. Mos lejoni që një kërkues të marrë historikun e gjurmimit të një klienti tjetër thjesht duke zëvendësuar një numër gjurmimi në kërkesë. Mbajeni kredencialin e API-së së ofruesit në backend-in tuaj dhe jo në JavaScript-in e shfletuesit ose në paketën e aplikacionit celular.

Një rrjedhë kërkese që mund ta zbatoni

  1. Autorizoni aksesin. Konfirmoni se klienti ose punonjësi lejohet të shohë porosinë.
  2. Zgjidhni dërgesën. Lexoni identifikuesin e ruajtur të gjurmimit dhe informacionin e transportuesit, kur është e zbatueshme.
  3. Kontrolloni freskinë lokale. Nëse ekziston tashmë një kërkim i fundit i suksesshëm, ripërdoreni sipas politikës së freskisë së aplikacionit.
  4. Kërkoni te ofruesi kur nevojitet. Përdorni veprimin e dokumentuar dhe një kufi kohe të përcaktuar për kërkesën.
  5. Vërtetoni rezultatin. Kontrolloni si rezultatin HTTP, ashtu edhe rezultatin në nivel dërgese.
  6. Bashkoni informacionin. Zbatoni të njëjtat rregulla normalizimi dhe pajtimi që përdoren për ngjarjet e webhook-eve.
  7. Ktheni statusin dhe freskinë. Përfshini kohën e ngjarjes më të fundit dhe kohën e kontrollit të fundit të suksesshëm te ofruesi, kur janë të disponueshme.

Politika lokale e freskisë është një vendim inxhinierik, jo një deklaratë për frekuencën e përditësimeve të transportuesit. Zgjidheni duke përdorur kërkesat e ndërfaqes, kufijtë e ofruesit, vëllimin e dërgesave dhe dobishmërinë e vërejtur të kërkimeve. Një klient që klikon vazhdimisht butonin e përditësimit nuk duhet të krijojë një rrjedhë të pakufizuar kërkesash në burimin e sipërm.

Normalizoni përgjigjen pa shpikur freskinë

Aplikacioni juaj mund të kthejë një format të qëndrueshëm të brendshëm edhe kur strukturat e përgjigjeve të ofruesve ndryshojnë. Ky objekt ilustrues është kontrata e aplikacionit tuaj, jo një payload aktual i ofruesit:

{
  "shipment_id": "internal-shipment-id",
  "status": "in_transit",
  "latest_event_at": null,
  "provider_updated_at": null,
  "last_successful_query_at": null,
  "retrieval_state": "success",
  "source": "provider_query"
}

Plotësoni çdo vulë kohore vetëm kur kuptimi i saj është i njohur. Koha kur serveri juaj mori një përgjigje i përket metadata-s së kërkesës; nuk duhet të paraqitet si koha kur lëvizi pakoja. Nëse ofruesi nuk jep një vulë kohore të përditësimit nga ofruesi, lëreni atë fushë të mungojë ose null, në vend që ta zëvendësoni me një vulë tjetër kohore.

Për ndërfaqen e klientit, ndani mesazhet: “Ngjarja më e fundit e transportuesit” përshkruan aktivitetin e dërgesës, ndërsa “Gjurmimi u kontrollua” përshkruan aktivitetin e marrjes së të dhënave nga aplikacioni juaj. Ky dallim parandalon që një skanim i pandryshuar të duket sikur është regjistruar rishtazi.

Mos lejoni që kërkesat API dhe webhook-et të mbishkruajnë njëra-tjetrën

Kur të dy mekanizmat janë aktivë, e njëjta ngjarje mund të mbërrijë përmes një kërkese dhe një webhook-u. Ato gjithashtu mund të përfundojnë në një rend të ndryshëm nga ai në të cilin nisën. Një kërkesë e nisur e para mund të përfundojë pasi një webhook ka dhënë tashmë informacion më të ri.

Mos përdorni logjikën “fiton përgjigjja e fundit”. Payload-i i marrë më së fundmi nuk është domosdoshmërisht gjendja më e fundit e dërgesës.

  • Ndani një tubacion të vetëm për përditësimet. Dërgoni rezultatet e kërkesave dhe payload-et e webhook-eve përmes të njëjtave funksione vërtetimi, normalizimi dhe ruajtjeje.
  • Eliminoni ngjarjet e dyfishta. Preferoni një identifikues të dokumentuar të ngjarjes. Nëse nuk ekziston, krijoni një gjurmë të përcaktuar me kujdes nga fushat e disponueshme, si koha e ngjarjes, statusi, vendndodhja dhe përshkrimi.
  • Përdorni fushat e renditjes me semantikë të njohur. Një revizion ose sekuencë e dokumentuar është më e dobishme sesa supozimi se koha e mbërritjes përfaqëson rendin e ngjarjeve.
  • Ruani historikun. Një ngjarje e marrë rishtazi mund të plotësojë një boshllëk historik pa ndryshuar përmbledhjen aktuale të dërgesës.
  • Lejoni korrigjimet. Statuset nuk janë një shkallë lineare universale. Ndiqni sjelljen e dokumentuar të korrigjimeve në vend që të refuzoni përgjithmonë çdo kalim të dukshëm prapa.

Kur renditja e ngjarjeve është e pasigurt, ruani payload-in origjinal dhe origjinën e tij për hetim. Mos e zgjidhni paqartësinë duke shpikur një vulë kohore të ngjarjes ose duke supozuar se të gjitha vulat kohore të transportuesve përdorin të njëjtën zonë kohore.

Trajtojini ndryshe të dhënat që mungojnë dhe kërkesat e dështuara

Një rezultat bosh, një rezultat i pandryshuar dhe një kërkesë e dështuar nuk duhet të prodhojnë të njëjtin mesazh për klientin.

Kërkesa përfundon me sukses, por statusi nuk ka ndryshuar

Mbajeni statusin ekzistues të dërgesës dhe përditësoni kohën e fundit të kërkesës së suksesshme. Mos krijoni një ngjarje të re dërgese vetëm sepse përfundoi një kërkim tjetër. Nëse klienti ka nevojë për më shumë hollësi, shfaqni historikun ekzistues të ngjarjeve dhe shpjegoni se nuk u kthye asnjë ngjarje më e re gjurmimi.

Dërgesa ende nuk ka informacion gjurmimi

Kontrolloni nëse kërkohet regjistrimi, nëse identifikuesi dhe transportuesi janë të saktë dhe si e paraqet ofruesi mbledhjen në pritje. Mungesa e ngjarjeve nuk provon vetvetiu se numri i gjurmimit është i pavlefshëm ose se pakoja ka humbur. Ruani dallimin e ofruesit midis një identifikuesi të panjohur, një dërgese të regjistruar që pret informacion dhe një kërkese që nuk mund të përpunohej.

Kërkesa te ofruesi skadon ose dështon

Nëse keni një status të mëparshëm të vlefshëm, kthejeni atë me një tregues të qartë se kontrolli më i fundit nuk pati sukses. Mbajeni të pandryshuar vulën kohore të kërkesës së fundit të suksesshme. Një gabim rrjeti nuk është përjashtim dorëzimi dhe nuk duhet të ndryshojë statusin e biznesit të pakos.

Përdorni riprovime të kufizuara me rritje graduale të vonesës dhe shpërndarje të rastësishme për dështimet kalimtare të përshtatshme. Mos riprovoni vazhdimisht kredenciale të pavlefshme ose kërkesa me format të gabuar. Kur një përgjigje jep Retry-After, interpretojeni sipas kontratës së ofruesit dhe semantikës HTTP. Specifikimi HTTP lejon që kjo vlerë të shprehet si vonesë në sekonda ose si datë HTTP.

Mbërrijnë kërkesa të shumta për të njëjtën dërgesë

Bashkoni kërkimet e njëkohshme që të mund të ndajnë një kërkesë të vetme në burimin e sipërm. Zbatoni kufij sipas llogarisë dhe dërgesës dhe parandaloni që një riprovim automatik të shumëfishohet në disa shtresa të aplikacionit. Kur mbështeten grupet, shqyrtoni rezultatin e çdo dërgese në vend që ta trajtoni të gjithë grupin si të suksesshëm vetëm sepse kërkesa HTTP përfundoi.

Përdorni polling-un si alternativë të kontrolluar

Pa webhook-e, polling-u i planifikuar mund ta mbajë bazën tuaj të të dhënave të përditësuar, por kërkon një politikë të qartë funksionimi. Vendosni se cilat dërgesa mbeten të pranueshme, si ndikojnë dështimet në planifikim dhe kur ndalet polling-u rutinë.

Për shumicën e integrimeve, një dizajn hibrid është pikënisje e arsyeshme: webhook-et trajtojnë ndryshimet në sfond, kërkesat sipas nevojës u shërbejnë kërkesave interaktive dhe punët e pajtimit kontrollojnë regjistrat që kërkojnë vëmendje. Ky është një rekomandim arkitekturor, jo garanci se minimizon koston për çdo llogari.

  • Jepuni përparësi dërgesave aktive dhe regjistrave me gabime të pazgjidhura të marrjes së të dhënave.
  • Shmangni kërkimin e çdo dërgese historike në çdo ekzekutim të planifikuar.
  • Përcaktoni si trajtohen dërgesat e përfunduara, duke përfshirë çdo dritare korrigjimi që kërkon biznesi juaj.
  • Ndiqni sa shpesh kërkimet gjejnë informacion vërtet të ri.
  • Hetoni problemet e dorëzimit të webhook-eve në vend që t'i maskoni me polling gjithnjë e më të shpeshtë.

Monitoroni vonesën e kërkesave te ofruesi, kërkimet e pasuksesshme, përgjigjet për kufizimin e frekuencës dhe ndryshimet midis të dhënave të kërkuara dhe regjistrave të ushqyer nga webhook-et. Monitoroni veçmas moshën e ngjarjes më të fundit të transportuesit. Përgjigjet e suksesshme API mund të bashkëjetojnë me informacion gjurmimi që nuk ka ndryshuar.

Testoni rrjedhën e punës para publikimit

Një kërkesë e suksesshme është vetëm testi i parë. Verifikoni situatat që përndryshe mund të krijojnë përditësime mashtruese të statusit:

  • Një webhook mbërrin ndërkohë që një kërkesë sipas nevojës është ende në ekzekutim.
  • Dy klientë ose seanca punonjësish kërkojnë njëkohësisht të njëjtën dërgesë.
  • Ofruesi kthen sukses HTTP, por raporton një gabim në nivel dërgese.
  • Një kërkesë dështon pasi aplikacioni juaj tashmë ka informacion të vlefshëm gjurmimi.
  • Një ngjarjeje i mungon zona kohore ose përmban një kod statusi të panjohur.
  • Një korrigjim i transportuesit ndryshon një rezultat të shfaqur më parë.
  • Një përdorues përpiqet të aksesojë një dërgesë që i përket një llogarie tjetër.

Kriteri juaj i publikimit duhet të jetë që aplikacioni të kthejë informacionin më të mirë të njohur për dërgesën, të shpjegojë saktë freskinë e tij dhe të mos e dëmtojë këtë informacion kur kërkesat dështojnë ose mbërrijnë jashtë rendit.

Pyetje të shpeshta

A e detyron kërkimi i API-së transportuesin të skanojë ose përditësojë një pako?

Jo. Marrja e informacionit të gjurmimit nuk mund të shkaktojë një skanim fizik. Nëse një kërkesë shkakton një kërkim në burimin e sipërm varet nga veprimi i dokumentuar. Edhe një rifreskim i mbështetur mund të kthejë informacion të pandryshuar nëse transportuesi nuk ka një ngjarje më të re.

A mund të përdor kërkesa API pa konfiguruar webhook-e?

Nëse ofruesi mbështet rrjedhën e kërkuar të kërkimit, mund të ndërtoni një integrim rreth kërkesave sipas nevojës ose polling-ut. Konfirmoni fillimisht kërkesat e regjistrimit dhe të kërkimit. Më pas aplikacioni juaj do të jetë përgjegjës për vendosjen se kur të kontrollojë, kontrollin e vëllimit të kërkesave dhe zbulimin e ndryshimeve.

Sa shpesh duhet të përdor polling për statusin e dërgesës?

Nuk ka interval universal. Zgjidhni një plan që përshtatet me kufijtë e ofruesit, vëllimin e dërgesave dhe vlerën e biznesit për gjetjen më të shpejtë të përditësimeve. Matni sa shpesh polling-u kthen ngjarje të reja dhe përshtateni planin, në vend që të supozoni se kërkesat e shpeshta prodhojnë të dhëna më të freskëta të transportuesit.

Pse API-ja kthen informacion që e kam marrë tashmë përmes një webhook-u?

Të dyja rrugët mund të ekspozojnë të njëjtin regjistër bazë të dërgesës. Një webhook dorëzon një njoftim, ndërsa një kërkesë merr informacionin sipas nevojës. Marrja e së njëjtës ngjarje përmes të dyja rrugëve nuk është domosdoshmërisht gabim; aplikacioni juaj duhet ta eliminojë si dublikatë.

A duhet të thotë butoni i përditësimit “Rifresko gjurmimin”?

Vetëm nëse kjo formulim e përshkruan saktë veprimin. Nëse butoni merr të dhënat e ruajtura të ofruesit, “Kontrollo për përditësime” është më i qartë. Shfaqeni ngjarjen e fundit të transportuesit veçmas nga koha kur aplikacioni juaj përfundoi për herë të fundit një kontroll të suksesshëm.

Burimet