Webhook-u gözləmədən ən son göndəriş statusunu API vasitəsilə necə əldə etmək olar
Vebhook-u gözləmədən mövcud olan ən son göndəriş statusunu əldə etmək üçün izləmə provayderinizin göndəriş sorğusu API-sinə autentifikasiya olunmuş sorğu göndərin. Tətbiqinizi dərhal yeniləmək üçün cavabdan istifadə edin, sonra isə sonrakı dəyişikliklər üçün vebhook-ları aktiv saxlayın. Əsas fərq ondan ibarətdir ki, sorğu adətən provayderin saxladığı ən son izləmə məlumatını əldə edir; bu, mütləq yeni daşıyıcı yoxlamasını işə salmır.

Bu yanaşma müştəri sifariş səhifəsini açdıqda, dəstək əməkdaşına yeniləmə lazım olduqda və ya sisteminiz buraxılmış bildirişdən bərpa olunmalı olduqda faydalıdır. Etibarlı tətbiq tələb üzrə sorğuları, aydın aktuallıq göstəricilərini və təkrarlanan və ya ardıcıllıqdan kənar yeniləmələrə qarşı qoruma mexanizmlərini birləşdirir.
“Ən son göndəriş statusu”nun nə demək olduğunu müəyyənləşdirin
Son nöqtəni seçməzdən əvvəl oxşar səslənə bilən, lakin fərqli nəticələr verən üç əməliyyatı ayırd edin.
| Əməliyyat | Nə edir | Nəyi müəyyən etmir |
|---|---|---|
| Öz verilənlər bazanızı oxuyun | Tətbiqinizin artıq saxladığı izləmə məlumatlarını qaytarır. | Provayderin daha yeni yeniləmə alıb-almadığını. |
| İzləmə API-sinə sorğu göndərin | Provayderin sorğu əməliyyatı vasitəsilə mövcud olan məlumatları əldə edir. | Bu sorğu zamanı yeni daşıyıcı axtarışının aparılıb-aparılmadığını. |
| İzləməni yeniləmə sorğusu göndərin | Provayder belə əməliyyat təklif edirsə, yuxarı səviyyədə daha bir yoxlama tələb edir. | Daşıyıcının yeni skanı olduğunu və ya yeniləmənin sinxron tamamlandığını. |
İndi cavaba ehtiyacınız olduqda sorğudan istifadə edin. Provayderin daha bir yuxarı səviyyə yoxlaması aparmasını istədikdə isə yalnız yeniləmə əməliyyatını araşdırın. Keşdən yan keçən parametr əlavə etməyin, sorğunu təkrarlamağın və ya HTTP cache-control başlığı göndərməyin daşıyıcını yeni məlumat təqdim etməyə məcbur edəcəyini düşünməyin.
Göndərişin görünməsi bir neçə mərhələdən ibarətdir: daşıyıcı hadisəni qeydə alır, izləmə provayderi onu əldə edir və tətbiqiniz onu qəbul edir və ya əldə edir. Birbaşa API sorğusu bildirişin çatdırılmasını gözləməkdən yan keçə bilər, lakin həmin zəncirin əvvəlki mərhələlərindəki gecikmələri aradan qaldıra bilməz.
Kod yazmazdan əvvəl sorğu müqaviləsini yoxlayın
İzləmə xidmətini inteqrasiya edən tərtibatçı bu iş prosesinə cavabdehdir. Köhnə inteqrasiya nümunəsindən kopyalanmış son nöqtə ilə deyil, provayderin cari sənədləri ilə başlayın. Aşağıdakı detalları təsdiqləyin:
- Göndərişin identifikasiyası: Sorğu izləmə nömrəsini, daxili göndəriş ID-sini, yoxsa daşıyıcı identifikatoru ilə birlikdə izləmə nömrəsini qəbul edir?
- Qeydiyyat tələbləri: Göndəriş sorğu edilə bilməzdən əvvəl qeydiyyatdan keçirilməlidirmi?
- Autentifikasiya: Hansı başlıq və ya autentifikasiya mexanizmi tələb olunur?
- Cavabın mənası: Əməliyyat saxlanmış məlumatları qaytarır, məlumatların toplanmasını başladır, yoxsa daha sonra yoxlanılmalı iş qaytarır?
- Nəticənin emalı: Uğurlu HTTP cavabı göndəriş səviyyəsində xəta və ya gözləmədə olan nəticə ehtiva edə bilərmi?
- İstifadə məhdudiyyətləri: Hansı tezlik məhdudiyyətləri, paket limitləri və hesaba xas məhdudiyyətlər tətbiq olunur?
- Aktuallıq sahələri: Hansı zaman nişanları daşıyıcı hadisələrini, provayder yeniləmələrini və cavabın yaradılmasını göstərir?
17TRACK inteqrasiyası üçün istehlakçı izləmə səhifəsi və ya mağaza izləmə interfeysi deyil, Tracking API müvafiq məhsuldur. İnteqrasiyanız üçün izləmə məlumatı sorğusu əməliyyatını, autentifikasiyanı, sorğu sahələrini və cavab strukturunu təsdiqləmək üçün rəsmi API sənədlərindən istifadə edin. Sorğunu və vebhook emalını eyni göndəriş qeydini yeniləyən ayrı tətbiq yolları kimi nəzərdən keçirin.
Yeniləmə davranışı və ya sorğu tezliyi barədə fərziyyələri kodda sərtləşdirməkdən çəkinin. Bu detallar istifadə etdiyiniz əməliyyata və xidmət şərtlərinə uyğun olmalıdır.
Backend vasitəsilə tələb üzrə axtarış yaradın
Praktik dizayn öz tətbiqinizdə autentifikasiya olunan son nöqtə təqdim etməkdir. Brauzer həmin son nöqtədən göndəriş yeniləməsi tələb edir; serveriniz avtorizasiyanı yoxlayır, provayder sorğusunun lazım olub-olmadığını müəyyən edir və normallaşdırılmış nəticə qaytarır.
Aşağıdakı marşrut tətbiqinizdə yaradacağınız son nöqtəyə nümunədir. Bu, 17TRACK son nöqtəsi və ya provayder sorğu spesifikasiyası deyil.
GET /api/orders/{order_id}/shipment-statusServerdə göndərişi axtarmaq üçün sifariş identifikatorundan istifadə edin. Sorğuda izləmə nömrəsini dəyişməklə çağıranın başqa müştərinin izləmə tarixçəsini əldə etməsinə imkan verməyin. Provayder API məlumatlarını brauzer JavaScript-ində və ya mobil tətbiq paketində deyil, backend-də saxlayın.
Tətbiq edə biləcəyiniz sorğu axını
- Girişi avtorizasiya edin. Müştərinin və ya əməkdaşın sifarişə baxmaq səlahiyyətinin olduğunu təsdiqləyin.
- Göndərişi müəyyənləşdirin. Saxlanmış izləmə identifikatorunu və uyğun olduqda daşıyıcı məlumatlarını oxuyun.
- Yerli aktuallığı yoxlayın. Son uğurlu sorğu artıq mövcuddursa, tətbiqinizin aktuallıq siyasətinə uyğun olaraq ondan yenidən istifadə edin.
- Lazım olduqda provayderə sorğu göndərin. Sənədləşdirilmiş əməliyyatdan və məhdud sorğu vaxtından istifadə edin.
- Nəticəni təsdiqləyin. Həm HTTP nəticəsini, həm də göndəriş səviyyəsindəki nəticəni yoxlayın.
- Məlumatları birləşdirin. Vebhook hadisələri üçün istifadə olunan eyni normallaşdırma və uyğunlaşdırma qaydalarını tətbiq edin.
- Statusu və aktuallığı qaytarın. Mövcud olduqda ən son hadisə vaxtını və provayderin son uğurlu yoxlama vaxtını daxil edin.
Yerli aktuallıq siyasəti mühəndislik qərarıdır, daşıyıcı yeniləmələrinin tezliyi barədə bəyanat deyil. Onu interfeys tələblərinizə, provayder limitlərinə, göndəriş həcminə və müşahidə olunan sorğu faydasına əsasən seçin. Müştərinin yeniləmə düyməsinə dəfələrlə basması yuxarı səviyyəyə məhdudiyyətsiz sorğu axını yaratmamalıdır.
Aktuallıq uydurmadan cavabı normallaşdırın
Provayderlərin cavab strukturları fərqli olsa da, tətbiqiniz sabit daxili format qaytara bilər. Bu nümunə obyekt provayderin faktiki yükü deyil, sizin tətbiq müqavilənizdir:
{
"shipment_id": "internal-shipment-id",
"status": "in_transit",
"latest_event_at": null,
"provider_updated_at": null,
"last_successful_query_at": null,
"retrieval_state": "success",
"source": "provider_query"
}Hər zaman nişanını yalnız mənası məlum olduqda doldurun. Serverinizin cavabı qəbul etdiyi vaxt sorğu metadatasına aiddir; bu, bağlamanın hərəkət etdiyi vaxt kimi təqdim edilməməlidir. Provayder yeniləmə vaxtı təqdim etmirsə, başqa zaman nişanını əvəz kimi istifadə etməkdənsə həmin sahəni boş saxlayın və ya null edin.
Müştəri interfeysində mesajları ayırın: “Son daşıyıcı hadisəsi” göndəriş fəaliyyətini, “İzləmə yoxlanıldı” isə tətbiqinizin məlumat əldə etmə fəaliyyətini təsvir edir. Bu fərq dəyişməmiş skanın yeni qeydə alınmış kimi görünməsinin qarşısını alır.
API sorğularının və vebhook-ların bir-birini əvəz etməsinə imkan verməyin
Hər iki mexanizm aktiv olduqda eyni hadisə sorğu və vebhook vasitəsilə gələ bilər. Onlar başladıqdan fərqli ardıcıllıqla da tamamlana bilər. Əvvəl başladılan sorğu vebhook artıq daha yeni məlumat təqdim etdikdən sonra tamamlana bilər.
Son cavab qalibdir məntiqindən istifadə etməyin. Ən son qəbul edilən yük mütləq ən son göndəriş vəziyyəti deyil.
- Bir yeniləmə axınını paylaşın. Sorğu nəticələrini və vebhook yüklərini eyni təsdiqləmə, normallaşdırma və yadda saxlama funksiyalarından keçirin.
- Hadisələrin dublikatını silin. Sənədləşdirilmiş hadisə identifikatoruna üstünlük verin. Belə identifikator yoxdursa, hadisə vaxtı, status, məkan və təsvir kimi mövcud sahələrdən diqqətlə müəyyən edilmiş barmaq izi yaradın.
- Mənası məlum olan sıralama sahələrindən istifadə edin. Sənədləşdirilmiş reviziya və ya ardıcıllıq, qəbul vaxtının hadisə ardıcıllığını göstərdiyini fərz etməkdən daha faydalıdır.
- Tarixçəni qoruyun. Yeni qəbul edilmiş hadisə cari göndəriş xülasəsini dəyişmədən tarixi boşluğu doldura bilər.
- Düzəlişlərə imkan verin. Statuslar universal xətti pillə deyil. Görünən hər geriyə keçidi daim rədd etmək əvəzinə sənədləşdirilmiş düzəliş davranışına əməl edin.
Hadisələrin ardıcıllığı qeyri-müəyyən olduqda ilkin yükü və onun mənşəyini araşdırma üçün saxlayın. Hadisə vaxtı uydurmaqla və ya bütün daşıyıcı zaman nişanlarının eyni vaxt qurşağında olduğunu fərz etməklə qeyri-müəyyənliyi aradan qaldırmağa çalışmayın.
Çatışmayan məlumatları və uğursuz sorğuları fərqli idarə edin
Boş nəticə, dəyişməz nəticə və uğursuz sorğu müştəriyə eyni mesajı göstərməməlidir.
Sorğu uğurludur, lakin status dəyişməyib
Mövcud göndəriş statusunu saxlayın və son uğurlu sorğu vaxtını yeniləyin. Başqa axtarışın tamamlanması səbəbindən yeni göndəriş hadisəsi yaratmayın. Müştəriyə daha ətraflı məlumat lazımdırsa, mövcud hadisə tarixçəsini göstərin və daha yeni izləmə hadisəsinin qaytarılmadığını izah edin.
Göndərişdə hələ izləmə məlumatı yoxdur
Qeydiyyatın tələb olunub-olunmadığını, identifikatorun və daşıyıcının düzgün olub-olmadığını, provayderin gözlənilən məlumat toplanmasını necə təqdim etdiyini yoxlayın. Hadisələrin olmaması öz-özlüyündə izləmə nömrəsinin etibarsız olduğunu və ya bağlamanın itdiyini sübut etmir. Provayderin naməlum identifikator, məlumat gözləyən qeydiyyatlı göndəriş və emal edilə bilməyən sorğu arasındakı fərqi qoruyun.
Provayder sorğusunun vaxtı bitir və ya sorğu uğursuz olur
Əvvəlki etibarlı statusunuz varsa, onu son yoxlamanın uğursuz olduğunu açıq şəkildə bildirərək qaytarın. Əvvəlki uğurlu sorğu zaman nişanını dəyişməyin. Şəbəkə xətası çatdırılma istisnası deyil və bağlamanın biznes statusunu dəyişməməlidir.
Münasib müvəqqəti xətalar üçün geriçəkilmə və təsadüfilik ilə məhdud təkrar cəhdlərdən istifadə edin. Etibarsız məlumatlar və ya səhv formatlaşdırılmış sorğuları dəfələrlə təkrarlamayın. Cavabda Retry-After təqdim olunursa, onu provayder müqaviləsinə və HTTP semantikasına uyğun şərh edin. HTTP spesifikasiyası bu dəyərin saniyələrlə gecikmə və ya HTTP tarixi formasında ifadə olunmasına imkan verir.
Eyni göndəriş üçün bir neçə sorğu daxil olur
Paralel axtarışları birləşdirin ki, onlar bir yuxarı səviyyə sorğusunu paylaşa bilsinlər. Hesab və göndəriş üzrə limitlər tətbiq edin və avtomatik təkrar cəhdin bir neçə tətbiq qatında çoxalmasının qarşısını alın. Paketləmə dəstəklənirsə, HTTP sorğusu tamamlandığı üçün bütün paketi uğurlu hesab etmək əvəzinə hər göndərişin nəticəsini ayrıca yoxlayın.
Nəzarətli ehtiyat variant kimi sorğulama istifadə edin
Vebhook-lar olmadan planlaşdırılmış sorğulama verilənlər bazanızı yeniləyə bilər, lakin bunun üçün açıq əməliyyat siyasəti tələb olunur. Hansı göndərişlərin uyğun olaraq qalacağını, xətaların cədvələ necə təsir edəcəyini və müntəzəm sorğulamanın nə vaxt dayandırılacağını müəyyənləşdirin.
Əksər inteqrasiyalar üçün hibrid dizayn məntiqli başlanğıcdır: vebhook-lar fon dəyişikliklərini idarə edir, tələb üzrə sorğular interaktiv istəklərə xidmət edir, uzlaşdırma tapşırıqları isə diqqət tələb edən qeydləri yoxlayır. Bu, memarlıq tövsiyəsidir və hər hesab üçün xərci minimuma endirəcəyinə zəmanət vermir.
- Aktiv göndərişlərə və həll olunmamış məlumat əldə etmə xətaları olan qeydlərə üstünlük verin.
- Hər planlaşdırılmış icrada bütün tarixi göndərişləri sorğulamaqdan çəkinin.
- Tamamlanmış göndərişlərin necə idarə olunacağını, o cümlədən biznesinizin tələb etdiyi düzəliş müddətini müəyyənləşdirin.
- Sorğuların nə qədər tez-tez həqiqətən yeni məlumat tapdığını izləyin.
- Getdikcə daha tez-tez sorğulama ilə problemləri gizlətmək əvəzinə vebhook çatdırılma problemlərini araşdırın.
Provayder sorğusunun gecikməsini, uğursuz sorğuları, tezlik limiti cavablarını və sorğu məlumatları ilə vebhook vasitəsilə daxil olan qeydlər arasındakı fərqləri izləyin. Ən son daşıyıcı hadisəsinin yaşını ayrıca izləyin. Uğurlu API cavabları izləmə məlumatlarının dəyişməməsi ilə yanaşı mövcud ola bilər.
Buraxılışdan əvvəl iş prosesini test edin
Uğurlu sorğu yalnız ilk testdir. Əks halda yanıltıcı status yeniləmələri yarada biləcək vəziyyətləri yoxlayın:
- Tələb üzrə sorğu hələ işləyərkən vebhook daxil olur.
- İki müştəri və ya əməkdaş sessiyası eyni göndərişi eyni vaxtda tələb edir.
- Provayder HTTP uğuru qaytarır, lakin göndəriş səviyyəsində xəta bildirir.
- Tətbiqiniz artıq etibarlı izləmə məlumatına malik olduqdan sonra sorğu uğursuz olur.
- Hadisədə vaxt qurşağı yoxdur və ya tanış olmayan status kodu var.
- Daşıyıcı düzəlişi əvvəllər göstərilmiş nəticəni dəyişir.
- İstifadəçi başqa hesaba aid göndərişə giriş əldə etməyə çalışır.
Buraxılış meyarınız belə olmalıdır: tətbiq ən yaxşı məlum göndəriş məlumatını qaytarmalı, onun aktuallığını dəqiq izah etməli və sorğular uğursuz olduqda və ya ardıcıllıqdan kənar gəldikdə həmin məlumatı korlamamalıdır.
Tez-tez verilən suallar
API-yə sorğu göndərmək daşıyıcını bağlamanı skan etməyə və ya yeniləməyə məcbur edirmi?
Xeyr. İzləmə məlumatını əldə etmək fiziki skana səbəb ola bilməz. Sorğunun yuxarı səviyyədə axtarışı işə salıb-işə salmaması sənədləşdirilmiş əməliyyatdan asılıdır. Dəstəklənən yeniləmə belə daşıyıcıda daha yeni hadisə yoxdursa, dəyişməmiş məlumat qaytara bilər.
Vebhook-ları konfiqurasiya etmədən API sorğularından istifadə edə bilərəmmi?
Provayder tələb olunan sorğu iş prosesini dəstəkləyirsə, inteqrasiyanı tələb üzrə sorğular və ya sorğulama ətrafında qura bilərsiniz. Əvvəlcə qeydiyyat və sorğu tələblərini təsdiqləyin. Bundan sonra nə vaxt yoxlama aparılacağına, sorğu həcminə nəzarətə və dəyişikliklərin aşkarlanmasına tətbiqiniz cavabdeh olacaq.
Göndəriş statusunu nə qədər tez-tez sorğulamalıyam?
Universal interval yoxdur. Provayderinizin limitlərinə, göndəriş həcminizə və yeniləmələri daha tez tapmağın biznes dəyərinə uyğun cədvəl seçin. Sorğulamanın nə qədər tez-tez yeni hadisələr qaytardığını ölçün və tez-tez sorğuların daha aktual daşıyıcı məlumatı yaradacağını fərz etmək əvəzinə cədvəli buna əsasən dəyişin.
API niyə vebhook vasitəsilə artıq qəbul etdiyim məlumatı qaytarır?
Hər iki yol eyni əsas göndəriş qeydini təqdim edə bilər. Vebhook bildiriş çatdırır, sorğu isə məlumatı tələb üzrə əldə edir. Eyni hadisənin hər iki yolla alınması mütləq xəta deyil; tətbiqiniz onun dublikatını silməlidir.
Yeniləmə düyməsində “İzləməni yenilə” yazılmalıdırmı?
Yalnız bu ifadə əməliyyatı dəqiq təsvir edirsə. Düymə saxlanmış provayder məlumatlarını əldə edirsə, “Yeniləmələri yoxla” daha aydındır. Son daşıyıcı hadisəsini tətbiqinizin son uğurlu yoxlamanı tamamladığı vaxtdan ayrıca göstərin.
Mənbələr
- 17TRACK Tracking API — bu təlimatda müzakirə olunan izləmə API inteqrasiyası üçün rəsmi məhsul məlumatı.
- 17TRACK API documentation — provayderə xas əməliyyatlar, autentifikasiya, sorğu sahələri və cavabların emalı üzrə məlumat.
- RFC 9110, Section 10.2.3: Retry-After — HTTP başlığının delay-seconds və HTTP-date formalarını müəyyən edir.


