Si të integroni një API për gjurmimin e dërgesave në dyqanin tuaj të tregtisë elektronike

Për të integruar një API për gjurmimin e dërgesave në dyqanin tuaj të tregtisë elektronike, lidhni sistemin e porosive me ofruesin e gjurmimit, dërgoni të dhënat e dërgesës dhe transportuesit përmes një kërkese të sigurt nga ana e serverit, ruani ngjarjet e normalizuara të gjurmimit dhe shfaqni statusin përfundimtar në ndërfaqet për klientët dhe ekipin e mbështetjes. Një zbatim i besueshëm është më shumë se shtimi i një fushe për numrin e gjurmimit: ai duhet të trajtojë zgjedhjen e transportuesit, përditësimet e statusit, përjashtimet e dorëzimit, riprovimet, privatësinë dhe mënyrën se si klientët përdorin realisht informacionin pas blerjes.

Ky udhëzues shpjegon një qasje praktike integrimi për pronarët e dyqaneve, zhvilluesit dhe ekipet e operacioneve. Ai përdor dokumentacionin zyrtar të Tracking API të 17TRACK si pikë reference, por të njëjtat parime planifikimi zbatohen edhe kur vlerësoni një ofrues tjetër me shumë transportues.

Përcaktoni çfarë duhet të arrijë integrimi

Filloni me rezultatin e biznesit dhe jo me pikën fundore të API-së. Shumica e dyqaneve duan të reduktojnë kontaktet me pyetjen “Ku është porosia ime?”, t’u japin blerësve një pamje të qartë të dorëzimit dhe të ndihmojnë operacionet të identifikojnë dërgesat e vonuara para se të ankohet klienti. Këto objektiva kërkojnë të dhëna dhe rrjedha pune të ndryshme.

• Vizibiliteti për klientin: shfaqni statusin aktual të dërgesës, informacionin e parashikuar të dorëzimit kur është i disponueshëm, detajet e transportuesit dhe ngjarjen e fundit domethënëse.
• Vizibiliteti operacional: lejoni stafin të gjejë dërgesat e vonuara, të bllokuara, të kthyera ose me përjashtime te transportues të ndryshëm.
• Komunikimi i automatizuar: aktivizoni email-e, SMS ose njoftime të tjera të miratuara kur dërgesa arrin një gjendje të përcaktuar.
• Konsistenca e të dhënave: shndërroni etiketat e ndryshme të ngjarjeve të transportuesve në një numër më të vogël statusesh që dyqani juaj mund t’i përdorë në mënyrë të besueshme.

Përcaktoni këto rezultate para se të zgjidhni metodën e zbatimit. Një tracking API mund të ofrojë të dhëna për dërgesën, por nuk vendos automatikisht se cilat ngjarje meritojnë një njoftim për klientin ose si duhet të trajtojë dyqani juaj një problem me adresën.

Zgjidhni arkitekturën e duhur të integrimit

Një arkitekturë tipike ka katër shtresa: platformën e tregtisë, një shërbim integrimi, ofruesin e gjurmimit dhe përvojën e orientuar nga klienti. Shërbimi i integrimit mund të jetë një aplikacion backend, një sistem për menaxhimin e porosive ose një rrjedhë pune pa server. Mbajtja e kësaj logjike në server është zakonisht më e sigurt sesa vendosja e kredencialeve të API-së në kodin e shfletuesit.

Rrjedha bazë duket kështu:

1. Një porosi e paguar përmbushet dhe merr një numër gjurmimi dhe një transportues.
2. Backend-i juaj dërgon detajet e dërgesës te ofruesi i gjurmimit.
3. Ofruesi kthen një identifikues gjurmimi ose të dhëna gjurmimi sipas dizajnit të API-së së tij.
4. Sistemi juaj ruan referencën e ofruesit dhe i harton ngjarjet e dërgesës me statuset e brendshme.
5. Një proces i planifikuar përditësimi ose një njoftim i mbështetur për ngjarjet rifreskon dërgesën.
6. Dyqani juaj, faqja e porosisë, mjetet e mbështetjes dhe shërbimi i njoftimeve lexojnë nga të dhënat tuaja të normalizuara.

Mos bëni që çdo shikim faqeje të thërrasë transportuesin ose tracking API. Ky dizajn mund të krijojë përvoja të ngadalta për klientët, kërkesa të dyfishta, probleme me kufijtë e përdorimit dhe rezultate jokonsistente. Ruani gjendjen më të fundit të pranuar të gjurmimit në bazën tuaj të të dhënave dhe rifreskojeni përmes proceseve të kontrolluara në sfond ose mekanizmit të mbështetur të përditësimit nga ofruesi.

Konfirmoni dokumentacionin e ofruesit para kodimit

Para zbatimit, shqyrtoni dokumentacionin zyrtar të API-së së ofruesit për autentikimin, formatet e kërkesave, fushat e përgjigjeve, transportuesit e mbështetur, sjelljen ndaj gabimeve, mekanizmat e përditësimit dhe kërkesat e llogarisë. 17TRACK ofron një faqe të produktit Tracking API dhe dokumentacion për zhvilluesit. Trajtojini këto faqe si autoritetin për sjelljen aktuale të API-së, në vend që të mbështeteni te shembujt e kopjuar nga forumet ose udhëzuesit e vjetër të integrimit.

Ndërtoni një listë të shkurtër kërkesash nga dokumentacioni:

• Si lëshohen, ruhen, rrotullohen dhe revokohen kredencialet e API-së?
• A kërkon kërkesa një kod transportuesi apo shërbimi mund ta identifikojë transportuesin nga numri i gjurmimit?
• Cilat fusha të përgjigjes identifikojnë dërgesën, statusin, vendndodhjen, vulat kohore dhe mesazhin e përjashtimit?
• Si dorëzohen përditësimet asinkrone, nëse llogaria i mbështet?
• Cilat janë kufijtë e dokumentuar të kërkesave, rregullat e faturimit, pritshmëritë për skadimin dhe kodet e gabimeve?
• Si duhen trajtuar numrat e dyfishtë të gjurmimit, numrat e pavlefshëm, transportuesit e panjohur dhe dërgesat e dorëzuara?

Mos nxirrni përfundime për një veçori vetëm nga emri i produktit. Për shembull, “në kohë reale” mund të përshkruajë pozicionimin e produktit dhe jo një garanci që çdo ngjarje e transportuesit shfaqet menjëherë. Zbatimi juaj duhet të shpjegojë se skanimet e transportuesit mund të vonohen dhe se një API nuk mund të krijojë një skanim që transportuesi nuk e ka raportuar.

Përgatitni të dhënat e porosisë dhe dërgesës

Momenti më i dobishëm për të krijuar gjurmimin është normalisht përmbushja e dërgesës, jo krijimi i porosisë. Një porosi mund të jetë paguar, por ende të mos jetë paketuar, dhe një numër gjurmimi mund të gjenerohet para se paketa të pranohet nga transportuesi. Vendosni se cila ngjarje në rrjedhën tuaj të përmbushjes duhet të krijojë regjistrin e gjurmimit.

Së paku, regjistri juaj i brendshëm i dërgesës duhet të dallojë vlerat e mëposhtme:

• ID-në e brendshme të porosisë dhe ID-në e përmbushjes
• Numrin e gjurmimit
• Emrin ose kodin e transportuesit
• Shtetin ose rajonin e destinacionit, kur është e nevojshme operacionalisht
• ID-në e gjurmimit te ofruesi ose referencën e abonimit, nëse kthehet
• Statusin aktual të normalizuar
• Vulën kohore të ngjarjes së fundit dhe vulën kohore të sinkronizimit të fundit
• Përgjigjen bruto të ofruesit ose një referencë të kontrolluar auditimi

Mbajini të ndara të dhënat e porosisë dhe të dërgesës. Një porosi mund të përmbajë disa paketa, dërgesa të ndara ose transportues të ndryshëm. Supozimi se një porosi ka vetëm një numër gjurmimi shpesh dështon kur magazina i dërgon artikujt veçmas.

Përdorni një proces idempotent. Nëse sistemi i përmbushjes e riprovon të njëjtën kërkesë, integrimi duhet të përditësojë dërgesën ekzistuese në vend që të krijojë abonime ose mesazhe të dyfishta për klientin. Një çelës praktik idempotence mund të kombinojë ID-në tuaj të brendshme të përmbushjes, identifikuesin e transportuesit dhe numrin e gjurmimit, në varësi të kërkesave të vetë ofruesit.

Normalizoni statuset e transportuesve për klientët

Transportuesit përdorin etiketa dhe sekuenca të ndryshme ngjarjesh. Dyqani juaj duhet të mbajë një model të vogël të brendshëm statusesh, si Informacioni u pranua, Në tranzit, Në dorëzim, U dorëzua, Përjashtim dhe U kthye. Ruajeni ngjarjen origjinale të transportuesit për stafin e mbështetjes, por përdorni statusin e normalizuar për logjikën e dyqanit.

Rregullat e normalizimit duhet të jenë të qarta. Një ngjarje “etiketa u krijua” nuk duhet të paraqitet si provë se paketa po lëviz. “U dorëzua” duhet të trajtohet si ngjarje e raportuar nga transportuesi dhe jo si garanci që klienti e ka gjetur fizikisht paketën. Një përjashtim nuk duhet të shndërrohet në heshtje në “në tranzit” vetëm sepse dërgesa mund të vazhdojë më vonë.

Përcaktoni gjithashtu përparësinë e statuseve dhe trajtimin e regresioneve. Një furnizim i vonuar i të dhënave nga transportuesi mund të mbërrijë jashtë rendit. Krahasoni vulat kohore të ngjarjeve kur janë të disponueshme, regjistroni ngjarjen bruto dhe shmangni zëvendësimin e një gjendjeje më të re “u dorëzua” me një gjendje më të vjetër “në tranzit”. Nëse vulat kohore mungojnë ose janë të paqarta, shënojeni regjistrin për një përditësim të kujdesshëm në vend që të shpikni një sekuencë.

Ndërtoni rrjedhën e kërkesës nga ana e serverit

Backend-i juaj duhet të vërtetojë të dhënat hyrëse të përmbushjes para se të thërrasë ofruesin e gjurmimit. Kontrolloni që numri i gjurmimit të jetë i pranishëm, hiqni hapësirat e panevojshme, vërtetoni formatin e pritshëm kur është e përshtatshme dhe konfirmoni që vlera e transportuesit është e pranueshme. Mos refuzoni numra të pazakontë por të vlefshëm gjurmimi vetëm sepse nuk përputhen me një model të ngushtë lokal.

Një rrjedhë kërkesash e pavarur nga ofruesi mund të paraqitet kështu:

receive fulfillment event
validate order and shipment fields
check for an existing idempotency key
send the documented tracking request from the server
store the provider response and internal shipment record
queue a refresh or process the supported update event
publish only approved fields to the storefront

Përdorni skadime të shkurtra, riprovime të kufizuara dhe tërheqje eksponenciale për dështimet e përkohshme. Mos e riprovoni çdo gabim. Një dështim autentikimi, kërkesë e pavlefshme ose transportues i pambështetur zakonisht kërkon korrigjim dhe jo thirrje të përsëritura. Regjistroni një ID korrelacioni, rezultatin e kërkesës dhe kategorinë e gabimit të ofruesit, por shmangni shkrimin e çelësave të API-së, adresave të plota të klientëve ose të dhënave personale të panevojshme në regjistrat e aplikacionit.

Mbajeni përgjigjen e ofruesit të ndarë nga modeli i orientuar ndaj klientit. Kjo e bën më të lehtë ndryshimin e ofruesve, korrigjimin e rregullit të hartëzimit dhe kufizimin e informacionit të ekspozuar përmes një faqeje publike të porosisë.

Dizajnoni përvojën e gjurmimit për klientin

Një faqe gjurmimi duhet t’u përgjigjet shpejt tri pyetjeve: cila është gjendja aktuale, çfarë ndodhi së fundmi dhe çfarë duhet të bëjë më pas klienti? Shfaqni referencën e porosisë, numrin e dërgesës në një formë të kujdesshme ndaj privatësisë, emrin e transportuesit, kohën e ngjarjes së fundit dhe një shpjegim të qartë për përjashtimet.

Mos shfaqni një kronologji bosh sikur të ishte dështim teknik. Para skanimit të parë nga transportuesi, shpjegoni se informacioni i dërgesës është pranuar dhe se lëvizja mund të mos jetë ende e dukshme. Për një përjashtim, jepni një shpjegim në gjuhë të thjeshtë vetëm kur të dhënat burimore e mbështesin atë. Nëse transportuesi raporton një problem me adresën, lidhuni me procesin e mbështetjes ose veprimin e shërbimit ndaj klientit që biznesi juaj mund të ofrojë realisht.

Për dyqanet e ndërtuara në Shopify ose në një platformë tjetër tregtie, kontrolloni se si ekspozohen nga platforma ngjarjet e përmbushjes, llogaritë e klientëve, faqet e statusit të porosive dhe modelet e njoftimeve. Dokumentacioni zyrtar i zhvilluesve të Shopify përfshin burime për webhooks dhe të dhënat e përmbushjes. API-të e platformës dhe dokumentacioni me versione mund të ndryshojnë, ndaj konfirmoni versionin e përdorur nga aplikacioni juaj para punës në prodhim.

Përdorni njoftimet me kujdes

Ngjarjet e dërgesës janë nxitës të dobishëm, por dërgimi i një mesazhi për çdo skanim të transportuesit mund të krijojë lodhje nga njoftimet. Përcaktoni rregulla biznesi, si njoftimi për krijimin e dërgesës, përparimin domethënës në tranzit, dërgesën për dorëzim, dorëzimin dhe përjashtime të zgjedhura. Shtypni dublikatat dhe shtoni një interval minimal për mesazhet e përsëritura të vonesës.

Ndani sinjalizimet operacionale nga njoftimet për klientët. Një ekip mbështetjeje mund të ketë nevojë të dijë se një dërgesë nuk ka ndryshuar për disa ditë, ndërsa klienti mund të ketë nevojë për një mesazh vetëm kur transportuesi raporton një përjashtim konkret. Pragu kohor duhet të pasqyrojë nivelin e shërbimit, destinacionin, transportuesin dhe metodën e transportit, dhe jo një numër universal pa bazë operacionale.

Testoni me skenarë realë dorëzimi

Një përgjigje e suksesshme për një numër gjurmimi nuk mjafton për lançimin në prodhim. Krijoni një matricë testimi që përfshin transportues, shtete, lloje dërgesash dhe gjendje ngjarjesh të ndryshme. Testoni të paktën:

• Një dërgesë të sapokrijuar pa skanim nga transportuesi
• Një dërgesë normale në tranzit
• Një dërgesë për dorëzim
• Një dërgesë të dorëzuar
• Një ngjarje përjashtimi ose të lidhur me adresën
• Një dërgesë të kthyer
• Një numër të pavlefshëm gjurmimi
• Një ngjarje të dyfishtë përmbushjeje
• Një përgjigje të vonuar ose skadim të ofruesit
• Një ngjarje jashtë rendit

Matni më shumë se disponueshmërinë e API-së. Kontrolloni nëse përditësohet porosia e saktë, nëse klienti sheh gjuhë të kuptueshme, nëse njoftimet e dyfishta shtypen dhe nëse stafi i mbështetjes mund të identifikojë ngjarjen origjinale të transportuesit. Filloni fillimisht me një lançim të kufizuar, ruani një alternativë operacionale dhe monitoroni kategoritë e gabimeve pas publikimit.

Siguria, privatësia dhe mirëmbajtja

Ruajini kredencialet në një menaxhues sekretesh ose në një variabël mjedisi të mbrojtur, jo në kodin e temës, kodin celular, kontrollin e burimit ose kërkesat e shfletuesit. Kufizoni aksesin në të dhënat e dërgesave sipas rolit, përdorni HTTPS dhe shqyrtoni sa kohë ruhen përgjigjet bruto dhe fushat e lidhura me klientët.

Shqyrtoni rregullisht dokumentacionin e ofruesit dhe versionin e API-së së platformës suaj të tregtisë. Mbështetja e transportuesve, emrat e ngjarjeve, kërkesat e autentikimit dhe sjellja e webhook-eve të platformës mund të ndryshojnë. Mbajini të konfigurueshme rregullat e hartëzimit të statuseve, dokumentoni supozimet pas tyre dhe bëjeni të mundur riluajtjen ose rakordimin e një dërgese pa dërguar një mesazh tjetër për klientin.

API-ja e 17TRACK është një mundësi e përshtatshme për t’u vlerësuar kur dyqani juaj ka nevojë për një integrim të dedikuar gjurmimi ndërmjet transportuesve. Zgjedhja e përshtatshme ende varet nga transportuesit që përdorni, shtetet ku shërbeni, sjellja e përditësimeve e dokumentuar për llogarinë tuaj, vëllimi i pritshëm i kërkesave dhe kontrollet operacionale që kërkon ekipi juaj. Konfirmojini këto pika në dokumentacionin zyrtar dhe në një provë të kontrolluar të konceptit para se të angazhoheni për një dizajn prodhimi.

FAQ

A duhet të krijohet gjurmimi kur vendoset porosia?

Zakonisht jo. Krijoni ose aktivizoni regjistrin e dërgesës kur rrjedha juaj e përmbushjes ka një transportues dhe një numër gjurmimi. Krijimi i tij në arkë mund të prodhojë regjistra për porosi që anulohen, nuk përmbushen ose ndahen më vonë.

A mund të garantojë një tracking API informacion në kohë reale për dorëzimin?

Jo. Asnjë API nuk mund të garantojë që çdo skanim i transportuesit të jetë menjëherë i dukshëm. Ofruesi varet nga të dhënat e transportuesit dhe sistemet e transportuesve mund t’i raportojnë ngjarjet me vonesa ose boshllëqe. Paraqitini saktë vulat kohore dhe gjuhën e statusit dhe shmangni premtimin për një kohë të saktë rifreskimi, përveçse kur dokumentacioni përkatës dhe marrëveshja e shërbimit e mbështesin atë premtim.

A duhet ta thërrasë shfletuesi tracking API drejtpërdrejt?

Në shumicën e zbatimeve, jo. Përdorni një integrim nga ana e serverit në mënyrë që kredencialet të mbeten të mbrojtura, përgjigjet të mund të normalizohen, riprovimet të kontrollohen dhe të dhënat e orientuara ndaj klientit të filtrohen. Dyqani zakonisht duhet të lexojë një pamje të miratuar të dërgesës nga aplikacioni juaj.

Si duhet ta trajtojë një dyqan një porosi me disa paketa?

Modeloni çdo përmbushje ose paketë si një dërgesë të veçantë, duke ruajtur ID-në e porosisë prind. Faqja e porosisë mund të shfaqë një përmbledhje të përgjithshme dhe kronologji të veçanta për çdo paketë. Kjo shmang fshehjen e një pakete të vonuar pas statusit “u dorëzua” të një pakete tjetër.

Cili është metri i parë i prodhimit që duhet monitoruar?

Monitoroni të gjithë rrjedhën nga krijimi i përmbushjes deri te një përditësim i saktë dhe i dukshëm për klientin. Suksesi i API-së vetëm nuk mjafton. Ndiqni regjistrat e dyfishtë, dërgesat e vjetruara, ngjarjet e pahartuara, dështimet e njoftimeve dhe përqindjen e dërgesave që kërkojnë korrigjim manual.

Burimet

• 17TRACK Tracking API
• 17TRACK API Documentation
• Shopify Webhooks Documentation
• Shopify Fulfillment Object Documentation