API-yə təqdim etməzdən əvvəl izləmə nömrələrini necə yoxlamaq olar: riayət edilməli 7 qayda
İzləmə nömrəsini izləmə API-sinə göndərməzdən əvvəl onu mərhələli şəkildə yoxlayın: daxiletməni normallaşdırın, əsas strukturunu yoxlayın, daşıyıcı kontekstini təsdiqləyin, nəzarət cəmini yalnız daşıyıcı bunu sənədləşdiribsə tətbiq edin və açıq şəkildə təhlükəli və ya natamam dəyərləri rədd edin. Universal bir müntəzəm ifadəyə güvənməyin. İzləmə nömrələrinin formatları daşıyıcıya, xidmətə, ölkəyə və göndəriş növünə görə fərqlənir. Buna görə effektiv yoxlayıcı legitim, lakin tanış olmayan formatdan istifadə edən nömrələri bloklamadan yanlış sorğuların qarşısını almalıdır.
Bu təlimat göndəriş izləməsini sifarişlərin idarə edilməsi sisteminə, anbar iş axınına, müştəri portalına və ya elektron ticarət tətbiqinə inteqrasiya edən tərtibatçılar və əməliyyat komandaları üçün hazırlanıb. Məqsəd göndərişdən əvvəl bağlamanın mövcud olduğunu sübut etmək deyil. Sintaktik yoxlama ilə göndəriş statusunun yoxlanması ayrı mərhələlərdir.
Yoxlama nəyi təsdiqləyə bilər, nəyi isə təsdiqləyə bilməz
Göndərilməzdən əvvəl yoxlayıcı boş dəyər, təsadüfi boşluqlar, dəstəklənməyən simvollar, həddindən artıq uzunluq və ya izləmə nömrəsinin yanlış sahəyə yerləşdirilməsi kimi ümumi daxiletmə problemlərini müəyyən edə bilər. Daşıyıcı məlumdursa və format sənədləşdirilibsə, ehtimal olunan daşıyıcını da müəyyən edə bilər.
O, adətən nömrənin real göndərişə aid olduğunu, bağlamanın daşıyıcı tərəfindən qəbul edildiyini və ya nömrənin hazırda izlənə bildiyini təsdiqləyə bilməz. Bu suallar üçün daşıyıcının və ya izləmə platformasının sorğusu tələb olunur. Nömrə format yoxlamasından keçsə də, istifadə olunmamış, incə şəkildə səhv yazılmış, müddəti bitmiş və ya başqa xidmətlə əlaqələndirilmiş ola bilər.
Yeddi qayda
1. Mənasını dəyişmədən dəyəri normallaşdırın
İstifadəçilər və yuxarı axın sistemləri tez-tez əvvələ və ya sona boşluqlar, sətir keçidləri, bölünməz boşluqlar və ya formatlaşdırma simvolları əlavə edir. Yoxlamadan əvvəl bunları təhlükəsiz şəkildə normallaşdırın. Ümumi ilk addım ətrafdakı boşluqları silmək və çap olunmayan boşluqları adi boşluqlara çevirməkdir. Daşıyıcının sənədləşdirilmiş formatı daxili boşluqlara və ya defislərə icazə verirsə, API sorğusu üçün onları silmək, yoxsa göstərmək və audit üçün orijinal dəyəri saxlamaq barədə qərar verin.
Mümkün olduqda iki dəyər saxlayın: orijinal daxiletmə və kanonik dəyər. Orijinal dəyər dəstək komandalarına məlumat keyfiyyəti problemlərini araşdırmağa, kanonik dəyər isə yoxlama və göndərmə üçün kömək edir. İdentifikatorları dəyişdirə biləcək çevirmələrdən çəkinin. Müvafiq daşıyıcı və ya API sənədləri bunu açıq şəkildə dəstəkləmədikcə hərfləri avtomatik olaraq rəqəmlərə çevirməyin, qeyri-müəyyən simvolları əvəz etməyin və bütün durğu işarələrini silməyin.
Unicode ilə işlənməyə diqqət yetirmək lazımdır. Başqa əlifbadan olan vizual olaraq oxşar simvol ASCII hərfinə və ya rəqəminə bənzəsə də, API tərəfindən qəbul edilməyə bilər. Kanonik dəyəri seçilmiş inteqrasiyanın icazə verdiyi simvol dəsti ilə məhdudlaşdırmaq sonrakı mərhələlərdə çaşdırıcı xətaların qarşısını ala bilər.
2. Əsas struktur yoxlamalarından keçməyən dəyərləri rədd edin
Daşıyıcıya xas məntiqi tətbiq etməzdən əvvəl dəyərin mövcud və məntiqli olub-olmadığını yoxlayın. Faydalı yoxlamalara minimum və maksimum uzunluq, icazə verilən simvol sinifləri və dəyərin yalnız boşluqlardan və ya “N/A”, “TBD” və ya “test” kimi yer tutucudan ibarət olub-olmaması daxildir. Dəqiq məhdudiyyətlər API müqaviləsindən və ya daşıyıcı sənədlərindən götürülməlidir. Nümunələrin çoxu qısa olduğu üçün universal maksimum uydurmayın.
Struktur yoxlaması qəsdən mühafizəkar olmalıdır. Məsələn, yalnız rəqəmlərə icazə verən qayda etibarlı hərf-rəqəmli identifikatorları rədd edəcək. Sabit uzunluq tələb edən qayda xidmət variantlarını və ya beynəlxalq formatları rədd edə bilər. Aşkar səhvləri tutmaq üçün ümumi yoxlamalardan, daşıyıcı və xidmət məlum olduqda isə daha konkret yoxlamalardan istifadə edin.
Həmçinin tətbiq sərhədində məlumat tipini yoxlayın. İzləmə nömrəsi adətən tam ədəd kimi deyil, sətir kimi qəbul edilməlidir. Rəqəmsal çevirmə əvvəldəki sıfırları silə və sabit enli rəqəm tiplərindən istifadə edən sistemlərdə dəqiqlik problemləri yarada bilər. Təsdiqlənmiş normallaşdırmadan sonra dəyəri sətir kimi dəqiq saxlayın.
3. Yalnız nömrədən təxmin etmək əvəzinə daşıyıcı kontekstindən istifadə edin
Daşıyıcısı olmayan izləmə nömrəsi qeyri-müəyyən daxiletmədir. Müxtəlif daşıyıcılar üst-üstə düşən uzunluqlardan, prefikslərdən və ya simvol dəstlərindən istifadə edə bilər və bir daşıyıcı üçün məntiqli görünən format digəri üçün etibarsız ola bilər. Sifariş, etiket, anbar sistemi və ya satıcı hesabı daşıyıcını artıq müəyyən edirsə, API bunu dəstəklədiyi zaman həmin konteksti izləmə nömrəsi ilə birlikdə göndərin.
Daşıyıcı konteksti həm yoxlamanı, həm də yönləndirməni yaxşılaşdırır. Bu, tətbiqinizə müvafiq format qaydalarını seçməyə, yanlış uyğunluqları azaltmağa və xəta mesajlarını daha faydalı etməyə imkan verir. Həmçinin bir neçə daşıyıcı oxşar görünüşlü dəyəri qəbul edə bildikdə avtomatik aşkarlama nəticəsinin fakt kimi qəbul edilməsinin qarşısını alır.
Daşıyıcı məlum deyilsə, iki mərhələli yanaşmadan istifadə edin. Əvvəlcə ümumi təhlükəsizlik yoxlamalarını aparın. Sonra dəyəri yalnız daşıyıcının aşkarlanmasını açıq şəkildə dəstəkləyən API axını vasitəsilə göndərin və ya biznes prosesi təsdiqlənmiş daşıyıcı tələb etdikdə onu yoxlama növbəsinə yerləşdirin. Bu uyğunluq saxlanılmır və sənədləşdirilməyibsə, yalnız prefiksə əsasən daşıyıcını səssizcə təyin etməyin.
4. Nəzarət cəmlərini yalnız qayda sənədləşdirildikdə tətbiq edin
Bəzi identifikator sistemlərində yoxlama rəqəmlərindən istifadə olunur, lakin izləmə nömrələri vahid universal nəzarət cəmi standartı ilə tənzimlənmir. Nəzarət cəmi müəyyən transkripsiya səhvlərini aşkarlaya bilər, amma göndərişin mövcud olduğunu sübut etmir. Daha əhəmiyyətlisi, yanlış nəzarət cəmi alqoritminin tətbiqi etibarlı nömrələri rədd edə bilər.
Nəzarət cəmini yalnız müvafiq daşıyıcı, xidmət, etiket spesifikasiyası və ya API sənədləri alqoritmi və onun əhatə etdiyi giriş hissəsini müəyyən etdikdə tətbiq edin. Qaydanın versiyasını qeyd edin və onu rəsmi nümunələr üzərində sınaqdan keçirin. Etibarlı qayda yoxdursa, kiçik nümunədə müşahidə edilən nümunələrə əsasən təxmin etmək əvəzinə nəzarət cəmini keçin.
Nəzarət cəminin nəticəsini tam yoxlama qərarı kimi deyil, siqnallardan biri kimi qəbul edin. Qayda mötəbərdirsə, uğursuz yoxlama göndərişi bloklamağa əsas verə bilər. Uğurlu yoxlama isə dəyəri növbəti mərhələyə keçirməlidir, onu aktiv göndəriş kimi qeyd etməməlidir.
5. Format yoxlamasını API-yə uyğunluqdan ayırın
Dəyər düzgün formalaşdırılmış ola bilər, lakin çağırdığınız son nöqtə üçün yenə də uyğun olmaya bilər. Göndərilməzdən əvvəl API sənədlərində tələb olunan sahələri, qəbul edilən daşıyıcı identifikatorlarını, autentifikasiya tələblərini, sorğu məhdudiyyətlərini, təkrar sorğuların idarə edilməsini və xidmət növləri və ya təyinatlarla bağlı məhdudiyyətləri yoxlayın. Bunlar inteqrasiya qaydalarıdır, izləmə nömrəsi qaydaları deyil, lakin etibarlı identifikatorun uğurla işlənib-işlənməyəcəyini müəyyən edir.
17TRACK Tracking API sənədləri bu fərqin niyə vacib olduğunu göstərir: tərtibatçılar izləmə nömrəsinin görünüşünə əsasən sorğu uydurmaq əvəzinə platformanın sorğu modelinə və dəstəklənən inteqrasiya davranışına əməl etməlidirlər. Son nöqtə tələbləri və cavabların işlənməsi üçün cari sənədlərə 17TRACK API sənədləri ünvanında baxın.
Yoxlama xətalarını nəqliyyat və autentifikasiya xətalarından ayrı saxlayın. “İzləmə nömrəsi formatı etibarsızdır”, “naməlum daşıyıcı”, “sorğu limiti aşılıb” və “avtorizasiya uğursuz oldu” fərqli tədbirlər tələb edir. Vahid, ümumi “göndərmə uğursuz oldu” mesajı təkrar cəhdləri və əməliyyat hesabatlarını daha az etibarlı edir.
6. Məhdudlaşdırılmış daxiletmələr, dublikatların silinməsi və təhlükəsiz təkrar cəhdlərlə API-ni qoruyun
Yoxlama həm də əməliyyat təhlükəsizliyi tədbiridir. Təhlil etməzdən və ya jurnala yazmazdan əvvəl daxiletmə uzunluğunu məhdudlaşdırın. Nəzarət simvollarını və gözlənilməyən yük strukturlarını rədd edin. Səhv idxalın nəzarətsiz sorğu seli yaratmaması üçün öz tətbiq sərhədinizdə sürət məhdudiyyətləri tətbiq edin.
Biznes prosesi təkrar qeydiyyat tələb etmədikdə göndərilməzdən əvvəl dublikatları silin. Faydalı dublikat silmə açarına kanonik izləmə nömrəsi, daşıyıcı, hesab və göndəriş konteksti daxil ola bilər. Düzgün açar iş axınınızdan asılıdır; eyni identifikator bəzən müxtəlif xidmətlərdə və ya biznes qeydlərində təkrar istifadə edilə bilər. Buna görə nömrənin təkbaşına həmişə qlobal miqyasda unikal olduğunu düşünməyin.
Müvəqqəti xətalar üçün geriçəkilmə ilə məhdudlaşdırılmış təkrar cəhdlərdən istifadə edin və daimi yoxlama xətalarını təkrar göndərməyin. API və arxitekturanız dəstəklədikdə idempotentlik və ya göndəriş qeydi saxlayın. Sorğunu araşdırmaq üçün kifayət qədər məlumatı jurnala yazın, lakin giriş məlumatlarını, müştəri məlumatlarını və həssas göndəriş detallarını qoruyun. Yoxlayıcı təkrar uğursuzluqları azaltmalıdır, həddindən artıq jurnal yazmaqla ikinci təhlükəsizlik problemi yaratmamalıdır.
7. Göndərildikdən sonra nəticəni təsdiqləyin və yanlış müsbət nəticələri izləyin
Son qayda göndərilməzdən əvvəl yoxlamanı hökm deyil, keçid kimi qəbul etməkdir. Sorğu qəbul edildikdən sonra API cavabını yoxlayın və onun statusunu, sorğu identifikatorunu, daşıyıcı əlaqəsini və sənədləşdirilmiş xəta kodunu saxlayın. Platforma sorğunu qəbul edir, lakin hələ hərəkət hadisələrini qaytara bilmirsə, bu, etibarsız nömrədən çox emal gecikməsini göstərə bilər.
Həll olunmamış qalan nömrələr üçün sonrakı tədbirlər siyasəti müəyyən edin. Vaxt çərçivəsi daşıyıcıya, xidmətə, göndərişin mənşəyinə və müştəri xidməti siyasətinizə uyğun olmalıdır; nömrənin etibarsız olduğunu sübut edən universal müddət yoxdur. Daşıyıcısı çatışmayan, provayder xətaları təkrarlanan, ziddiyyətli daşıyıcı nəticələri olan və ya statusu sifariş qeydinə uyğun gəlməyən qeydləri eskalasiya edin.
Yanlış rədd və yanlış qəbul hallarını ölçün. Sərt müntəzəm ifadə düzgün formalaşdırılmamış göndərişləri azalda bilər, lakin legitim göndərişləri səhvən bloklaya bilər. Həddindən artıq icazəverici yoxlayıcı daha çox sorğunu qəbul edə, lakin sonrakı mərhələlərdə səs-küy yarada bilər. Uğursuz nümunələri daşıyıcı və xidmət üzrə nəzərdən keçirin, sənədləşdirilmiş qaydaları versiya nəzarəti ilə yeniləyin və dəyişiklikləri məxfiliyi qorunan, təmsilçi sınaq məlumat dəsti üzərində yoxlayın.
Praktik yoxlama ardıcıllığı
Davamlı saxlanıla bilən tətbiq aşağıdakı ardıcıllıqdan istifadə edə bilər:
- Sorğunun sətir dəyəri və etibarlı biznes qeydi ehtiva etdiyini yoxlayın.
- Orijinal daxiletməni saxlayın, sonra sənədləşdirilmiş kanonik forma yaradın.
- Boş dəyərləri, yer tutucuları, təhlükəli simvolları və sənədləşdirilmiş uzunluq aralığından kənar dəyərləri rədd edin.
- Daşıyıcını etibarlı sifariş məlumatlarından müəyyən edin və ya açıq şəkildə dəstəklənən aşkarlama axınından istifadə edin.
- Daşıyıcıya xas sintaksis və nəzarət cəmi qaydalarını yalnız mötəbər sənədlər dəstəklədikdə tətbiq edin.
- Son nöqtə tələblərini, dublikat vəziyyətini və təkrar cəhd üçün uyğunluğu yoxlayın.
- Göndərin, cavabı təsnif edin, nəticəni saxlayın və həll olunmamış qeydlər üçün sonrakı tədbir planlaşdırın.
Bu ardıcıllıq yoxlayıcını sınaqdan keçirməyi asanlaşdırır, çünki hər qərarın fərqli səbəbi olur. Həmçinin əməliyyat komandalarına vahid qeyri-şəffaf xəta əvəzinə tədbir görülə bilən uğursuzluq kateqoriyaları təqdim edir.
Tətbiq yoxlama siyahısı
- Əvvəldəki sıfırların qorunması üçün izləmə nömrələrini sətir kimi saxlayın.
- Audit vacib olduqda orijinal və kanonik dəyərləri ayrıca saxlayın.
- Daşıyıcı qaydalarını səpələnmiş sərt kodlaşdırılmış şərtlər kimi deyil, versiyalanmış konfiqurasiya kimi qoruyun.
- Hərfləri, rəqəmləri, defisləri, boşluqları, Unicode oxşarlarını, yer tutucuları və sərhəd uzunluqlarını sınaqdan keçirin.
- Mümkün olduqda etibarlı daşıyıcı kontekstindən istifadə edin.
- Uğurlu müntəzəm ifadə uyğunluğundan göndərişin mövcudluğunu nəticə kimi çıxarmayın.
- Daimi yoxlama xətalarını müvəqqəti API və ya şəbəkə xətalarından ayrıca təsnif edin.
- Format qaydalarını və ya sorğu məntiqini dəyişməzdən əvvəl provayder sənədlərini nəzərdən keçirin.
Tez-tez verilən suallar
Müntəzəm ifadə izləmə nömrəsini yoxlaya bilərmi?
Daşıyıcı və xidmət formatı məlumdursa, məhdud nümunəni yoxlaya bilər. Lakin nömrənin mövcud olduğunu, müəyyən göndərişə aid olduğunu və ya hazırda aktiv olduğunu sübut edə bilməz. Universal ifadə yanlış rədd və ya yanlış uyğunluqlar yaratmağa meyllidir.
Etibarsız görünən nömrə API-yə göndərilməlidirmi?
Açıq şəkildə boş, təhlükəli və ya struktur baxımından qeyri-mümkün dəyərlər adətən göndərilməzdən əvvəl dayandırılmalıdır. Tanış olmayan, lakin başqa cəhətdən təhlükəsiz format yalnız daxili təxminə uyğun gəlmədiyi üçün rədd edilməməlidir. Əvvəlcə daşıyıcının sənədlərini yoxlayın və ya dəstəklənən aşkarlama prosesindən istifadə edin.
Göndərişi təsdiqləmək üçün nəzarət cəmi kifayətdirmi?
Xeyr. Nəzarət cəmi tətbiq edilə bildikdə yalnız dəyərin riyazi qaydaya uyğun olub-olmadığını yoxlayır. Daşıyıcının nömrəni verdiyini və ya bağlamanın şəbəkəyə daxil olduğunu təsdiqləmir.
Daşıyıcı naməlum olduqda nə baş verməlidir?
Ümumi təhlükəsizlik yoxlamalarını aparın və mövcuddursa, daşıyıcının aşkarlanmasını açıq şəkildə dəstəkləyən API iş axınından istifadə edin. Əks halda daşıyıcını səssizcə təxmin etmək əvəzinə qeydi zənginləşdirmə və ya əl ilə yoxlama üçün saxlayın.
API xətaları necə idarə edilməlidir?
Onları səbəbinə görə təsnif edin. Səhv formalaşdırılmış daxiletməni və dəstəklənməyən daşıyıcı dəyərlərini düzəldin; müvəqqəti şəbəkə və ya provayder xətalarını məhdudiyyətlər və geriçəkilmə ilə təkrar edin; autentifikasiya və ya kvota xətalarını isə inteqrasiya sahibinə yönləndirin. Sirləri açıqlamadan diaqnostika üçün lazım olan cavab detallarını saxlayın.
Mənbələr
- 17TRACK API Sənədləri — izləmə API-si tərtibatçıları üçün sorğu və inteqrasiya təlimatları.
- 17TRACK İzləmə API-si — rəsmi məhsul məlumatları və API istifadə ssenariləri.
- USPS İzləmə — rəsmi daşıyıcı izləmə giriş nöqtəsi və müştəri təlimatı.
- UPS İzləmə — rəsmi daşıyıcı izləmə giriş nöqtəsi.


