Skip to main content
Faqja kryesoreBlogUdhëzuesÇfarë të dhënash duhet të kthejë një API gjurmimi? 12 fusha përtej statusit aktual?

Çfarë të dhënash duhet të kthejë një API gjurmimi? 12 fusha përtej statusit aktual?

17TRACK

Një API gjurmimi duhet të kthejë më shumë se një etiketë të tillë si “Në tranzit”. Përtej statusit aktual, kërkoni identifikuesit e dërgesës, identitetin e transportuesit, informacion të detajuar mbi statusin, mesazhet origjinale të transportuesit, historikun e ngjarjeve, vulat kohore të ngjarjeve, vendndodhjet, vlerësimet e dorëzimit, përjashtimet, kalimet ndërmjet transportuesve, detajet e dorëzimit dhe metadatat mbi freskinë e të dhënave. Së bashku, këto 12 grupe të dhënash i ndihmojnë zhvilluesit të ndërtojnë rrjedha pune të besueshme dhe u japin ekipeve të operacioneve kontekst të mjaftueshëm për të vepruar.

Çfarë të dhënash duhet të kthejë një API gjurmimi: 12 fusha përtej statusit

Ky është një kontrakt i rekomanduar përgjigjeje për zhvilluesit, blerësit teknikë dhe ekipet e operacioneve të tregtisë elektronike — jo një pretendim se çdo transportues ose API ofron çdo fushë. Disa vlera do të jenë në mënyrë legjitime të padisponueshme. Një dizajn më i mirë i bën këto boshllëqe të qarta në vend që t'i plotësojë me supozime.

Çfarë i bën të dobishme të dhënat e gjurmimit?

Një status aktual i përgjigjet një pyetjeje të ngushtë: cila është gjendja e përmbledhur e dërgesës? Ai nuk shpjegon domosdoshmërisht se çfarë ndodhi, kur ndodhi, nëse informacioni është i fundit ose çfarë duhet të bëjë dikush më pas.

Për shembull, dy dërgesa mund të shfaqin të dyja “Në tranzit”, ndërsa kërkojnë përgjigje të ndryshme. Njëra mund të ketë një skanim të fundit në një qendër dhe të mos ketë asnjë problem të raportuar. Tjetra mund të ketë një problem të pazgjidhur me adresën, të regjistruar në historikun e ngjarjeve. Një aplikacion që lexon vetëm statusin kryesor mund të mos e vërejë këtë dallim.

Vlerësojeni përgjigjen kundrejt tre detyrave praktike: përputhja e dërgesës me porosinë e saktë, shpjegimi i saktë i përparimit të saj dhe vendosja nëse një veprim është i justifikuar. Fushat e mëposhtme i mbështesin këto detyra. Emrat e fushave janë ilustrues; ato nuk janë standard universal ose skemë e një ofruesi të caktuar.

12 fusha për t'u vlerësuar përtej statusit aktual

1. Identifikuesit e dërgesës dhe gjurmimit

Përgjigjja duhet të identifikojë dërgesën që përshkruhet. Vlerat e dobishme përfshijnë numrin e gjurmimit të dorëzuar, identifikuesin e regjistrimit të gjurmimit të API-së dhe një referencë të klientit që sistemi juaj mund ta lidhë me një regjistrim përmbushjeje ose pakoje.

Mos supozoni se një porosi është e barabartë me një dërgesë. Një porosi mund të ndahet në disa pako dhe një zëvendësim mund të krijojë një dërgesë tjetër. Ruajini regjistrimet e gjurmimit në nivelin e pakos ose përmbushjes, pastaj lidhini ato me porosinë. Ruajini numrat e gjurmimit si vargje, në mënyrë që formatimi dhe zerot në fillim të mos humbasin.

2. Identiteti i transportuesit

Kërkoni një identifikues të qëndrueshëm të transportuesit së bashku me një emër të lexueshëm të transportuesit. Kur është e disponueshme, përgjigjja duhet të dallojë një transportues të dhënë shprehimisht nga aplikacioni juaj nga një transportues i zgjedhur përmes zbulimit automatik.

Konteksti i transportuesit ka rëndësi gjatë interpretimit të një numri gjurmimi dhe ngjarjeve të tij. Nëse zbulimi është i paqartë, integrimi juaj duhet të ketë një mënyrë për ta zgjidhur atë, në vend që të paraqesë në heshtje një përputhje të pasigurt si të konfirmuar. Mbajeni veç informacionin e nivelit të shërbimit: vetëm emri i transportuesit nuk përcakton nëse një dërgesë përdor shërbim ekspres, postar ose tjetër.

3. Detaj i normalizuar i statusit

Krahas statusit kryesor, kërkoni një kod të dokumentuar detaji ose nënstatus. Një kategori e gjerë mund ta përshkruajë një dërgesë si përjashtim, ndërsa detaji identifikon një tentativë dorëzimi, problem me adresën ose ndalim të lidhur me doganat.

Përdorni kode të qëndrueshme për logjikën e biznesit dhe etiketa të lexueshme për paraqitje. Konfirmoni mënyrën se si ofruesi i lidh ngjarjet e transportuesit me këto kode, duke përfshirë mënyrën se si trajton ngjarjet e panjohura ose të palidhura. Një etiketë e normalizuar e bën më të lehtë përdorimin e burimeve të ndryshme të transportuesve, por nuk duhet të fshijë dallimet që i nevojiten ekipit tuaj të mbështetjes.

4. Mesazhet dhe kodet origjinale të transportuesit

Ruani përshkrimin origjinal të ngjarjes dhe kodin e ngjarjes së transportuesit kur ofrohen. Këto vlera u japin agjentëve të mbështetjes kontekst që mund të mungojë në një status të normalizuar, veçanërisht kur transportuesi përdor një frazë specifike operacionale.

Mbajeni tekstin origjinal veç përshkrimeve të përkthyera ose të rishkruara. Përndryshe, një shpjegim për klientin mund të ngatërrohet me formulimin e saktë të transportuesit. Trajtojeni tekstin e transportuesit si hyrje të pabesueshme gjatë shfaqjes: kodojeni siç duhet dhe mos e paraqitni si HTML të ekzekutueshëm.

5. Historiku i ngjarjeve të gjurmimit

Një përgjigje e dobishme duhet të paraqesë kronologjinë e dërgesës, jo vetëm ngjarjen e fundit. Çdo ngjarje duhet të përfshijë idealisht një identifikues, status ose kod, përshkrim, vulë kohore dhe informacion të disponueshëm mbi vendndodhjen.

Kontrolloni nëse API-ja kthen historikun e plotë, një dritare të kufizuar ose rezultate me faqe. Përcaktoni gjithashtu se si paraqiten korrigjimet dhe vëzhgimet e dyfishta. Aplikacioni juaj nuk duhet të supozojë se elementi i parë është gjithmonë më i riu, përveçse kur kontrata e përgjigjes e garanton shprehimisht këtë renditje.

6. Vulat kohore të ngjarjeve dhe informacioni i zonës kohore

Koha e ndodhjes së një ngjarjeje ndryshon nga koha kur API-ja e mori ose e ktheu atë. Ruajini të dyja kur janë të disponueshme. Ky dallim ndihmon të shpjegohet pse një përditësim i sapomarrë mund të përshkruajë diçka që ka ndodhur më herët.

Kërkoni vula kohore me zhvendosje të qarta UTC ose shënim UTC. RFC 3339 përcakton një format vule kohore të përshtatshëm për protokollet e internetit, duke përfshirë zhvendosjet numerike të kohës. Nëse një burim ofron vetëm kohën lokale pa një zhvendosje të njohur, ruajeni këtë pasiguri në vend që ta trajtoni në heshtje si UTC. Mos nënkuptoni kurrë saktësi në nivel sekondash kur burimi themelor ofron vetëm një datë.

7. Vendndodhjet e ngjarjeve dhe gjeografia e dërgesës

Kërkoni përbërës të strukturuar të vendndodhjes, si qyteti, rajoni, shteti dhe kodi postar, kur ofrohen. Ruani gjithashtu një varg të papërpunuar të vendndodhjes nëse shndërrimi i tij në fusha të strukturuara mund të humbasë kuptimin.

Vendndodhja e skanimit nuk është domosdoshmërisht pozicioni aktual i pakos. Po ashtu, qendra e fundit e raportuar nuk është provë se pakoja ndodhet ende atje. Faqet për klientët duhet ta përshkruajnë atë si vendndodhjen e fundit të raportuar. Shmangni nxjerrjen e koordinatave ose të një adrese të saktë dorëzimi nga teksti i paplotë i skanimit.

8. Data ose intervali i parashikuar i dorëzimit

Një fushë e dorëzimit të parashikuar duhet të tregojë nëse përmban një datë të vetme ose një interval, kush e ka prodhuar dhe kur është përditësuar për herë të fundit. Një vlerësim i ofruar nga transportuesi dhe një parashikim i llogaritur veçmas duhet të mbeten të dallueshëm.

Mos e shndërroni një vlerësim që përmban vetëm datën në një orë të saktë mbërritjeje. Integrimi juaj duhet të trajtojë gjithashtu vlerësimet e rishikuara ose të tërhequra, pa ruajtur një premtim të vjetruar në faqen e gjurmimit. Nëse nuk ekziston një vlerësim, tregoni se nuk është i disponueshëm në vend që ta llogaritni nga një supozim i pambështetur.

9. Arsyeja e përjashtimit dhe veprimi i kërkuar

Informacioni mbi përjashtimin duhet të shpjegojë problemin dhe, kur mbështetet nga burimi, të identifikojë një veprim, palën përgjegjëse ose afatin. Një njoftim i përgjithshëm për vonesë është ndryshe nga një kërkesë për informacionin e marrësit.

Mbajini faktet e raportuara veç vendimeve të rrjedhës suaj të punës. Për shembull, biznesi juaj mund të hapë një detyrë mbështetjeje pas një periudhe të caktuar pa përditësim. Ky është një rregull i brendshëm për përshkallëzim, jo dëshmi se transportuesi e ka deklaruar pakon të humbur. Mos gjeneroni udhëzime pagese ose kërkesa për informacion të ndjeshëm nga teksti i paqartë i gjurmimit.

10. Kalimet ndërmjet transportuesve dhe numrat e lidhur të gjurmimit

Kur një dërgesë kalon ndërmjet operatorëve, të dhënat e dobishme përfshijnë transportuesin e ardhshëm, një numër të lidhur gjurmimi dhe marrëdhënien ndërmjet regjistrimeve origjinale dhe pasuese. Kjo mund të ndihmojë në ruajtjen e vazhdimësisë kur segmenti i dorëzimit përdor një identifikues tjetër.

Trajtojeni një kalim të raportuar si marrëdhënie, në vend që të mbishkruani transportuesin origjinal. Mos bashkoni regjistrime vetëm sepse destinacionet ose numrat e gjurmimit duken të ngjashëm. Nëse marrëdhënia nuk ofrohet ose konfirmohet ndryshe, mbajeni të pazgjidhur në vend që të shpikni një udhëtim të vazhdueshëm.

11. Rezultati i dorëzimit dhe referencat e provës

Kur raportohet dorëzimi, përgjigjja duhet të ofrojë kohën e regjistruar të dorëzimit dhe çdo detaj të disponueshëm, si përshkrimi i një vendi të sigurt ose kategoria e marrësit. Një referencë e provës së dorëzimit mund të jetë gjithashtu e dobishme kur transportuesi dhe shërbimi e ofrojnë atë.

Një status i dorëzuar nuk duhet të trajtohet si provë se marrësi i synuar e ka pranuar personalisht pakon. Nënshkrimet, fotografitë, emrat dhe vendndodhjet e sakta mund të përmbajnë informacion personal. Kufizoni qasjen, shmangni ekspozimin e këtyre detajeve në faqet publike të gjurmimit dhe konfirmoni kërkesat për autorizim ose skadim të lidhjeve të provës.

12. Freskia, gjendja e marrjes dhe metadatat e përgjigjes

Kërkoni mjaftueshëm metadata për të dalluar ngjarjen më të fundit të dërgesës nga marrja e fundit e suksesshme e të dhënave. Vlerat e dobishme përfshijnë kontrollin e fundit të suksesshëm, tentativën e fundit të dështuar, kohën e gjenerimit të përgjigjes dhe nëse të dhënat e kthyera janë të ruajtura në cache ose të pjesshme.

Një kërkesë e suksesshme API-je nuk përcakton vetvetiu se transportuesi ka publikuar një skanim të ri. Semantika e përgjigjes HTTP përshkruan rezultatin e kërkesës; përparimi i dërgesës i përket të dhënave të aplikacionit. Ruajini gabimet e marrjes veç përjashtimeve të dërgesës, në mënyrë që një problem i përkohshëm lidhjeje të mos shndërrohet në alarm të rremë dorëzimi.

Të dhënat që mungojnë kanë nevojë për një kuptim të përcaktuar

Prania e fushës është vetëm një pjesë e kontratës. Ekipi juaj duhet të kuptojë gjithashtu çfarë do të thotë një vlerë që mungon. Një vlerësim dorëzimi mund të jetë i padisponueshëm nga burimi, ende i pamarrë ose i pazbatueshëm pas dorëzimit. Këto situata nuk duhet të prodhojnë automatikisht të njëjtin mesazh për klientin.

  • E panjohur: Vlera nuk është përcaktuar ende.
  • Nuk është dhënë: Burimi nuk e ka ofruar vlerën në të dhënat e marra.
  • Nuk zbatohet: Fusha nuk vlen për këtë regjistrim ose gjendje.
  • Marrja dështoi: Sistemi nuk mundi të përfundojë kërkimin përkatës.

Këto janë dallime të rekomanduara, jo vlera tekstuale të detyrueshme. Cilado qoftë paraqitja që zgjidhni, dokumentojeni. Shmangni datat zëvendësuese, objektet bosh që ngjajnë me regjistrime të vlefshme dhe koordinatat e paracaktuara që mund të ngatërrohen me vendndodhje reale.

Si ta testoni përgjigjen përpara integrimit

Vlerësoni ngarkesat reale nga transportuesit, shërbimet dhe rrugët e transportit që përdor biznesi juaj. Një skemë mund të listojë një fushë opsionale pa garantuar që çdo burim themelor e plotëson atë. Për një integrim me 17TRACK, përdorni dokumentacionin zyrtar të Tracking API për të kontrolluar kontratën e përgjigjes, në vend që t'i trajtoni emrat konceptualë të fushave në këtë udhëzues si parametra të gatshëm për kopjim.

  1. Ndërtoni një mostër përfaqësuese. Përfshini dërgesa të regjistruara rishtazi, dërgesa aktive, tentativa dorëzimi, dorëzime të përfunduara dhe raste të disponueshme kalimi.
  2. Gjurmoini fushat deri te ngjarjet. Konfirmoni që statusi i shfaqur, ngjarja e fundit dhe detajet e dorëzimit përshkruajnë një regjistrim të qëndrueshëm. Hetoni mospërputhjet në vend që t'i fshihni.
  3. Testoni përditësimet e vonuara dhe të përsëritura. Përpunoni sërish të njëjtën ngarkesë dhe merrni një ngjarje më të vjetër pas një ngjarjeje më të re. Konfirmoni që asnjëra situatë nuk krijon njoftime të dyfishta ose nuk e kthen gabimisht gjendjen e shfaqur.
  4. Testoni vlerat që mungojnë dhe ato të keqformuara. Përfshini vlerësime që mungojnë, vendndodhje të panjohura, kode statusi të panjohura dhe vula kohore të paplota. Aplikacioni duhet të mbetet i përdorshëm pa shpikur zëvendësime.
  5. Ndani dështimet e transportit nga rezultatet e gjurmimit. Një dështim autentikimi, skadim kohe ose përgjigje e keqformuar duhet të kalojë në rrugën e gabimit të integrimit, jo në rrjedhën e punës për përjashtimin e dërgesës.
  6. Vlerësoni pamjen për klientin. Kontrolloni që referencat e brendshme, detajet e papërpunuara diagnostikuese dhe informacioni personal të mos rrjedhin në faqet ose njoftimet publike.

Për përditësimet e bazuara në webhook, kontrolloni gjithashtu identifikuesit e dorëzimit, autentikimin, sjelljen e riprovimit dhe trajtimin e riluajtjes në dokumentacionin e ofruesit. Këto janë kërkesa integrimi dhe jo fakte mbi dërgesën. Marrësi juaj duhet t'i përpunojë në mënyrë të sigurt dorëzimet e përsëritura dhe nuk duhet të supozojë se rendi i mbërritjes është i barabartë me rendin e ngjarjeve.

Kriteri i pranimit duhet të jetë praktik: a mundet aplikacioni juaj ta shpjegojë dërgesën pa bërë pretendime të pambështetura dhe a mundet ekipi juaj i operacioneve të identifikojë veprimin tjetër të justifikuar? Një ngarkesë më e vogël dhe e mirëpërcaktuar mund të jetë më e dobishme se një përgjigje më e madhe plot me vlera opsionale të pashpjeguara.

FAQ

A duhet të plotësohen të 12 grupet e të dhënave për çdo dërgesë?

Jo. Provat e dorëzimit, numrat pasues të gjurmimit dhe datat e parashikuara të dorëzimit mund të mos jenë të disponueshme ose të zbatueshme. Kërkoni përkufizime të qarta të fushave dhe sjellje të parashikueshme për vlerat që mungojnë, në vend të plotësimit universal. Kontrolloni fushat më të rëndësishme kundrejt përzierjes reale të dërgesave tuaja.

A duhet ta ruajmë përgjigjen e papërpunuar apo vetëm fushat e normalizuara?

Ruani fushat e normalizuara për logjikën e aplikacionit. Ruajtja e ngarkesave përkatëse burimore mund të ndihmojë gjithashtu në korrigjimin e gabimeve dhe në ndryshimet e hartëzimit, në varësi të kërkesave tuaja për privatësinë, sigurinë, kontratat dhe ruajtjen. Kufizoni qasjen dhe shmangni ruajtjen e përmbajtjes së ndjeshme vetëm sepse shfaqet në një përgjigje.

Cila vulë kohore duhet të përcaktojë ngjarjen më të fundit?

Përdorni kronologjinë e dokumentuar të ngjarjeve dhe rregullat e renditjes së ofruesit, duke marrë parasysh zonat kohore dhe korrigjimet. Koha e marrjes ju tregon kur sistemi juaj mësoi për një ngjarje, jo domosdoshmërisht kur ajo ndodhi. Nëse vulat kohore janë të paplota ose bien ndesh, ruajeni paqartësinë në vend që të pretendoni një renditje të saktë.

A mund të konfirmojë një API gjurmimi se një pako ka humbur?

Trajtojeni një humbje si të raportuar nga transportuesi vetëm kur burimi e mbështet shprehimisht atë interpretim. Një periudhë e gjatë pa skanime mund të justifikojë hetimin sipas rregullave tuaja operacionale, por heshtja e vetme nuk përcakton humbjen. Mbajini “gjurmimi i vjetruar” dhe “i raportuar i humbur” si koncepte të ndara.

A mjafton një status i dorëzuar për të mbyllur një ankesë të klientit?

Jo automatikisht. Ai përcakton rezultatin e raportuar të gjurmimit, por mund të mos zgjidhë mosmarrëveshjen e marrësit. Shqyrtoni detajet e disponueshme të dorëzimit, llogarinë e klientit dhe procesin tuaj të mbështetjes. Shmangni trajtimin e një etikete statusi si zëvendësim për hetimin e informacionit kontradiktor.

Burimet