Skip to main content
Ana səhifəBloqBələdçilərİnkişaf mühitində Tracking API inteqrasiyasının sınaqdan keçirilməsi: Sandbox, test nömrələri, saxta Webhook-lar

İnkişaf mühitində Tracking API inteqrasiyasının sınaqdan keçirilməsi: Sandbox, test nömrələri, saxta Webhook-lar

17TRACK

İnkişaf mühitində izləmə API inteqrasiyasını yoxlamaq üçün üç tamamlayıcı üsuldan istifadə edin: API davranışını yoxlamaq üçün provayderin sandbox mühiti və ya sənədləşdirilmiş test nömrələri, təkrarlana bilən göndəriş ssenariləri üçün lokal fixture-lər və qəbul edən endpoint-iniz üçün saxta webhook-lar. Daha sonra simulyasiyaların sübut edə bilmədiyi hissələri, o cümlədən etimadnamələri, abunə konfiqurasiyasını və faktiki hadisə çatdırılmasını yoxlamaq üçün nəzarətli canlı sınaq aparın.

İnkişaf Sandbox Test Nömrələrində İzləmə API İnteqrasiyasının Yoxlanılması

Bu təlimat göndəriş izləməsini ecommerce platformasına, sifariş idarəetmə sisteminə, ERP-yə və ya müştəri bildirişləri xidmətinə qoşan tərtibatçılar üçündür. Məqsəd sadəcə uğurlu API cavabı almaq deyil. Məqsəd təkrarlanan mesajlar, itirilmiş hadisələr və ya real müştərilərlə təsadüfi əlaqə olmadan izləmə yeniləmələrinin düzgün sifariş vəziyyəti yaratdığını sübut etməkdir.

Provayder davranışını tətbiq davranışından ayırın

İzləmə inteqrasiyasının ən azı iki sərhədi var: tətbiqinizin provayderə göndərdiyi sorğular və tətbiqinizin sonradan qəbul etdiyi və ya əldə etdiyi yeniləmələr. Birinci sərhəddə uğurlu sorğu ikinci sərhədin işlədiyini sübut etmir.

Sınaq planını bütün sistemi yoxlaması gözlənilən tək bir test izləmə nömrəsi ətrafında deyil, bu sərhədlər əsasında qurun.

Sınaq üsuluNəyi yoxlaya bilərTəkbaşına nəyi müəyyən edə bilməz
Provayder sandbox-ıProvayder tərəfindən təsvir edilən dəstəklənən sorğu formatları, autentifikasiya və simulyasiya edilmiş davranışİstehsal daşıyıcı məlumatlarının əlçatanlığı və ya istehsalda çatdırılma davranışı
Sənədləşdirilmiş test nömrələriHəmin nömrələrə təyin edilmiş konkret ssenarilərDigər statuslar, daşıyıcılar və ya webhook ardıcıllıqları
Lokal fixture-lər və API mock-larıParser-inizi, uyğunlaşdırma qaydalarınızı, saxlamanı və xətaların idarə edilməsiniReal provayderin sorğuları qəbul edib-etmədiyini və eyni payload-u göndərib-göndərmədiyini
Saxta webhook sorğularıEndpoint-in işlənməsini, yoxlamanı, dublikatların aradan qaldırılmasını və aşağı axın təsirləriniProvayder tərəfində callback konfiqurasiyasını və ya real çatdırılma təkrarlarını
Nəzarətli canlı sınaqReal bağlantını və müşahidə edilən göndəriş iş axınınıBütün nadir xətaları, istisnaları və ya çatdırılma ardıcıllıqlarını

Tövsiyə olunan yanaşma: lokal testləri deterministik edin, mövcud olduqda provayder tərəfindən dəstəklənən sınaqlardan istifadə edin və canlı göndərişləri sistemlər arasındakı əlaqəni təsdiqləmək üçün saxlayın.

Fixture-lər yazmazdan əvvəl provayder müqaviləsini təsdiqləyin

İstifadə etmək istədiyiniz API versiyası üçün rəsmi sənədlərlə başlayın. Əsas URL-i, autentifikasiya üsulunu, qeydiyyat tələblərini, cavab sxemini, webhook quraşdırmasını və sənədləşdirilmiş sınaq imkanlarını təsdiqləyin. Provayder API təklif etdiyi üçün ayrıca sandbox mühitinin mövcud olduğunu düşünməyin.

17TRACK inteqrasiyası üçün başlanğıc nöqtəsi kimi 17TRACK İzləmə API səhifəsindən və rəsmi API sənədlərindən istifadə edin. Provayderə xas nümunələr hazırlamazdan əvvəl tətbiq olunan sorğu və callback spesifikasiyalarını orada yoxlayın. Aşağıdakı nümunələr qəsdən tətbiqə məxsus fixture-lərdir və 17TRACK API sxemini təmsil etmir.

İnkişaf kodunu xarici hesaba qoşmazdan əvvəl bu sualları aydınlaşdırın:

  • İnkişaf və istehsal etimadnamələri ayrıdırmı və hər etimadnamə hansı mühitə giriş verir?
  • Sandbox callback-ləri dəstəkləyir, yoxsa yalnız sorğu-cavab sınağını?
  • Test nömrələri sənədləşdirilibmi və onlar dəqiq hansı nəticələri yaradır?
  • Qeydiyyatlar və ya digər test sorğuları hesab kvotasını azalda və ya daimi qeydlər yarada bilərmi?
  • Callback autentifikasiyası, təsdiqi, vaxt aşımı və təkrar cəhd qaydaları necə sənədləşdirilib?
  • İzləmə qeydiyyatını, göndərişi, daşıyıcını və callback hadisəsini hansı identifikatorlar əlaqələndirir?

Sınaq davranışı aydın şəkildə sənədləşdirilməyibsə, provayderdən bunu təsdiqləməsini istəyin. Bu arada öz emal məntiqinizi mock-larla sınaqdan keçirməyə davam edin. Təsdiqlənməmiş sandbox imkanı planlaşdırma qeyri-müəyyənliyidir, provayderdə belə imkanın olmadığına dəlil deyil.

Təcrid olunmuş inkişaf mühiti yaradın

Ayrı verilənlər bazasından və ya təcrid olunmuş tenant-dan, ayrıca sirrlərdən və sintetik sifarişlərdən istifadə edin. E-poçtları, SMS-ləri və digər bildirişləri test təyinatlarına və ya bildiriş sinkinə yönləndirin. Fixture-də “çatdırıldı” kimi işarələnmiş göndəriş real alıcıya mesaj göndərməməlidir.

Daxili qeydlərə və jurnallara açıq mühit göstəricisi əlavə edin. Provayder etimadnamələrini serverdə, mənbə kodundan kənarda saxlayın və sorğu qeydlərindən sirləri silin. Callback-lər üçün müvəqqəti ictimai giriş lazımdırsa, yalnız nəzərdə tutulan inkişaf marşrutunu açın və autentifikasiya nəzarətlərini qoruyun.

Hadisələr göndərməzdən əvvəl az sayda məlum sifariş yaradın. Bir sifarişə bağlı iki göndərişi və tətbiqiniz dəstəkləyirsə, müxtəlif daşıyıcı kontekstlərində eyni izləmə nömrəsi sətrini daxil edin. Bu hallar yalnız izləmə nömrəsinin həmişə unikal biznes qeydini müəyyən etdiyini düşünən fərziyyələri üzə çıxarır.

Hər testin gözlənilən təsirini əvvəlcədən müəyyən edin: göndəriş vəziyyəti, sifarişlə əlaqə, zaman xətti qeydləri, bildiriş sayı və audit qeydi. Bu, nümayişi keçə və ya uğursuz ola bilən assertion-a çevirir.

Test nömrələrindən yalnız sənədləşdirilmiş məqsədləri üçün istifadə edin

İzləmə nömrəsinin iki fərqli sınaq rolu var. O, qeydiyyatı yoxlamaq üçün giriş kimi istifadə oluna bilər və izləmə hadisələri yaradan göndərişi müəyyən edə bilər. Format yoxlamasından keçən nömrə mütləq faydalı hadisə tarixçəsi təqdim etmir.

Rəsmi test nömrələri mövcud olduqda

Hər nömrənin yanında provayderin bildirdiyi ssenarini qeyd edin. Çatdırılmış göndəriş üçün sənədləşdirilmiş nömrənin istisnanı, qaytarmanı və ya uğursuz çatdırılma cəhdini simulyasiya etdiyi düşünülməməlidir. Həmçinin nəticənin sabit olub-olmadığını, zamanla dəyişib-dəyişmədiyini və ya konkret daşıyıcı seçimi tələb edib-etmədiyini yoxlayın.

Bu nömrələri xüsusi inteqrasiya-test konfiqurasiyasında saxlayın. Onları unit test-lərə səpələməyin; xarici davranışın dəyişməsi əks halda deterministik testləri etibarsız edə bilər.

Rəsmi test nömrələri təsdiqlənmədikdə

Tətbiqiniz daxilində sintetik identifikatorlardan istifadə edin və provayder sərhədini mock edin. Heç vaxt inandırıcı görünən nömrə uydurub onun sınaq üçün ayrıldığını düşünməyin: bu, real göndərişə uyğun gələ bilər.

Canlı yoxlama üçün nəzarət etdiyiniz və girişinə icazəniz olan göndərişlərdən istifadə edin. İzləmə nömrələrini ictimai ekran görüntülərindən və ya müştəri yazışmalarından köçürməkdən çəkinin. Göndəriş tarixçələrini potensial həssas məlumat kimi qəbul edin, çünki onlar məkanları, vaxt göstəricilərini və çatdırılma məlumatlarını ehtiva edə bilər.

Köhnə çatdırılmış göndəriş parsing-i yoxlamağa kömək edə bilər, lakin davamlı inteqrasiya üçün zəif asılılıqdır. Tarixi məlumatların əlçatanlığı və xarici cavab dəyişə bilər. Təkrarlana bilən test üçün təmizlənmiş fixture saxlayın və canlı yoxlamanı ayrıca aparın.

Fixture-ləri mənalı göndəriş keçidləri ətrafında yaradın

Fixture-ləri sənədləşdirilmiş sxemdən və mövcud olduqda təmizlənmiş real cavablardan yaradın. Provayder payload fixture-lərini daxili normallaşdırılmış hadisə modelinizdən ayrı saxlayın. Aralarındakı adapteri yoxlayın ki, daxili mock pozulmuş provayder parser-ini gizlətməsin.

Faydalı başlanğıc dəstinə bu ssenarilər daxildir:

  • Hələ izləmə hadisəsi yoxdur: hərəkət və ya çatdırılma iddiası irəli sürmədən göndərişi saxlayın.
  • Tranzitdə: zaman xəttini yeniləyin və düzgün sifariş əlaqəsini qoruyun.
  • Çatdırılma üçün çıxıb: çatdırılmanı tamamlanmış hesab etmədən bildiriş siyasətinizi tətbiq edin.
  • Çatdırıldı: tamamlanmanı qeyd edin və nəzərdə tutulan biznes əməliyyatını bir dəfə yaradın.
  • İstisna və ya çatdırılma cəhdi: tamamlanmış çatdırılmadan fərqi qoruyun.
  • Qaytarılma hərəkəti: hər sonrakı skanı ilkin alıcıya doğru irəliləyiş kimi şərh etməyin.
  • Naməlum status: status uyğunlaşdırması uydurmadan diaqnostika üçün kifayət qədər məlumat saxlayın.

Bu ssenarilər üçün öz normallaşdırılmış adlarınızdan istifadə edin, sonra provayderin sənədləşdirilmiş dəyərlərini onlara açıq şəkildə uyğunlaşdırın. Müxtəlif API-lərin eyni status etiketlərindən istifadə etdiyini və ya etiketin hər yerdə eyni biznes mənasına malik olduğunu düşünməyin.

Məlumat formasını da dəyişin: boş hadisə siyahısı, çatışmayan məcburi olmayan sahələr, əlavə naməlum sahələr, Unicode məkan adları, saat qurşağı ofsetləri olan vaxt göstəriciləri və səhv formatlı məcburi dəyərlər. Parser uyğun əlavələrə dözməli, təhlükəsiz emal edilə bilməyən məlumatları isə rədd etməlidir.

Saxta webhook-ları real qəbul yolundan göndərin

Saxta webhook yalnız yekun status-yeniləmə funksiyasını çağırmamalı, qəbul marşrutunu, autentifikasiya middleware-ini, yoxlamanı, saxlama prosesini və worker emalını sınaqdan keçirməlidir.

Aşağıdakı payload sintetik daxili hadisəni təmsil edir. Sahə adları, hadisə ID-si və status nümunə xarakterlidir; bunlar provayder callback müqaviləsi deyil.

{
  "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"
}

Onu tracking-event.json kimi saxlayın və lokal test qəbuledicisinə göndərin:

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

Bu əmr yalnız lokal marşrutlaşdırmanı və emalı yoxlayır. Provayder autentifikasiyasını nümayiş etdirmir. İnkişafa məxsus marşrutu istehsalda əlçatmaz saxlayın və ya provayderin sənədləşdirilmiş autentifikasiya üsulu və ayrıca test sirri ilə istehsal qəbuledicisini yoxlayın.

İstehsal nəzarətlərini zəiflətmədən autentifikasiyanı yoxlayın

Provayder imzalanmış callback-lər müəyyən edirsə, təsadüfi imza başlığını və ya alqoritmi seçmək əvəzinə məhz həmin sxemi tətbiq edin. Sorğu baytlarını imzalayan sxemlərdə yoxlama üçün orijinal gövdəni saxlayın; JSON-un parse edilməsi və yenidən seriyalaşdırılması həmin baytları dəyişə bilər.

Tətbiq olunduqda düzgün autentifikasiyanı, çatışmayan etimadnamələri, dəyişdirilmiş gövdələri və səhv imzaları yoxlayın. Sənədləşdirilmiş sxem vaxt göstəricilərini və ya təkrar hücumdan qorunmanı ehtiva edirsə, həmin qaydaları da sınaqdan keçirin. HMAC standartlaşdırılmış mesaj autentifikasiyası konstruksiyasıdır, lakin onun mövcudluğu konkret izləmə provayderinin ondan istifadə etdiyini sübut etmir.

Dublikatları, ardıcıllığı və bərpanı yoxlayın

Eyni yeniləmə təkrar gəldikdə və ya hadisələr gözlənilməz ardıcıllıqda çatdıqda göndəriş emalı düzgün qalmalıdır. Bunlar müdafiə xarakterli test ssenariləridir və konkret provayderin çatdırılma zəmanəti barədə iddia deyil.

TestGözlənilən tətbiq davranışı
Eyni hadisəni iki dəfə göndərinBir məntiqi hadisə saxlayın və dublikat müştəri bildirişlərindən çəkinin.
Çatdırılmadan sonra daha köhnə tranzit skanı göndərinFaydalı tarixçəni qoruyun, lakin çatdırılmış vəziyyəti avtomatik geri çevirməyin.
Eyni vaxtda yeniləmələr göndərinParalel worker-lərə baxmayaraq ardıcıl vəziyyət keçidlərini tətbiq edin.
Davamlı qəbuldan sonra emalı dayandırınYeni callback tələb etmədən saxlanmış hadisəni bərpa edib emal edin.
Qəbul davamlı olmamışdan əvvəl saxlamanı uğursuz edinUğurlu qəbul barədə yanlış təsdiq göndərməyin.
Naməlum göndəriş göndərinMüəyyən edilmiş karantin və ya rədd siyasətinə əməl edin; sifariş əlaqəsini heç vaxt təxmin etməyin.

Dublikatların aradan qaldırılması üçün təqdim edildikdə sənədləşdirilmiş sabit hadisə identifikatoruna üstünlük verin. Əks halda müvafiq sahələr əsasında diqqətlə məhdudlaşdırılmış identiklik müəyyən edin və toqquşmaları yoxlayın. Təkcə izləmə nömrəsi hadisə identikliyi deyil, çünki bir göndəriş çoxsaylı qanuni yeniləmələr yarada bilər.

Hadisə tarixçəsini cari göndəriş proyeksiyasından ayırın. Tarixi skanların saxlanması hər gecikmiş skanın göstərilən statusu əvəz etməsini tələb etmir. “Ən yeni vaxt göstəricisindən istifadə et” də tam qayda deyil: düzəlişlər, qaytarılma axınları və müxtəlif vaxt mənaları açıq şəkildə idarə edilməlidir.

Asinxron emal üçün arxitekturanıza uyğun olaraq hadisə davamlı inbox qeydinə və ya davamlı növbəyə çatdıqdan sonra təsdiq göndərin. Provayderin sənədləşdirilmiş təsdiq tələblərinə əməl edin. HTTP status kodlarının mənasını müəyyən edir, lakin konkret göndəricinin təkrar cəhd cədvəli öz müqaviləsindən götürülməlidir.

Nəzarətli canlı yoxlama aparın və buraxılış meyarlarını müəyyən edin

Deterministik testlər keçdikdən sonra real inteqrasiya vasitəsilə icazəli göndərişi qeydiyyatdan keçirin və tam yolu təsdiqləyin. Provayderin nəzərdə tutulan qeydi qəbul etdiyini, callback konfiqurasiyasının düzgün mühitə yönəldiyini və daxil olan məlumatların gözlənilən göndərişə uyğunlaşdırıldığını yoxlayın.

Canlı yoxlama zamanı hər göndəriş statusunun görünməsini tələb etməyin. Real göndərişlər idarəolunan fixture-lər deyil. Canlı sınaqdan bağlantını və müşahidə edilən müqavilə uyğunluğunu yoxlamaq üçün, təkrarlana bilən fixture-lərdən isə nadir və dağıdıcı ssenariləri əhatə etmək üçün istifadə edin.

Buraxılışdan əvvəl aşağıdakı nəticələri tələb edin:

  • Sənədləşdirilmiş uğur və xəta cavabları, API paket əməliyyatlarını dəstəkləyirsə element səviyyəli xətalar da daxil olmaqla, idarə olunur.
  • İlk sorğu artıq uğurlu olmuş ola bildikdə vaxt aşımı kor-koranə yaradılma təkrarlarına səbəb olmur.
  • Dublikat hadisələr dublikat biznes əməliyyatları yarada bilmir.
  • Yanlış callback-lər göndəriş vəziyyətini dəyişə bilmir.
  • Worker xətaları hadisələri səssizcə itirmək əvəzinə bərpa edilə bilən vəziyyətdə saxlayır.
  • İnkişaf trafiki real müştərilərə bildiriş göndərə və ya istehsal sifarişlərini dəyişə bilmir.
  • Jurnallar sirləri açıqlamadan sorğuları, qəbul edilmiş hadisələri, emal nəticələrini və bildiriş cəhdlərini əlaqələndirir.

Qeyri-müəyyən sorğu, təkrarlanan callback və ya kəsilmiş worker-dən sonra sistemin necə bərpa olunduğunu izah edə bildikdə buraxılış hazırdır. Tək uğurlu izləmə sorğusu kifayət deyil.

FAQ

Sandbox olmadan izləmə inteqrasiyasını yoxlaya bilərəmmi?

Bəli. Çıxış API sərhədini mock edin, sənədləşdirilmiş callback fixture-lərini yenidən oynadın və normallaşdırma ilə biznes qaydalarınızı lokal olaraq yoxlayın. Sonra faktiki bağlantını təsdiqləmək üçün icazəli canlı göndərişdən istifadə edin. Bu, geniş əhatə təmin edir, lakin sənədləşdirilməmiş provayder davranışını təkrarlamır.

İzləmə sorğum niyə uğurlu olur, lakin heç bir hadisə qaytarmır?

Sorğunun qəbul edilməsi və izləmə məlumatlarının əlçatanlığı fərqli nəticələrdir. Provayderin cavab təfərrüatlarını, qeydiyyat tələblərini, daşıyıcı identifikasiyası qaydalarını və hadisəsiz göndərişlər üçün sənədləşdirilmiş davranışı yoxlayın. Boş zaman xəttini doldurmaq üçün hərəkət və ya çatdırılma məlumatı uydurmayın.

Uğurlu saxta webhook real webhook-ların gələcəyini sübut edirmi?

Xeyr. O, yalnız mock tərəfindən sınaqdan keçirilən yolu sübut edir. Real çatdırılma həmçinin provayder konfiqurasiyasından, ictimai əlçatanlıqdan, TLS-dən, autentifikasiyadan və faktiki callback müqaviləsindən asılıdır. Bunları provayder tərəfindən dəstəklənən test çatdırılması və ya icazəli canlı iş axını ilə yoxlayın.

Emal tamamlanmazdan əvvəl HTTP 200 qaytarmalıyam?

Provayderin sənədləşdirilmiş təsdiq müqaviləsinə əməl edin. Asinxron dizaynda davamlı qəbul edildikdən sonra təsdiq göndərin, daha sonra worker-də emal edin. Davamlı qəbuldan əvvəl uğur qaytarmaq proses dərhal sonra uğursuz olarsa hadisənin itirilməsinə səbəb ola bilər.

Müştəri bildirişlərini necə yoxlamalıyam?

Bütün inkişaf bildirişlərini nəzarət olunan sinkə göndərin. Təyinatı, şablonu, tetikleyici keçidi və göndəriş sayını assertion ilə yoxlayın. Eyni hadisəni yenidən oynadın və bir göndəriş yeniləməsinin təkrarlanan müştəri mesajları yaratmadığını yoxlamaq üçün worker təkrarlarını simulyasiya edin.

Mənbələr

  • 17TRACK Tracking API — izləmə API məhsulu üçün rəsmi başlanğıc nöqtəsi.
  • 17TRACK API sənədləri — provayderə xas inteqrasiya müqaviləsi üçün istinad; tətbiq olunan sınaq və callback tələblərini burada təsdiqləyin.
  • RFC 9110: HTTP Semantics — HTTP cavab semantikası və sorğuların təkrar göndərilməsi ilə bağlı mülahizələr.
  • RFC 2104: HMAC — callback təhlükəsizliyi təlimatında müzakirə olunan standartlaşdırılmış mesaj autentifikasiyası konstruksiyası.