Skip to main content
Faqja kryesoreBlogUdhëzues15 pyetje që duhet t’ia bëni ofruesit të API-së së gjurmimit përpara se të kaloni në prodhim

15 pyetje që duhet t’ia bëni ofruesit të API-së së gjurmimit përpara se të kaloni në prodhim

17TRACK

Para se të vendosni një API gjurmimi në prodhim, pyesni si trajton transportuesit dhe llojet tuaja reale të dërgesave, çfarë kuptimi kanë ngjarjet e tij, si mbërrijnë përditësimet dhe çfarë ndodh kur të dhënat ose integrimi dështojnë. 15 pyetjet më poshtë u japin ekipeve të inxhinierisë dhe operacioneve një mënyrë praktike për t'i testuar këto përgjigje përpara se klientët, agjentët e mbështetjes ose rrjedhat e automatizuara të varen prej tyre.

15 pyetje që duhet t'i bëni një ofruesi API gjurmimi përpara se të vazhdoni

Një demonstrim i suksesshëm nuk është test prodhimi. Përdorni një mostër përfaqësuese dërgesash, duke përfshirë pakot e vonuara, të kthyera dhe të vështira për t'u identifikuar. Për çdo përgjigje, kërkoni dokumentacion, një ngarkesë shembull ose një rezultat testi. Regjistroni çdo çështje të pazgjidhur së bashku me një përgjegjës dhe një datë vendimi, në vend që të supozoni se do të trajtohet pas lançimit.

Filloni me përshtatshmërinë e dërgesave dhe kuptimin e të dhënave

1. Cilat nga dërgesat tona reale mund t'i gjurmoni dhe çfarë do të thotë mbulimi?

Jepini ofruesit një mostër të transportuesve, shërbimeve, çifteve të origjinës dhe destinacionit dhe formateve të numrave të gjurmimit. Kërkojini të identifikojë cilat dërgesa mund të pranojë, cilët transportues mund t'i identifikojë automatikisht dhe ku duhet të jepni një kod transportuesi. Prania e një transportuesi në një listë nuk vërteton se çdo shërbim, dorëzim ndërmjet transportuesve ose lloj dërgese do të prodhojë ngjarjet që i nevojiten aplikacionit tuaj.

Testoni shembuj realë nga linjat me volum të lartë dhe rastet kufitare operacionale. Përfshini një dërgesë që ndryshon transportues gjatë transitit, nëse kjo ndodh në biznesin tuaj. Regjistroni nëse API-ja refuzon një dërgesë, e pranon pa gjetur ngjarje ose kthen ngjarje me detaje të kufizuara. Këto rezultate kërkojnë trajtim të ndryshëm në një sistem menaxhimi porosish.

2. Çfarë kërkohet për të regjistruar një dërgesë dhe si parandaloni regjistrimet e dyfishta?

Sqaroni identifikuesit e kërkuar, rregullat e përzgjedhjes së transportuesit, kohën e regjistrimit dhe përgjigjen ndaj një numri gjurmimi të pavlefshëm ose ende joaktiv. Pyesni nëse vetëm numri i gjurmimit mjafton për rastin tuaj të përdorimit apo nëse nevojiten të dhëna shtesë. Konfirmoni çfarë ndodh nëse e njëjta dërgesë dorëzohet dy herë, qoftë nga i njëjti sistem apo nga shërbime të veçanta.

Ndërtoni një rrjedhë të vetme regjistrimi me përgjegjësi të qartë: cili sistem i dërgon dërgesat, cili ruan identifikuesin e ofruesit dhe cili përsërit një dërgim të pasigurt. Nëse një kërkesë skadon pas përpunimit nga ofruesi, një përsëritje e pakushtëzuar nuk duhet të krijojë në heshtje një regjistrim të dytë ose njoftime të dyfishta në sistemet pasuese.

3. Çfarë kuptimi kanë statuset tuaja dhe a mund të kontrollojmë ngjarjet bazë të transportuesit?

Kërkoni një fjalor statusesh dhe ngjarje bazë përfaqësuese. Terma si në transit, në dorëzim, përjashtim, dorëzuar dhe kthyer janë përmbledhje të dobishme, por rregullat e biznesit tuaj mund të kërkojnë më shumë detaje. Përcaktoni nëse ofruesi jep përshkrimet origjinale të transportuesit krahas statuseve të standardizuara dhe si trajton një ngjarje që nuk përputhet qartë.

Jini dakord për modelin tuaj të brendshëm të statusit përpara lançimit. Në veçanti, vendosni se cila ngjarje mund të mbyllë një dërgesë, të shkaktojë një mesazh dorëzimi ose të nisë një rrjedhë pune për përjashtimet. Mos e trajtoni një etiketë të gjerë statusi si provë të një ngjarjeje të caktuar fizike, përveçse kur të dhënat bazë e mbështesin atë interpretim.

4. Cilat vula kohore dhe vendndodhje ofrohen dhe si duhet t'i interpretojmë?

Për çdo ngjarje, dalloni kohën kur transportuesi thotë se ka ndodhur nga koha kur ofruesi e ka marrë ose publikuar. Pyesni për zonat kohore, zhvendosjet që mungojnë, saktësinë e vendndodhjes dhe përditësimet që mbërrijnë pas ngjarjeve të mëvonshme. Një ngjarje e marrë së fundmi mund të përshkruajë një skanim më të vjetër; renditja vetëm sipas kohës së marrjes mund të krijojë një kronologji mashtruese.

Testoni ngarkesën kundrejt skemës së bazës së të dhënave dhe shfaqjes për klientët. Vendosni si të shfaqni një ngjarje kur zona e saj lokale kohore është e pasigurt dhe shmangni paraqitjen e një kohe ose vendndodhjeje të saktë dorëzimi nëse burimi nuk e jep.

5. Si përfaqësohen përjashtimet, kthimet dhe prova e dorëzimit?

Kërkoni shembuj të tentativave të dështuara të dorëzimit, ndalimeve doganore, problemeve me adresën, lëvizjeve të kthimit te dërguesi dhe dërgesave të dorëzuara. Pyesni cilat detaje standardizohen, cilat mbeten specifike për transportuesin dhe nëse konfirmimi i dorëzimit përfshin prova mbështetëse në rastet që ju interesojnë. Mos supozoni se statusi i dorëzuar përfshin emrin e marrësit, nënshkrimin, fotografinë ose prova të tjera.

Hartëzoni çdo përjashtim me një përgjegjës veprimi. Disa ngjarje kërkojnë shqyrtim nga mbështetja; të tjera nuk kërkojnë mesazh për klientin derisa të mbërrijnë më shumë të dhëna. Nëse prova e dorëzimit është e nevojshme për një rrjedhë pune mosmarrëveshjeje, bëjeni disponueshmërinë dhe formatin e saj një kriter të veçantë pranimi, jo një pjesë të nënkuptuar të mbulimit të gjurmimit.

Testoni si mbërrijnë përditësimet në sistemet tuaja

6. A i dërgoni përditësimet me webhook, polling apo të dyja dhe kur duhet të përdorim secilën?

Kërkoni modelin e dokumentuar të dërgimit, shembujt e ngarkesave, konfigurimin e abonimit dhe udhëzimet për rikuperimin e përditësimeve të humbura. Nëse ofrohen webhook-e, përcaktoni nëse njoftojnë për një dërgesë të ndryshuar, ofrojnë një pamje të plotë apo mbajnë një ngjarje individuale. Nëse polling kërkohet ose përdoret si alternativë, sqaroni modelin e duhur të kërkesave dhe mënyrën e identifikimit të regjistrimeve të ndryshuara.

Zgjidhni modelin bazuar në rrjedhën e punës. Një kronologji për klientët mund të tolerojë një vonesë tjetër përditësimi nga ajo e një radhe përjashtimesh. Arkitektura juaj nuk duhet të premtojë sinjalizime të menjëhershme vetëm sepse integrimi përdor webhook-e: transportuesi duhet së pari ta bëjë ngjarjen të disponueshme dhe çdo sistem pasues duhet ta përpunojë.

7. Çfarë ndodh kur njoftimet dublikohen, vonohen ose mbërrijnë jashtë rendit?

Pyesni nëse ofruesi përsërit dërgesat e pasuksesshme, për sa kohë dhe çfarë përgjigjeje pret nga endpoint-i juaj. Kërkoni një identifikues të qëndrueshëm të ngjarjes ose dërgesës, nëse ekziston. Më pas testoni të njëjtin njoftim dy herë, dërgoni një ngjarje më të vjetër pas një më të reje dhe ktheni përkohësisht një gabim nga endpoint-i juaj.

Marrësi juaj duhet të projektohet që të konfirmojë vetëm atë që ka pranuar në mënyrë të sigurt, të përpunojë përsëritjet pa dërguar sërish mesazhe për klientët dhe të rindërtojë një kronologji të saktë kur ngjarjet mbërrijnë jashtë rendit. Nëse një dizajn i propozuar varet nga dorëzimi saktësisht një herë i çdo njoftimi, sfidojeni këtë supozim përpara publikimit.

8. Si do ta masim freskinë e të dhënave dhe çfarë ndikon në të?

Pyesni çfarë mund të masë ofruesi në çdo fazë: kohën e ngjarjes së transportuesit, kohën e marrjes nga ofruesi dhe kohën e dërgimit në sistemin tuaj. Ndajini këto matje nga çdo angazhim që merr. Një boshllëk i gjatë midis lëvizjes fizike dhe përditësimit të aplikacionit tuaj mund të vijë nga burimi, nga përpunimi i ofruesit ose nga radha juaj.

Gjatë një piloti, matni këto boshllëqe për dërgesa përfaqësuese dhe hetoni rastet e veçuara. Vendosni pragje sinjalizimi sipas asaj që kërkon realisht rrjedha juaj e punës. Nëse një skanim i vonuar do të shkaktonte një mesazh të dëmshëm për klientin ose humbje të përshkallëzimit, përcaktoni një alternativë si etiketë të dhënash të vjetruara ose shqyrtim manual.

9. Si mbrohen kredencialet e API-së dhe kërkesat webhook?

Kërkoni dokumentacionin për autentikimin dhe menaxhimin e kredencialeve. Konfirmoni si lëshohen, kufizohen, rrotullohen dhe revokohen kredencialet; nëse kredencialet e testimit dhe prodhimit janë të ndara; dhe si një marrës webhook mund të verifikojë se një kërkesë është autentike. Pyesni gjithashtu se cilat mbrojtje janë të disponueshme kundër kërkesave webhook të ripërsëritura.

Le të shqyrtojë ekipi juaj i sigurisë zbatimin e propozuar, jo vetëm listën e veçorive të ofruesit. Mbajini sekretet jashtë kodit dhe regjistrave në anën e klientit, kufizoni qasjen në kredencialet e prodhimit dhe praktikoni rrotullimin e kredencialeve. Nëse aplikacioni juaj nuk mund të verifikojë një njoftim hyrës me mekanizmin e dokumentuar, kjo është pengesë për publikimin e një rrjedhe pune të bazuar në webhook.

10. Çfarë të dhënash dërgese dhe klienti ruani dhe ku shkojnë ato?

Renditni çdo fushë që do të dërgonte integrimi juaj, duke përfshirë numrat e gjurmimit, referencat e porosive, adresat, të dhënat e kontaktit dhe çdo metadata të personalizuar. Pyesni cilat fusha kërkohen, për sa kohë ruhen të dhënat dhe regjistrat, si funksionojnë kërkesat për fshirje dhe cilat rajone ose nënpërpunues janë të rëndësishëm për kërkesat e organizatës suaj. Merrni dokumentacion kontraktual ose sigurie aty ku kërkohet nga shqyrtimi juaj.

Minimizoni të dhënat që transmetoni. Një integrim gjurmimi nuk duhet të marrë informacione për klientët vetëm sepse është e leverdishme të kaloni një objekt të tërë porosie. Ekipet tuaja të privatësisë, ligjit dhe sigurisë duhet të vendosin nëse trajtimi i dokumentuar nga ofruesi përshtatet me tregjet ku operoni.

Planifikoni për dështimet dhe ndryshimet operacionale

11. Cilat janë kufijtë e frekuencës së kërkesave dhe si duhet të përgjigjen klientët ndaj gabimeve?

Pyesni për kufijtë sipas endpoint-it, kredencialit dhe mjedisit, së bashku me rregullat e njëkohshmërisë dhe sjelljen e rekomanduar të përsëritjeve. Dalloni një kërkesë të pavlefshme nga një problem i përkohshëm shërbimi dhe nga një kërkesë që është kufizuar për shkak të frekuencës. Për API-të HTTP, kuptimet e kodeve të statusit kanë rëndësi: RFC 6585 përcakton 429 për shumë kërkesa, ndërsa RFC 9110 përshkruan semantikën HTTP, duke përfshirë gabimet e serverit.

Llogaritni trafikun e pritshëm për ditët e zakonshme dhe kulmet, më pas testoni një klient që ngadalëson ritmin, vendos punën në radhë dhe sinjalizon dështimet e vazhdueshme. Konfirmoni nëse një shkrim i pasigurt mund të përsëritet në mënyrë të sigurt. Një politikë përsëritjeje që shumëfishon trafikun gjatë një ndërprerjeje mund ta vështirësojë rikuperimin.

12. Si komunikohen ndryshimet në skemë, status dhe integrimin me transportuesit?

Pyesni për versionimin e API-së, njoftimet e amortizimit, regjistrat e ndryshimeve dhe nëse fushat e ngjarjeve mund të shtohen pa ndryshuar versioni. Përshkrimet e transportuesve dhe sjellja e gjurmimit gjithashtu mund të ndryshojnë. Përcaktoni si komunikon ofruesi një ndryshim që prek një transportues ose rrugë të caktuar, në vend të të gjithë API-së.

Shkruani analizues tolerantë për fushat opsionale dhe vlerat e panjohura të statusit, por mos e shndërroni në heshtje një vlerë të panjohur në të dorëzuar ose të dështuar. Ruani mjaftueshëm detaje burimore për të diagnostikuar një hartëzim të ndryshuar. Caktoni dikë të shqyrtojë njoftimet e ofruesit dhe të përditësojë testet e integrimit përpara se ndryshimi të arrijë te klientët.

13. Çfarë mund të testojmë përpara prodhimit dhe sa ngushtë përputhet mjedisi i testimit me sjelljen reale?

Kërkoni qasje në dokumentacion, një mjedis testimi nëse ofrohet, përgjigje shembull dhe një mënyrë për të provuar shtigjet e gabimeve. Pyesni cilët skenarë simulohen dhe cilët kërkojnë dërgesa reale. Një sandbox mund të provojë se kodi juaj trajton një ngarkesë, por të thotë pak për plotësinë e ngjarjeve të transportuesit, kohën e përditësimeve ose përshtatshmërinë rajonale.

Kryeni dy lloje testesh: teste integrimi të përcaktueshme për analizimin, përsëritjet dhe sigurinë; dhe një pilot të kufizuar me dërgesa reale për sjelljen operacionale. Përfshini dërgime të dyfishta, një skadim të ofruesit, një skanim të vonuar, një kthim dhe një status të panjohur. Kërkoni miratimin si nga inxhinieria, ashtu edhe nga ekipi që do të trajtojë përjashtimet.

14. Cilat angazhime për mbështetje dhe incidente zbatohen kur gjurmimi ndalon së përditësuari?

Pyesni cilat kanale mbështetjeje janë të disponueshme për llogarinë tuaj, si raportohen incidentet dhe cilat angazhime kontraktuale të shërbimit—nëse ka—zbatohen për API-në ose dërgimin e njoftimeve. Sqaroni nëse angazhimi për disponueshmërinë mbulon endpoint-in e API-së, dërgimin e përditësimeve të gjurmimit apo të dyja. Ato nuk janë i njëjti rezultat operacional.

Vendosni procedurën tuaj: kush zbulon një dështim, kush kontakton ofruesin, kur përdoret polling-u ose një alternativë tjetër dhe çfarë shohin klientët ndërsa përditësimet vonohen. Kërkoni procesin për zgjidhjen e një problemi të të dhënave të një dërgese të caktuar, si dhe të një ndërprerjeje në të gjithë platformën. Testoni rrugën tuaj të përshkallëzimit përpara se t'ju nevojitet.

15. Si llogariten përdorimi dhe kostot dhe çfarë ndodh nëse largohemi?

Pyesni cilat veprime llogariten drejt faturimit ose kufijve të përdorimit: dërgimet, dërgesat e gjurmuara, kërkesat, njoftimet apo njësi tjetër. Konfirmoni si trajtohen regjistrimet e dyfishta, përsëritjet, dërgesat joaktive, tejkalimet dhe trafiku i testimit sipas marrëveshjes së propozuar. Merrni kushtet e zbatueshme me shkrim, në vend që të vlerësoni kostot nga një demonstrim API.

Planifikoni gjithashtu për përfundimin. Përcaktoni si mund të eksportoni historikun e dërgesave, për sa kohë mbetet e disponueshme qasja dhe çfarë ndodh me regjistrimet aktive të gjurmimit. Një plan i zbatueshëm daljeje nuk është parashikim se do të ndërroni ofruesin; është një mënyrë për të shmangur humbjen e dukshmërisë mbi dërgesat që janë tashmë në lëvizje.

Kthejini përgjigjet në një vendim për prodhimin

Një shqyrtim i dobishëm për daljen në përdorim duhet të ketë tre rezultate:

  • Rezultat i përshtatshmërisë së dërgesave: një mostër e testuar që tregon cilat regjistrime gjurmimi u pranuan dhe nëse ngjarjet e tyre mbështesin rrjedhat e synuara të punës për klientët dhe operacionet.
  • Rezultat i integrimit: trajtim i demonstruar i autentikimit, dublikimeve, përsëritjeve, ngjarjeve të vonuara, ndryshimeve të skemës dhe rikuperimit nga përditësimet e humbura.
  • Marrëveshje operimi: kufij të dokumentuar, kushte të trajtimit të të dhënave, kontakte mbështetjeje, supozime kostosh dhe përgjegjës për rreziqet e pazgjidhura.

17TRACK është një ofrues që mund të vlerësoni nëse një API gjurmimi me shumë transportues përshtatet me rastin tuaj të përdorimit; faqja e Tracking API dhe dokumentacioni i API-së janë pika nisjeje për kontrollimin e integrimit kundrejt këtyre pyetjeve. I njëjti standard duhet të zbatohet për çdo ofrues: dokumentacioni përcakton se si synohet të funksionojë një ndërfaqe, ndërsa testet tuaja me dërgesa përfaqësuese përcaktojnë nëse ajo funksionon për rrjedhën tuaj të punës në prodhim. Mos publikoni një njoftim për klientin ose automatizim për përjashtimet derisa të jenë vërtetuar ngjarjet që e shkaktojnë atë.

FAQ

A mjafton një test sandbox për të miratuar një API gjurmimi për prodhim?

Jo. Një sandbox mund të vërtetojë formatet e kërkesave dhe një pjesë të trajtimit të dështimeve, por nevojiten dërgesa reale për të vlerësuar ngjarjet specifike të transportuesit, kohën dhe dobishmërinë e të dhënave të përjashtimeve në linjat tuaja reale. Përdorini të dyja, me kritere të veçanta pranimi.

A duhet të përdorim webhook-e apo polling për përditësimet e gjurmimit?

Për të vendosur, përdorni opsionet e dokumentuara të dërgimit nga ofruesi dhe tolerancën e rrjedhës suaj të punës ndaj vonesave. Webhook-et mund të ulin nevojën për kontrolle të përsëritura kur mbështeten, por marrësi juaj ende ka nevojë për trajtimin e përsëritjeve dhe dublikimeve. Polling-u mund të jetë i përshtatshëm si metodë kryesore ose si rrugë rikuperimi, në varësi të kufijve të dokumentuar.

Cili është gabimi më i zakonshëm në hartëzimin e statuseve të gjurmimit?

Përdorimi i një statusi të gjerë si nxitës për një pretendim biznesi më specifik. Për shembull, vetëm etiketa e dorëzimit mund të mos japë provat e nevojshme për zgjidhjen e një mosmarrëveshjeje. Përcaktoni nxitësit duke përdorur detajet e ngjarjes bazë që ofruesi juaj i jep realisht.

Kush duhet ta miratojë integrimin përpara lançimit?

Inxhinieria duhet të miratojë besueshmërinë dhe sigurinë; operacionet ose mbështetja duhet të miratojnë dobishmërinë e ngjarjeve dhe rrjedhave të punës për përjashtimet; ndërsa përgjegjësit përkatës të privatësisë, ligjit dhe prokurimit duhet të shqyrtojnë trajtimin e të dhënave dhe kushtet tregtare. Caktoni një përgjegjës të emërtuar për çdo boshllëk që mbetet i hapur.

Burimet