Skip to main content
Faqja kryesoreBlogUdhëzuesTestimi i integrimit të API-së së gjurmimit në zhvillim: sandbox, numra testimi, webhook-e të simuluara

Testimi i integrimit të API-së së gjurmimit në zhvillim: sandbox, numra testimi, webhook-e të simuluara

17TRACK

Për të testuar një integrim të API-së së gjurmimit në zhvillim, përdorni tre metoda plotësuese: një sandbox të ofruesit ose numra testimi të dokumentuar për sjelljen e API-së, fixture lokale për skenarë të përsëritshëm dërgesash dhe webhook-e të simuluara për endpoint-in tuaj pranues. Më pas kryeni një kontroll të kontrolluar në mjedisin real për të vërtetuar pjesët që simulimet nuk mund t’i provojnë, duke përfshirë kredencialet, konfigurimin e abonimit dhe dërgimin real të ngjarjeve.

Testimi i një integrimi të API-së së gjurmimit në zhvillim: Sandbox dhe numrat e testimit

Ky udhëzues është për zhvilluesit që lidhin gjurmimin e dërgesave me një platformë ecommerce, sistem të menaxhimit të porosive, ERP ose shërbim njoftimesh për klientët. Qëllimi nuk është thjesht të merrni një përgjigje të suksesshme nga API-ja. Duhet të provoni se përditësimet e gjurmimit prodhojnë gjendjen e saktë të porosisë, pa mesazhe të dyfishta, ngjarje të humbura ose kontakt aksidental me klientë realë.

Ndani sjelljen e ofruesit nga sjellja e aplikacionit

Një integrim gjurmimi ka të paktën dy kufij: kërkesat që aplikacioni juaj i dërgon ofruesit dhe përditësimet që aplikacioni juaj merr ose i merr më pas. Një kërkesë e suksesshme në kufirin e parë nuk dëshmon se kufiri i dytë funksionon.

Ndërtoni planin e testimit rreth këtyre kufijve, në vend që të prisni që një numër i vetëm testimi të ushtrojë të gjithë sistemin.

Metoda e testimitÇfarë mund të vërtetojëÇfarë nuk mund të vërtetojë e vetme
Sandbox i ofruesitFormatet e mbështetura të kërkesave, autentikimin dhe sjelljen e simuluar të përshkruar nga ofruesiDisponueshmërinë e të dhënave të transportuesve në prodhim ose sjelljen e dërgimit në prodhim
Numrat e dokumentuar të testimitSkenarët specifikë të caktuar për këta numraStatuset, transportuesit ose sekuencat e tjera të webhook-eve
Fixture lokale dhe mock-e të API-sëParser-in, rregullat e hartëzimit, ruajtjen dhe trajtimin e dështimeveNëse ofruesi real pranon kërkesat ose dërgon të njëjtin payload
Kërkesa të simuluara webhookTrajtimin e endpoint-it, validimin, eliminimin e dublikatave dhe efektet pasueseKonfigurimin e callback-ut nga ana e ofruesit ose riprovimet reale të dërgimit
Test i kontrolluar në mjedisin realLidhjen reale dhe rrjedhën e vëzhguar të dërgesësÇdo gabim, përjashtim ose sekuencë të rrallë dërgimi

Qasja e rekomanduar: bëjini testet lokale deterministe, përdorni testimin e mbështetur nga ofruesi kur është i disponueshëm dhe rezervoni dërgesat reale për konfirmimin e lidhjes midis sistemeve.

Konfirmoni kontratën e ofruesit para krijimit të fixture-ve

Filloni me dokumentacionin zyrtar për versionin e API-së që synoni të përdorni. Konfirmoni URL-në bazë, metodën e autentikimit, kërkesat e regjistrimit, skemën e përgjigjes, konfigurimin e webhook-ut dhe çdo mundësi testimi të dokumentuar. Mos supozoni se ekziston një sandbox i veçantë vetëm sepse ofruesi ofron një API.

Për një integrim me 17TRACK, përdorni faqen e API-së së gjurmimit të 17TRACK dhe dokumentacionin zyrtar të API-së si pika fillestare. Verifikoni atje specifikimet e zbatueshme të kërkesave dhe callback-eve para se të ndërtoni shembuj specifikë për ofruesin. Shembujt më poshtë janë qëllimisht fixture të zotëruara nga aplikacioni dhe nuk përfaqësojnë skemën e API-së së 17TRACK.

Zgjidhni këto pyetje para se të lidhni kodin e zhvillimit me një llogari të jashtme:

  • A janë kredencialet e zhvillimit dhe prodhimit të ndara dhe në cilin mjedis jep akses secili kredencial?
  • A mbështet sandbox-i callback-e apo vetëm testimin kërkesë-përgjigje?
  • A janë të dokumentuar numrat e testimit dhe çfarë rezultatesh të sakta prodhojnë?
  • A mund të konsumojnë regjistrimet ose kërkesat e tjera të testimit kuotën e llogarisë ose të krijojnë regjistrime të përhershme?
  • Cilat janë rregullat e dokumentuara për autentikimin e callback-ut, konfirmimin, afatin e pritjes dhe riprovimin?
  • Cilët identifikues lidhin një regjistrim gjurmimi, dërgesë, transportues dhe ngjarje callback-u?

Nëse sjellja e testimit nuk është dokumentuar qartë, kërkojini ofruesit ta konfirmojë. Ndërkohë, vazhdoni të testoni logjikën tuaj të përpunimit me mock-e. Një aftësi e pakonfirmuar e sandbox-it është një pasiguri planifikimi, jo dëshmi se ofruesi nuk e ka atë aftësi.

Ndërtoni një mjedis të izoluar zhvillimi

Përdorni një bazë të dhënash të veçantë ose tenant të izoluar, sekrete të veçanta dhe porosi sintetike. Drejtojini email-et, mesazhet SMS dhe njoftimet e tjera te destinacione testimi ose te një sink njoftimesh. Një dërgesë e shënuar si e dorëzuar në një fixture nuk duhet të shkaktojë mesazh për një blerës real.

Shtoni një shënues të qartë të mjedisit në regjistrimet dhe log-et e brendshme. Mbajini kredencialet e ofruesit në server, jashtë kontrollit të burimit, dhe maskoni sekretet nga kapjet e kërkesave. Nëse nevojitet akses publik i përkohshëm për callback-e, ekspozoni vetëm rrugën e synuar të zhvillimit dhe ruani kontrollet e saj të autentikimit.

Krijoni një grup të vogël porosish të njohura para se të dërgoni ngjarje. Përfshini dy dërgesa të lidhura me një porosi dhe, nëse aplikacioni juaj e mbështet, të njëjtin varg numri gjurmimi nën kontekste të ndryshme transportuesish. Këto raste zbulojnë supozimet se një numër gjurmimi i vetëm identifikon gjithmonë një regjistrim unik biznesi.

Përcaktoni paraprakisht efektin e pritshëm të çdo testi: gjendjen e dërgesës, lidhjen me porosinë, hyrjet në kronologji, numrin e njoftimeve dhe regjistrimin e auditimit. Kjo e shndërron demonstrimin në një pohim që mund të kalojë ose të dështojë.

Përdorni numrat e testimit vetëm për qëllimin e dokumentuar

Një numër gjurmimi ka dy role të dallueshme testimi. Mund të jetë një hyrje e përdorur për të vërtetuar regjistrimin dhe mund të identifikojë një dërgesë që prodhon ngjarje gjurmimi. Një numër që kalon validimin e formatit nuk siguron domosdoshmërisht një histori të dobishme ngjarjesh.

Kur janë të disponueshëm numrat zyrtarë të testimit

Regjistroni skenarin e deklaruar nga ofruesi pranë çdo numri. Një numër i dokumentuar për një dërgesë të dorëzuar nuk duhet të supozohet se simulon një përjashtim, kthim ose përpjekje të dështuar dorëzimi. Kontrolloni gjithashtu nëse rezultati i tij është fiks, ndryshon me kalimin e kohës ose kërkon zgjedhjen e një transportuesi të caktuar.

Mbajini këta numra në një konfigurim të dedikuar për testet e integrimit. Mos i shpërndani nëpër testet njësi, ku ndryshimi i sjelljes së jashtme mund t’i bëjë testet ndryshe deterministe jo të besueshme.

Kur numrat zyrtarë të testimit nuk janë konfirmuar

Përdorni identifikues sintetikë brenda aplikacionit tuaj dhe simuloni kufirin e ofruesit. Mos shpikni kurrë një numër që duket i besueshëm dhe supozoni se është rezervuar për testim: ai mund të përputhet me një dërgesë reale.

Për validimin real, përdorni dërgesa që kontrolloni dhe për të cilat jeni të autorizuar të keni akses. Shmangni kopjimin e numrave të gjurmimit nga pamje publike ose biseda me klientë. Trajtojini historitë e dërgesave si potencialisht të ndjeshme, sepse mund të përmbajnë vendndodhje, vula kohore dhe informacion dorëzimi.

Një dërgesë e vjetër e dorëzuar mund të ndihmojë në validimin e analizimit, por është një varësi e dobët për integrimin e vazhdueshëm. Disponueshmëria e të dhënave historike dhe përgjigjja e jashtme mund të ndryshojnë. Ruani një fixture të pastruar për teste të përsëritshme dhe mbajeni kontrollin real të ndarë.

Krijoni fixture rreth tranzicioneve kuptimplota të dërgesës

Ndërtoni fixture nga skema e dokumentuar dhe, kur është e disponueshme, nga përgjigje reale të pastruara. Mbajini fixture-t e payload-eve të ofruesit të ndara nga modeli juaj i brendshëm i normalizuar të ngjarjeve. Testoni përshtatësin midis tyre në mënyrë që një mock i brendshëm të mos fshehë një parser të prishur të ofruesit.

Një grup fillestar i dobishëm mbulon këta skenarë:

  • Ende pa ngjarje gjurmimi: ruajeni dërgesën pa pretenduar lëvizje ose dorëzim.
  • Në tranzit: përditësoni kronologjinë dhe ruani lidhjen e saktë me porosinë.
  • Në dalje për dorëzim: zbatoni politikën tuaj të njoftimeve pa e trajtuar dorëzimin si të përfunduar.
  • E dorëzuar: regjistroni përfundimin dhe lëshoni veprimin e synuar të biznesit vetëm një herë.
  • Përjashtim ose përpjekje dorëzimi: ruani dallimin nga një dorëzim i përfunduar.
  • Lëvizje kthimi: shmangni interpretimin e çdo skanimi të mëvonshëm si përparim drejt marrësit fillestar.
  • Status i panjohur: ruani informacion të mjaftueshëm për diagnostikim pa shpikur një hartëzim statusi.

Përdorni emrat tuaj të normalizuar për këta skenarë dhe më pas hartëzoni qartë vlerat e dokumentuara të ofruesit drejt tyre. Mos supozoni se API të ndryshme përdorin të njëjtat etiketa statusi ose se një etiketë ka të njëjtin kuptim biznesi kudo.

Ndryshoni gjithashtu formën e të dhënave: listë bosh ngjarjesh, fusha opsionale që mungojnë, fusha shtesë të panjohura, emra vendndodhjesh Unicode, vula kohore me zhvendosje të zonës kohore dhe vlera të detyrueshme të keqformuara. Parser-i juaj duhet të tolerojë shtesa të përputhshme, ndërsa të refuzojë të dhënat që nuk mund të përpunohen në mënyrë të sigurt.

Dërgoni webhook-e të simuluara përmes rrugës reale pranuese

Një webhook i simuluar duhet të ushtrojë rrugën pranuese, middleware-in e autentikimit, validimin, ruajtjen dhe përpunimin nga worker-i — jo thjesht të thërrasë funksionin përfundimtar të përditësimit të statusit.

Payload-i vijues përfaqëson një ngjarje të brendshme sintetike. Emrat e fushave, ID-ja e ngjarjes dhe statusi janë ilustrues; ato nuk janë kontratë callback-u të ofruesit.

{
  "event_id": "dev-event-001",
  "shipment_id": "dev-shipment-001",
  "tracking_number": "INTERNAL-TEST-001",
  "status": "in_transit",
  "occurred_at": "2025-01-15T10:00:00Z"
}

Ruajeni si tracking-event.json dhe dërgojeni te një pranues lokal testimi:

curl --request POST \
  http://localhost:3000/dev/tracking-events \
  --header 'Content-Type: application/json' \
  --data-binary @tracking-event.json

Kjo komandë validon vetëm rrugëzimin dhe trajtimin lokal. Ajo nuk demonstron autentikimin e ofruesit. Mbajeni një rrugë vetëm për zhvillim të paarritshme në prodhim ose testoni pranuesin e prodhimit duke përdorur metodën e dokumentuar të autentikimit të ofruesit dhe një sekret të veçantë testimi.

Testoni autentikimin pa dobësuar kontrollet e prodhimit

Nëse ofruesi specifikon callback-e të nënshkruara, zbatoni pikërisht atë skemë në vend që të zgjidhni një header ose algoritëm arbitrar nënshkrimi. Për skemat që nënshkruajnë bajtet e kërkesës, ruani trupin origjinal për verifikim; analizimi dhe serializimi i ri i JSON-it mund t’i ndryshojë ato bajte.

Testoni autentikimin e vlefshëm, kredencialet që mungojnë, trupat e manipuluar dhe nënshkrimet e pasakta kur është e zbatueshme. Nëse skema e dokumentuar përfshin vula kohore ose mbrojtje kundër riprodhimit, testoni edhe këto rregulla. HMAC është një ndërtim i standardizuar për autentikimin e mesazheve, por ekzistenca e tij nuk dëshmon se një ofrues i caktuar gjurmimi e përdor.

Testoni dublikatat, renditjen dhe rikuperimin

Përpunimi i dërgesave duhet të mbetet i saktë kur i njëjti përditësim mbërrin përsëri ose kur ngjarjet mbërrijnë në një renditje të papritur. Këto janë skenarë testimi mbrojtës, jo pohime për garancinë e dërgimit të një ofruesi të caktuar.

TestiSjellja e pritshme e aplikacionit
Dërgoni të njëjtën ngjarje dy herëMbani një ngjarje logjike dhe shmangni njoftimet e dyfishta për klientin.
Dërgoni një skanim më të vjetër tranziti pas dorëzimitRuani historinë e dobishme pa e kthyer automatikisht gjendjen e dorëzuar.
Dërgoni përditësime të njëkohshmeAplikoni tranzicione të qëndrueshme të gjendjes pavarësisht worker-ëve njëkohësisht.
Ndaloni përpunimin pas pranimit të qëndrueshëmRikuperoni dhe përpunoni ngjarjen e ruajtur pa kërkuar një callback të ri.
Dështoni në ruajtje para se pranimi të jetë i qëndrueshëmMos konfirmoni në mënyrë të rreme pranimin e suksesshëm.
Dërgoni një dërgesë të panjohurNdiqni një politikë të përcaktuar karantine ose refuzimi; mos e hamendësoni kurrë lidhjen me porosinë.

Preferoni një identifikues të dokumentuar dhe të qëndrueshëm të ngjarjes për eliminimin e dublikatave kur ofrohet. Përndryshe, përcaktoni një identitet të kufizuar me kujdes nga fushat përkatëse dhe testoni përplasjet. Një numër gjurmimi më vete nuk është identitet ngjarjeje, sepse një dërgesë mund të gjenerojë shumë përditësime legjitime.

Ndajeni historinë e ngjarjeve nga projek­sioni aktual i dërgesës. Mbajtja e skanimeve historike nuk kërkon që çdo skanim i mbërritur me vonesë të mbishkruajë statusin e shfaqur. As rregulli “përdor vulën kohore më të re” nuk është i plotë: korrigjimet, rrjedhat e kthimit dhe kuptimet e ndryshme të vulave kohore kërkojnë trajtim të qartë.

Për përpunimin asinkron, konfirmoni vetëm pasi ngjarja të arrijë një pikë të qëndrueshme dorëzimi, si një regjistrim inbox të konfirmuar ose një radhë të qëndrueshme, sipas arkitekturës suaj. Ndiqni kërkesat e dokumentuara të ofruesit për konfirmim. HTTP përcakton semantikën e kodeve të statusit, por orari i riprovimeve të një dërguesi të caktuar duhet të vijë nga kontrata e tij.

Kryeni një kontroll të kontrolluar real dhe përcaktoni kriteret e lëshimit

Pasi testet deterministe të kalojnë, regjistroni një dërgesë të autorizuar përmes integrimit real dhe konfirmoni rrugën e plotë. Kontrolloni që ofruesi pranoi regjistrimin e synuar, konfigurimi i callback-ut tregon mjedisin e duhur dhe të dhënat hyrëse hartëzohen te dërgesa e pritshme.

Mos kërkoni që çdo status dërgese të shfaqet gjatë atij kontrolli real. Dërgesat reale nuk janë fixture të kontrollueshme. Përdoreni ekzekutimin real për të validuar lidhjen dhe përputhshmërinë e vëzhguar me kontratën; përdorni fixture të riprodhueshme për të mbuluar skenarët e rrallë ose shkatërrues.

Para lëshimit, kërkoni rezultatet e mëposhtme:

  • Përgjigjet e dokumentuara të suksesit dhe gabimit trajtohen, duke përfshirë dështimet në nivel artikulli nëse API-ja mbështet operacione në grup.
  • Afatet e pritjes nuk shkaktojnë riprovime të verbra krijimi kur kërkesa e parë mund të ketë pasur sukses.
  • Ngjarjet e dyfishta nuk mund të krijojnë veprime të dyfishta biznesi.
  • Callback-et e pavlefshme nuk mund të ndryshojnë gjendjen e dërgesës.
  • Dështimet e worker-it lënë ngjarje të rikuperueshme në vend që t’i humbin në heshtje.
  • Trafiku i zhvillimit nuk mund të njoftojë klientë realë ose të ndryshojë porosi prodhimi.
  • Log-et lidhin kërkesat, ngjarjet e marra, rezultatet e përpunimit dhe përpjekjet e njoftimit pa ekspozuar sekretet.

Një lëshim është gati kur mund të shpjegoni si rrjedhën normale, ashtu edhe mënyrën se si sistemi rikuperohet pas një kërkese të pasigurt, callback-u të përsëritur ose worker-i të ndërprerë. Një kërkim i vetëm i suksesshëm gjurmimi nuk mjafton.

Pyetje të shpeshta

A mund ta testoj një integrim gjurmimi pa sandbox?

Po. Simuloni kufirin e API-së dalëse, riprodhoni fixture të dokumentuara callback-esh dhe testoni lokalisht normalizimin dhe rregullat e biznesit. Më pas përdorni një dërgesë reale të autorizuar për të konfirmuar lidhjen aktuale. Kjo siguron mbulim të konsiderueshëm, por nuk riprodhon sjelljen e padokumentuar të ofruesit.

Pse kërkesa ime e gjurmimit ka sukses, por nuk kthen ngjarje?

Pranimi i kërkesës dhe disponueshmëria e të dhënave të gjurmimit janë rezultate të ndryshme. Kontrolloni detajet e përgjigjes së ofruesit, kërkesat e regjistrimit, rregullat e identifikimit të transportuesit dhe sjelljen e dokumentuar për dërgesat pa ngjarje. Mos shpikni informacion lëvizjeje ose dorëzimi për të mbushur një kronologji bosh.

A dëshmon një webhook i simuluar i suksesshëm se webhook-et reale do të mbërrijnë?

Jo. Ai dëshmon vetëm rrugën e ushtruar nga simulimi. Dërgimi real varet gjithashtu nga konfigurimi i ofruesit, arritshmëria publike, TLS-ja, autentikimi dhe kontrata aktuale e callback-ut. Vërtetojini këto me një dërgim testimi të mbështetur nga ofruesi ose me një rrjedhë reale të autorizuar.

A duhet të kthej HTTP 200 para se përpunimi të përfundojë?

Ndiqni kontratën e dokumentuar të konfirmimit të ofruesit. Në një dizajn asinkron, konfirmoni pas pranimit të qëndrueshëm dhe më pas përpunojeni në një worker. Kthimi i suksesit para pranimit të qëndrueshëm mund të humbasë një ngjarje nëse procesi dështon menjëherë më pas.

Si duhet t’i testoj njoftimet e klientëve?

Dërgojini të gjitha njoftimet e zhvillimit te një sink i kontrolluar. Verifikoni destinacionin, modelin, tranzicionin shkaktues dhe numrin e dërgimeve. Riprodhoni të njëjtën ngjarje dhe simuloni riprovimet e worker-it për të vërtetuar se një përditësim dërgese nuk gjeneron mesazhe të përsëritura për klientin.

Burimet