İzləmə API-si hansı məlumatları qaytarmalıdır? Cari statusdan əlavə 12 sahə?
İzləmə API-si “Yoldadır” kimi yalnız bir etiketdən daha çoxunu qaytarmalıdır. Cari statusdan əlavə, göndəriş identifikatorlarını, daşıyıcının kimliyini, ətraflı status məlumatlarını, daşıyıcının ilkin mesajlarını, hadisə tarixçəsini, hadisə vaxtlarını, məkanları, təxmini çatdırılma məlumatlarını, istisnaları, daşıyıcı dəyişikliklərini, çatdırılma detallarını və məlumatların yenilənmə səviyyəsi ilə bağlı metadatanı axtarın. Bu 12 məlumat qrupu birlikdə tərtibatçılara etibarlı iş axınları yaratmağa, əməliyyat komandalarına isə tədbir görmək üçün kifayət qədər kontekst əldə etməyə kömək edir.

Bu, tərtibatçılar, texniki alıcılar və e-ticarət əməliyyat komandaları üçün tövsiyə olunan cavab müqaviləsidir; hər bir daşıyıcının və ya API-nin bütün sahələri təmin etdiyi iddia edilmir. Bəzi dəyərlərin əlçatmaz olması tamamilə normaldır. Daha yaxşı dizayn bu boşluqları fərziyyələrlə doldurmaq əvəzinə onları açıq şəkildə göstərir.
İzləmə məlumatlarını faydalı edən nədir?
Cari status bir dar suala cavab verir: göndərişin ümumiləşdirilmiş vəziyyəti nədir? Bu, mütləq nə baş verdiyini, bunun nə vaxt baş verdiyini, məlumatın yenilənib-yenilənmədiyini və ya bundan sonra nə edilməli olduğunu izah etmir.
Məsələn, iki göndərişin hər ikisi “Yoldadır” göstərə bilər, lakin fərqli cavablar tələb edə bilər. Birində obyekt üzrə yaxın zamanda skan edilmiş məlumat və bildirilmiş problem olmaya bilər. Digərində isə hadisə tarixçəsində həll edilməmiş ünvan problemi qeyd oluna bilər. Yalnız əsas statusu oxuyan tətbiq bu fərqi görə bilməz.
Cavabı üç praktiki vəzifəyə əsasən qiymətləndirin: göndərişi düzgün sifarişlə əlaqələndirmək, onun gedişatını dəqiq izah etmək və tədbirin əsaslandırılıb-əsaslandırılmadığına qərar vermək. Aşağıdakı sahələr bu vəzifələri dəstəkləyir. Sahə adları nümunə xarakterlidir; onlar universal standart və ya konkret provayderin sxemi deyil.
Cari statusdan əlavə qiymətləndiriləcək 12 sahə
1. Göndəriş və izləmə identifikatorları
Cavab təsvir edilən göndərişi müəyyən etməlidir. Faydalı dəyərlərə təqdim edilmiş izləmə nömrəsi, API-nin izləmə qeydinin identifikatoru və sisteminizin icra və ya bağlama qeydi ilə əlaqələndirə biləcəyi müştəri istinadı daxildir.
Bir sifarişin bir göndərişə bərabər olduğunu düşünməyin. Sifariş bir neçə bağlamaya bölünə, əvəzləmə isə başqa bir göndəriş yarada bilər. İzləmə qeydlərini bağlama və ya icra səviyyəsində saxlayın, sonra onları sifarişlə əlaqələndirin. Formatın və başlanğıc sıfırlarının itirilməməsi üçün izləmə nömrələrini sətir kimi saxlayın.
2. Daşıyıcının kimliyi
Oxunaqlı daşıyıcı adı ilə yanaşı sabit daşıyıcı identifikatorunu axtarın. Mümkün olduqda cavab tətbiqiniz tərəfindən açıq şəkildə təqdim edilən daşıyıcı ilə avtomatik aşkarlama yolu ilə seçilən daşıyıcını fərqləndirməlidir.
Daşıyıcı konteksti izləmə nömrəsini və hadisələrini şərh edərkən vacibdir. Aşkarlama qeyri-müəyyəndirsə, inteqrasiyanız qeyri-müəyyən uyğunluğu təsdiqlənmiş kimi səssizcə göstərmək əvəzinə onu həll etmək imkanına malik olmalıdır. Xidmət səviyyəsi məlumatlarını ayrıca saxlayın: yalnız daşıyıcının adı göndərişin ekspress, poçt və ya başqa xidmətdən istifadə etdiyini göstərmir.
3. Normallaşdırılmış status detalları
Əsas statusla yanaşı sənədləşdirilmiş detal kodu və ya alt-status tələb edin. Geniş kateqoriya göndərişi istisna kimi təsvir edə bilər, detal isə çatdırılma cəhdini, ünvan problemini və ya gömrüklə bağlı saxlanmanı müəyyənləşdirir.
Biznes məntiqi üçün sabit kodlardan, təqdimat üçün isə oxunaqlı etiketlərdən istifadə edin. Naməlum və ya xəritələndirilməmiş hadisələrlə necə davrandığı da daxil olmaqla, provayderin daşıyıcı hadisələrini bu kodlara necə uyğunlaşdırdığını yoxlayın. Normallaşdırılmış etiket müxtəlif daşıyıcı lentlərinin istifadəsini asanlaşdırır, lakin dəstək komandanızın ehtiyac duyduğu fərqləri silməməlidir.
4. Daşıyıcının ilkin mesajları və kodları
Təqdim edildikdə ilkin hadisə təsvirini və daşıyıcının hadisə kodunu saxlayın. Bu dəyərlər, xüsusilə daşıyıcı konkret əməliyyat ifadəsindən istifadə etdikdə, normallaşdırılmış statusda olmayan konteksti dəstək agentlərinə təqdim edir.
İlkin mətni tərcümə edilmiş və ya yenidən yazılmış təsvirlərdən ayrı saxlayın. Əks halda, müştəriyə yönəlik izah daşıyıcının dəqiq ifadəsi kimi səhv başa düşülə bilər. Göstərərkən daşıyıcı mətnini etibarsız giriş kimi qəbul edin: onu düzgün şəkildə qaçışlandırın və icra edilə bilən HTML kimi göstərməyin.
5. İzləmə hadisələrinin tarixçəsi
Faydalı cavab yalnız son hadisəni deyil, göndərişin zaman xəttini də göstərməlidir. Hər bir hadisə ideal olaraq identifikator, status və ya kod, təsvir, vaxt möhürü və mövcud məkan məlumatını ehtiva etməlidir.
API-nin tam tarixçəni, məhdud zaman aralığını və ya səhifələnmiş nəticələri qaytarıb-qaytarmadığını yoxlayın. Düzəlişlərin və təkrarlanan müşahidələrin necə göstərildiyini də müəyyənləşdirin. Cavab müqaviləsi bu sıralanmanı açıq şəkildə təmin etmədiyi halda tətbiqiniz ilk elementin həmişə ən yeni olduğunu düşünməməlidir.
6. Hadisə vaxtları və saat qurşağı məlumatları
Hadisənin baş verdiyi vaxt API-nin onu qəbul etdiyi və ya qaytardığı vaxtdan fərqlidir. Mümkün olduqda hər ikisini qoruyun. Bu fərq yeni qəbul edilmiş yeniləmənin daha əvvəl baş vermiş hadisəni necə təsvir edə bildiyini izah etməyə kömək edir.
Açıq UTC fərqləri və ya UTC işarəsi ilə vaxt möhürləri tələb edin. RFC 3339 rəqəmsal vaxt fərqləri də daxil olmaqla, internet protokolları üçün uyğun vaxt möhürü formatını müəyyənləşdirir. Mənbə yalnız məlum fərq olmadan yerli vaxt təqdim edirsə, onu səssizcə UTC kimi qəbul etmək əvəzinə bu qeyri-müəyyənliyi qoruyun. Əsas mənbə yalnız tarix təqdim edirsə, saniyə səviyyəsində dəqiqlik təəssüratı yaratmayın.
7. Hadisə məkanları və göndəriş coğrafiyası
Təqdim edildikdə şəhər, region, ölkə və poçt kodu kimi strukturlaşdırılmış məkan komponentlərini axtarın. Strukturlaşdırılmış sahələrə çevrilmə məna itkisinə səbəb ola bilərsə, xam məkan sətrini də qoruyun.
Skan məkanı bağlamanın canlı mövqeyi olmaya bilər. Eyni şəkildə, son bildirilmiş obyekt bağlamanın hələ də orada olduğuna sübut deyil. Müştəriyə yönəlik səhifələrdə onu son bildirilmiş məkan kimi təsvir edin. Natamam skan mətnindən koordinatlar və ya dəqiq çatdırılma ünvanı çıxarmaqdan çəkinin.
8. Təxmini çatdırılma tarixi və ya aralığı
Təxmini çatdırılma sahəsi onun tək tarix, yoxsa zaman aralığı ehtiva etdiyini, kimin tərəfindən yaradıldığını və sonuncu dəfə nə vaxt yeniləndiyini göstərməlidir. Daşıyıcı tərəfindən təqdim edilən təxmin ayrıca hesablanmış proqnozdan fərqləndirilməlidir.
Yalnız tarixdən ibarət təxmini məlumatı dəqiq çatdırılma vaxtına çevirməyin. İnteqrasiyanız yenilənmiş və ya geri götürülmüş təxminləri də idarə etməlidir ki, izləmə səhifəsində köhnəlmiş vəd saxlanılmasın. Təxmin yoxdursa, dəstəklənməyən fərziyyə əsasında hesablamamaq əvəzinə onun əlçatmaz olduğunu göstərin.
9. İstisnanın səbəbi və tələb olunan tədbir
İstisna məlumatı problemi izah etməli və mənbə bunu dəstəkləyirsə, tədbiri, məsul tərəfi və ya son tarixi müəyyənləşdirməlidir. Ümumi gecikmə bildirişi alıcı məlumatının tələb edilməsindən əməliyyat baxımından fərqlənir.
Bildirilmiş faktları öz iş axını qərarlarınızdan ayrı saxlayın. Məsələn, müəyyən edilmiş müddət ərzində yeniləmə olmadıqda biznesiniz dəstək tapşırığı aça bilər. Bu, daxili eskalasiya qaydasıdır, daşıyıcının bağlamanı itmiş elan etdiyinə sübut deyil. Qeyri-müəyyən izləmə mətnindən ödəniş təlimatları və ya həssas məlumat sorğuları yaratmayın.
10. Daşıyıcı dəyişiklikləri və əlaqəli izləmə nömrələri
Göndəriş operatorlar arasında hərəkət etdikdə faydalı məlumatlara növbəti daşıyıcı, əlaqəli izləmə nömrəsi və ilkin və sonrakı qeydlər arasındakı əlaqə daxildir. Bu, çatdırılmanın növbəti mərhələsində fərqli identifikatordan istifadə edildikdə davamlılığı qorumağa kömək edə bilər.
Bildirilmiş daşıyıcı dəyişməsini ilkin daşıyıcını əvəz etmək əvəzinə əlaqə kimi qəbul edin. Təyinatları və ya izləmə nömrələri oxşar göründüyünə görə qeydləri birləşdirməyin. Əlaqə təqdim edilməyib və ya başqa şəkildə təsdiqlənməyibsə, davamlı səyahət uydurmaq əvəzinə onu həll edilməmiş saxlayın.
11. Çatdırılma nəticəsi və sübut istinadları
Çatdırılma bildirildikdə cavabda qeyd edilmiş çatdırılma vaxtı və təhlükəsiz yerin təsviri və ya alıcının kateqoriyası kimi mövcud çatdırılma detalları təqdim edilməlidir. Daşıyıcı və xidmət bunu təmin edirsə, çatdırılma sübutuna istinad da faydalı ola bilər.
Çatdırıldı statusu nəzərdə tutulan alıcının bağlamanı şəxsən qəbul etdiyinə sübut kimi qəbul edilməməlidir. İmzalar, fotoşəkillər, adlar və dəqiq məkanlar şəxsi məlumat ehtiva edə bilər. Girişi məhdudlaşdırın, bu detalları ictimai izləmə səhifələrində göstərməkdən çəkinin və sübut keçidləri üçün icazə və ya müddət bitmə tələblərini yoxlayın.
12. Yenilənmə səviyyəsi, əldəetmə vəziyyəti və cavab metadatası
Son göndəriş hadisəsini son uğurlu məlumat əldəetməsindən fərqləndirmək üçün kifayət qədər metadata tələb edin. Faydalı dəyərlərə son uğurlu yoxlama, son uğursuz cəhd, cavabın yaradılma vaxtı və qaytarılmış məlumatların keşlənmiş və ya qismən olub-olmaması daxildir.
Uğurlu API sorğusu öz-özlüyündə daşıyıcının yeni skan dərc etdiyini göstərmir. HTTP cavab semantikası sorğunun nəticəsini təsvir edir; göndərişin irəliləyişi tətbiq məlumatlarına aiddir. Əldəetmə xətalarını göndəriş istisnalarından ayrı saxlayın ki, müvəqqəti bağlantı problemi yanlış çatdırılma xəbərdarlığına çevrilməsin.
Çatışmayan məlumat müəyyən edilmiş məna daşımalıdır
Sahənin mövcudluğu müqavilənin yalnız bir hissəsidir. Komandanız yox olan dəyərin nə demək olduğunu da başa düşməlidir. Çatdırılma təxmini mənbədən əlçatmaz, hələ əldə edilməmiş və ya çatdırılmadan sonra tətbiq olunmayan ola bilər. Bu vəziyyətlər avtomatik olaraq eyni müştəri mesajını yaratmamalıdır.
- Naməlum: Dəyər müəyyən edilməyib.
- Təqdim edilməyib: Mənbə əldə edilmiş məlumatlarda dəyəri təqdim etməyib.
- Tətbiq olunmur: Sahə bu qeyd və ya vəziyyət üçün keçərli deyil.
- Əldəetmə uğursuz oldu: Sistem müvafiq axtarışı tamamlaya bilmədi.
Bunlar məcburi hərfi dəyərlər deyil, tövsiyə olunan fərqlərdir. Hansı təqdimat formasını seçməyinizdən asılı olmayaraq, onu sənədləşdirin. Həqiqi qeydlərə bənzəyən yer tutucu tarixlərdən, boş obyektlərdən və real məkan kimi səhv başa düşülə biləcək standart koordinatlardan çəkinin.
İnteqrasiyadan əvvəl cavabı necə yoxlamaq olar
Biznesinizin istifadə etdiyi daşıyıcılardan, xidmətlərdən və çatdırılma marşrutlarından alınmış real yükləri qiymətləndirin. Sxem istəyə bağlı sahəni sadalaya bilər, lakin əsas mənbənin onu hər dəfə dolduracağına zəmanət vermir. 17TRACK inteqrasiyası üçün bu təlimatdakı konseptual sahə adlarını birbaşa istifadəyə hazır parametrlər kimi qəbul etmək əvəzinə cavab müqaviləsini yoxlamaq üçün rəsmi Tracking API sənədlərindən istifadə edin.
- Nümunəvi nümunə yaradın. Yeni qeydiyyata alınmış göndərişləri, aktiv göndərişləri, çatdırılma cəhdlərini, tamamlanmış çatdırılmaları və mövcud daşıyıcı dəyişikliklərini daxil edin.
- Sahələri hadisələrə qədər izləyin. Göstərilən statusun, son hadisənin və çatdırılma detallarının ardıcıl qeydi təsvir etdiyini təsdiqləyin. Uyğunsuzluqları gizlətmək əvəzinə araşdırın.
- Gecikmiş və təkrarlanan yeniləmələri yoxlayın. Eyni yükü yenidən emal edin və daha yeni hadisədən sonra köhnə hadisə qəbul edin. Hər iki halın təkrarlanan bildiriş yaratmadığını və göstərilən vəziyyəti səhvən geri çevirmədiyini təsdiqləyin.
- Çatışmayan və səhv formatlı dəyərləri yoxlayın. Çatışmayan təxminləri, naməlum məkanları, tanınmayan status kodlarını və natamam vaxt möhürlərini daxil edin. Tətbiq əvəzedici dəyərlər uydurmadan istifadəyə yararlı qalmalıdır.
- Daşıma xətalarını izləmə nəticələrindən ayırın. Autentifikasiya xətası, vaxt aşımı və ya səhv formatlı cavab inteqrasiya xətası yoluna düşməlidir, göndəriş istisnası iş axınına deyil.
- Müştəri görünüşünü təsdiqləyin. Daxili istinadların, xam diaqnostik detalların və şəxsi məlumatların ictimai səhifələrə və ya bildirişlərə sızmadığını yoxlayın.
Webhook əsaslı yeniləmələr üçün provayderin sənədlərində çatdırılma identifikatorlarını, autentifikasiyanı, təkrar cəhd davranışını və təkrar oynatma idarəsini də yoxlayın. Bunlar göndəriş faktlarından deyil, inteqrasiya tələblərindən ibarətdir. Qəbulediciniz təkrarlanan çatdırılmaları təhlükəsiz emal etməli və qəbul sırasının hadisə sırasına bərabər olduğunu düşünməməlidir.
Qəbul meyarı praktiki olmalıdır: tətbiqiniz dəstəklənməyən iddialar irəli sürmədən göndərişi izah edə bilərmi və əməliyyat komandanız əsaslandırılmış növbəti tədbiri müəyyən edə bilərmi? Daha kiçik, dəqiq müəyyən edilmiş yük izah edilməmiş istəyə bağlı dəyərlərlə dolu daha böyük cavabdan faydalı ola bilər.
Tez-tez verilən suallar
Hər göndərişdə bütün 12 məlumat qrupu doldurulmalıdır?
Xeyr. Çatdırılma sübutu, sonrakı izləmə nömrələri və təxmini çatdırılma tarixləri əlçatan və ya tətbiq olunan olmaya bilər. Universal doldurulma əvəzinə aydın sahə tərifləri və proqnozlaşdırıla bilən çatışmayan dəyər davranışı tələb edin. Faktiki çatdırılma çeşidinizə əsasən ən vacib sahələri yoxlayın.
Xam cavabı, yoxsa yalnız normallaşdırılmış sahələri saxlamalıyıq?
Tətbiq məntiqi üçün normallaşdırılmış sahələri saxlayın. Müvafiq mənbə yüklərinin qorunması sazlama və xəritələndirmə dəyişikliklərinə də kömək edə bilər, lakin məxfilik, təhlükəsizlik, müqavilə və saxlama tələbləriniz nəzərə alınmalıdır. Girişi məhdudlaşdırın və cavabda göründüyünə görə həssas məzmunu avtomatik saxlamayın.
Son hadisəni hansı vaxt möhürü müəyyən etməlidir?
Saat qurşaqlarını və düzəlişləri nəzərə alaraq sənədləşdirilmiş hadisə xronologiyasından və provayderin sıralama qaydalarından istifadə edin. Qəbul vaxtı sisteminizin hadisədən nə vaxt xəbər tutduğunu göstərir, onun nə vaxt baş verdiyini deyil. Vaxt möhürləri natamam və ya ziddiyyətlidirsə, dəqiq ardıcıllıq iddia etmək əvəzinə qeyri-müəyyənliyi qoruyun.
İzləmə API-si bağlamanın itdiyini təsdiqləyə bilərmi?
İtkini yalnız mənbə bu şərhi açıq şəkildə dəstəklədikdə daşıyıcı tərəfindən bildirilmiş kimi qəbul edin. Uzun müddət skanların olmaması əməliyyat qaydalarınıza əsasən araşdırmaya səbəb ola bilər, lakin təkcə səssizlik itkinin baş verdiyini göstərmir. “Köhnəlmiş izləmə” və “itmiş kimi bildirilmiş” anlayışlarını ayrı saxlayın.
Çatdırıldı statusu müştəri şikayətini bağlamaq üçün kifayətdirmi?
Avtomatik olaraq yox. Bu, bildirilmiş izləmə nəticəsini təsdiqləyir, lakin alıcının mübahisəsini həll etməyə bilər. Mövcud çatdırılma detallarını, müştəri hesabını və dəstək prosesinizi nəzərdən keçirin. Status etiketini ziddiyyətli məlumatların araşdırılmasının əvəzi kimi qəbul etməyin.
Mənbələr
- 17TRACK Tracking API sənədləri — inteqrasiyanın sənədləşdirilmiş sahələrini və davranışını yoxlamaq üçün məhsula xas istinad; yuxarıdakı 12 qrup onun sxeminin surəti deyil, redaksiya tövsiyələridir.
- RFC 3339: İnternetdə tarix və vaxt: vaxt möhürləri — vaxt möhürlərinin təqdimatı və vaxt fərqi qaydaları.
- RFC 9110: HTTP semantikası — göndəriş səviyyəsindəki biznes statusundan fərqli olan HTTP cavab semantikası.


