Skip to main content
Ana səhifəBloqBələdçilərGöndərişin izlənməsi API iş axını: göndərişin qeydiyyata alınmasından izləmə məlumatlarının əldə edilməsinə qədər

Göndərişin izlənməsi API iş axını: göndərişin qeydiyyata alınmasından izləmə məlumatlarının əldə edilməsinə qədər

17TRACK

Göndəriş izləmə API iş axını izləmə nömrəsinin və tələb olunan daşıyıcı məlumatlarının təqdim edilməsi, qeydiyyatın uğurlu olub-olmadığının yoxlanılması, izləmə məlumatlarının əlçatan olmasının gözlənilməsi və göndərişin statusu ilə hadisə tarixçəsinin əldə edilməsi ilə başlayır. İstehsal inteqrasiyası üçün tərtibatçılar həmçinin hər bir izləmə qeydini sifarişlə əlaqələndirməli, qismən uğursuzluqları idarə etməli, yeniləmələri təhlükəsiz şəkildə emal etməli və qəbul edilmiş qeydiyyatı faktiki daşıyıcı skanından fərqləndirməlidirlər.

Göndərişin qeydiyyatından məlumatların əldə edilməsinədək göndəriş izləmə API iş axını

Bu təlimat elektron ticarət platformasını, sifariş idarəetmə sistemini, anbar tətbiqini və ya müştəri xidməti alətini birləşdirən tərtibatçılar üçün həmin iş axınını izah edir. Burada tətbiq dizaynı üzrə tövsiyələr provayderə xas API tələblərindən ayrılır. 17TRACK inteqrasiyası üçün aşağıdakı nümunələri tətbiq etməzdən əvvəl sorğu sxemini, autentifikasiyanı, dəstəklənən əməliyyatları və cavab sahələrini təsdiqləmək məqsədilə rəsmi API sənədlərindən istifadə edin.

Qeydiyyatın nə etdiyini və nə etmədiyini anlayın

Göndərişin izləmə xidməti ilə qeydiyyata alınması xidmətin API müqaviləsinə uyğun olaraq həmin göndərişi izləyə və ya idarə edə bilməsi üçün identifikatorun təqdim edilməsi deməkdir. Bu, poçt haqqının ödənilməsi, göndəriş etiketinin yaradılması, götürülmənin sifariş edilməsi və ya bağlamanın daşıyıcıya təhvil verilməsi ilə eyni əməliyyat deyil.

Tətbiqinizdə üç nəticəni ayrı saxlayın:

  • Sorğu qəbul edildi: API HTTP sorğunuza cavab qaytardı.
  • Qeydiyyat qəbul edildi: Xidmət ayrı-ayrı izləmə qeydini emal üçün qəbul etdi.
  • İzləmə məlumatı əlçatandır: Xidmətin tətbiqinizin əldə edə və ya qəbul edə biləcəyi göndəriş məlumatı var.

Bu nəticələr vahid “uğur” bayrağında birləşdirilməməlidir. Qəbul edilmiş izləmə nömrəsində hələ heç bir daşıyıcı hadisəsi olmaya bilər. Eyni şəkildə, paket sorğusu üçün uğurlu HTTP cavabı paketdəki hər bir elementin qəbul edildiyini təsdiqləmir; provayder tərəfindən müəyyən edilmiş tətbiq səviyyəli nəticə strukturunu yoxlayın.

1. Göndəriş identifikatorunuzu və API konfiqurasiyanızı hazırlayın

Qeydiyyat sorğusu göndərməzdən əvvəl göndərişin öz sisteminiz daxilində necə identifikasiya ediləcəyinə qərar verin. Yalnız sifariş identifikatoru adətən kifayət etmir, çünki bir sifariş bir neçə bağlamaya bölünə bilər. Hər göndəriş və ya bağlama üçün ayrıca daxili qeyd yaradın və həmin qeydi müvafiq sifarişlə əlaqələndirin.

Faydalı daxili qeydə aşağıdakı məlumatlar daxil ola bilər. Bunlar təklif olunan tətbiq sahələridir, 17TRACK sorğu sxemi deyil.

  • Daxili göndəriş ID-si: Bağlama üçün sabit identifikatorunuz.
  • Sifariş istinadı: Bağlamanın aid olduğu sifariş və ya icra qeydi.
  • İzləmə nömrəsi: Daşıyıcı tərəfindən verilən identifikator; başlanğıcdakı sıfırları qorumaq üçün mətn kimi saxlanılır.
  • Daşıyıcı məlumatı: Məlum olduğu halda, icra sisteminiz tərəfindən təqdim edilən daşıyıcı identifikatoru.
  • Provayder istinadı: Sonrakı əməliyyatlar üçün lazım olan və izləmə xidməti tərəfindən qaytarılan istənilən identifikator.
  • Qeydiyyat vəziyyəti: Təqdimatın gözləmədə, qəbul edilmiş, rədd edilmiş və ya uzlaşdırılmanı gözləyən olub-olmadığı barədə qeydiniz.
  • İzləmə vəziyyəti: Qeydiyyat vəziyyətindən ayrıca saxlanılan ən son göndəriş statusu.

Təqdim etməzdən əvvəl daxil edilən məlumatları yoxlayın. Təsadüfi boşluqları silin, lakin daşıyıcının formatı ilə bağlı fərziyyələrə əsaslanaraq izləmə nömrəsini yenidən yazmayın. Problemlərin araşdırılması üçün orijinal dəyəri qoruyun. Daşıyıcı məlumdursa, qeyri-rəsmi ekran adını göndərmək əvəzinə onu provayderin sənədləşdirilmiş daşıyıcı identifikatoru ilə uyğunlaşdırın.

Autentifikasiyanı server tərəfində konfiqurasiya edin. Giriş məlumatlarını mənbə kodundan kənarda saxlayın, işlənmə və istehsal konfiqurasiyalarını ayırın və sirlərdən jurnallarda istifadə etməyin. Əlaqəsiz inteqrasiyadan götürülmüş dəyərlərdən istifadə etmək əvəzinə sənədləşdirilmiş API versiyasını, sorğu limitlərini, paket limitlərini və hesab tələblərini təsdiqləyin.

2. Göndərişi qeydiyyata alın və element səviyyəsində nəticəni qeyd edin

İzləmə qeydini provayderinizin sənədlərində təsvir olunan qeydiyyat əməliyyatından istifadə etməklə təqdim edin. Yalnız tələb olunan sahələri və müəyyən məqsədə xidmət edən əlavə məlumatları daxil edin. Sifariş verilənlər bazanızda mövcud olduğu üçün müştəri adlarını, ünvanlarını və ya digər şəxsi məlumatları göndərməkdən çəkinin.

Aşağıdakı psevdokod tətbiq ardıcıllığını göstərir. Funksiya adları nümunə xarakterlidir; onlar API son nöqtələri və ya SDK metodları deyil.

shipment = load_internal_shipment(shipment_id)
validate_tracking_input(shipment)

result = tracking_adapter.register(shipment)

if result.item_accepted:
    save_registration_result(shipment_id, result)
elif result.outcome_unknown:
    schedule_registration_reconciliation(shipment_id)
else:
    save_registration_error(shipment_id, result)
    route_for_retry_or_correction(result)

Nə baş verdiyini izah etmək üçün kifayət qədər məlumatı saxlayın: daxili göndəriş ID-si, təqdimetmə vaxtı, cəhd nömrəsi, element səviyyəsində nəticə və provayder sorğu istinadı. Yalnız müvəqqəti işçi jurnalına güvənməyin. Müştəri xidməti və əməliyyat qruplarınız göndərişin uğurla sistemə daxil edilib-edilmədiyinə dair qalıcı cavaba ehtiyac duyur.

Paket təqdimatlarını ayrı-ayrılıqda idarə edin

API paket qeydiyyatını dəstəkləyirsə, qaytarılan hər elementi orijinal göndərişi ilə əlaqələndirin. HTTP sorğusu uğurla tamamlandığı üçün bütün paketi qəbul edilmiş kimi işarələməyin. Qəbul edilmiş elementləri saxlayın, rədd edilmiş elementləri ayırın və qeyri-müəyyən nəticələri ayrıca araşdırın.

Bu, bir səhv formatlı izləmə nömrəsinin artıq uğur qazanmış qeydlərin lazımsız şəkildə yenidən göndərilməsinə səbəb olmasının qarşısını alır. Həmçinin əməliyyat əməkdaşlarına düzəliş tələb edən qeydlərin konkret siyahısını təqdim edir.

Vaxt aşımını naməlum nəticə kimi qəbul edin

Vaxt aşımı qeydiyyatın uğursuz olduğunu sübut etmir. Bağlantınız kəsilməzdən əvvəl provayder sorğunu qəbul etmiş ola bilər. Yenidən kor-koranə göndərməzdən əvvəl nəticəni uzlaşdırmaq üçün sənədləşdirilmiş idempotentlik davranışından, dublikatların idarə edilməsindən və ya axtarış əməliyyatlarından istifadə edin.

Provayderin dublikatlarla bağlı davranışı aydın olmadıqda, avtomatik təkrar cəhdləri aktivləşdirməzdən əvvəl bunu nəzarət olunan qeydlərlə yoxlayın və müqaviləni təsdiqləyin. Daxildə qeydiyyat işlərinin dublikatlarının qarşısını almaq hələ də faydalıdır, lakin bu, uzaq xidmətin təkrarlanan sorğuları necə idarə etdiyini anlamağı əvəz etmir.

3. İlk izləmə məlumatlarının gəlməsinə şərait yaradın

Qeydiyyat qəbul edildikdən sonra izləmə məlumatları dərhal əlçatan olmaya bilər. Daşıyıcı fiziki emal hadisəsini qeyd etməzdən əvvəl etiket mövcud ola bilər. Məlumat çatışmazlığı izləmə nömrəsinin, daşıyıcı seçiminin və ya göndərişə xas axtarış tələblərinin yoxlanılmasını da tələb edə bilər.

Bu vəziyyəti açıq şəkildə göstərin. “Qeydiyyata alındı; izləmə məlumatı gözlənilir” ifadəsi “Yoldadır” və ya “Qeydiyyat uğursuz oldu” ifadələrindən daha dəqiqdir. Boş interfeysi doldurmaq üçün çatdırılma təxmini və ya hərəkət hadisəsi uydurmayın.

Qeyd boş qalmağa davam etdikdə, praktiki olaraq aşağıdakı ardıcıllıqla araşdırın:

  1. Ayrı-ayrı qeydiyyatın qəbul edildiyini təsdiqləyin.
  2. Təqdim edilmiş izləmə nömrəsini icra qeydi ilə müqayisə edin.
  3. Daşıyıcı uyğunlaşdırmasını və sənədləşdirilmiş əlavə axtarış tələblərini yoxlayın.
  4. Eyni göndəriş üçün daşıyıcının öz izləmə səhifəsini yoxlayın.
  5. Daşıyıcıda hadisələr olduğu halda inteqrasiyanızda görünmürsə, əldəetmə cavablarını yoxlayın və redaktə edilmiş diaqnostik məlumatlarla API provayderi ilə əlaqə saxlayın.

Sübut olmadan universal gözləmə müddətindən istifadə etməyin. Eskalasiya qaydaları göndəriş xidmətini, gözlənilən təhvil prosesini və öz əməliyyat öhdəliklərinizi əks etdirməlidir.

4. İzləmə məlumatlarını əldə edin və düzgün şərh edin

Qeyd əlçatan olduqdan sonra tələb olunan identifikatorlardan istifadə etməklə sənədləşdirilmiş izləmə məlumatları əməliyyatını çağırın. Qeydiyyat və əldəetmə əməliyyatlarının eyni sahələri qəbul etdiyini düşünməyin. Bəzi API müqavilələri izləmə nömrələrini, daşıyıcı identifikatorlarını və provayder tərəfindən yaradılmış qeyd istinadlarını fərqləndirir.

Tətbiqiniz üç məlumat qatını fərqləndirməlidir:

  • Göndəriş xülasəsi: İdarə panellərində, sifariş səhifələrində və əməliyyat filtrlərində istifadə olunan ümumi vəziyyət.
  • Hadisə tarixçəsi: Təqdim edildiyi halda hadisə təsvirləri, vaxt nişanları və yerlər daxil olmaqla ayrı-ayrı müşahidələr.
  • Əldəetmə metadatası: Tətbiqinizin məlumatı nə vaxt qəbul etdiyi və ya əldə etdiyi, həmçinin sorğunun uğurla tamamlanıb-tamamlanmadığı.

Uğurlu axtarış əldəetmə əməliyyatının uğurla başa çatması deməkdir. Bu, əvvəlki axtarışdan sonra bağlamanın hərəkət etdiyini göstərmir. Bildiriş və ya sonrakı iş axını yaratmazdan əvvəl qaytarılan izləmə məlumatlarını saxlanılan qeydlə müqayisə edin.

Hadisə vaxtını əldəetmə vaxtından ayrı saxlayın

Daşıyıcı hadisəsi ilə əlaqəli vaxtı sisteminizin həmin hadisəni qəbul etdiyi vaxtdan ayrıca saxlayın. Bu gün günortadan sonra əldə edilən hadisə daha əvvəlki skanı təsvir edə bilər. Onun hadisə vaxtını əldəetmə vaxtı ilə əvəz etmək köhnə yeniləmənin yeni fiziki hərəkət kimi görünməsinə səbəb olar.

Orijinal vaxt nişanını və təqdim edilmiş vaxt qurşağı fərqini qoruyun. Vaxt nişanlarını yalnız vaxt qurşağı məlum olduqda müqayisə üçün normallaşdırın. Hadisədə vaxt qurşağı məlumatı yoxdursa, serverinizin vaxt qurşağını səssizcə təyin etmək əvəzinə bu qeyri-müəyyənliyi saxlayın.

Normallaşdırılmış statusla yanaşı xam mənanı da qoruyun

Normallaşdırılmış status müxtəlif daşıyıcılar üzrə göndərişləri qruplaşdırmaq üçün faydalıdır, lakin orijinal hadisə təsviri əməliyyat problemini daha dəqiq izah edə bilər. Mümkün olduqda hər ikisini saxlayın. Yalnız ümumi istisna kateqoriyası dəstək əməkdaşına növbəti addımın ünvanı yoxlamaq, alıcı ilə əlaqə saxlamaq və ya başqa yeniləməni gözləmək olduğunu bildirməyə bilər.

Qeyri-müəyyən statusdan çatdırılma zəmanəti, təsdiqlənmiş itki və ya konkret gömrük nəticəsi çıxarmayın. Əsas məlumatlara və əməliyyat siyasətinizə uyğun olaraq məsələni eskalasiya edin.

5. Səsvermə və ya vebhuklar vasitəsilə qeydləri yeniləyin

Məlumatların bir dəfə əldə edilməsi bağlantını yoxlamaq üçün kifayətdir, lakin göndərişin görünürlüğünü qorumaq üçün kifayət deyil. İstehsal dizaynınızda yeniləmə mexanizmi olmalıdır. Seçdiyiniz provayder tərəfindən dəstəklənən mexanizmləri və onlara tətbiq olunan şərtləri təsdiqləyin.

Səsvermə zamanı tətbiqiniz cədvəl üzrə izləmə məlumatlarını sorğulayır. Sorğuları sənədləşdirilmiş limitlər daxilində planlaşdırın, dəyişməyən qeydləri səbəb olmadan təkrar-təkrar sorğulamaqdan çəkinin və təkrar cəhd edilə bilən uğursuzluqlar üçün geri çəkilmə mexanizmindən istifadə edin. Müştərinin sifariş səhifəsini açması avtomatik olaraq məhdudiyyətsiz yuxarı axın sorğusuna səbəb olmamalıdır; saxlanılan izləmə görünüşü səhifəni təmin edə, nəzarət olunan fon prosesi isə onu yeniləyə bilər.

Vebhuklardan istifadə edirsinizsə, daxil olan sorğuları provayderin sənədləşdirilmiş yoxlama mexanizmindən istifadə etməklə təsdiqləyin. Qəbul edilmiş mesajları vebhuk müqaviləsinə uyğun olaraq təsdiqləməzdən əvvəl saxlayın və ya etibarlı növbəyə yerləşdirin, sonra hadisələri asinxron şəkildə emal edin.

Sənədləşdirilmiş çatdırılma müqaviləsi əksini zəmanət vermədiyi halda, qəbul edicini dublikatlara və gözlənilməz gəliş sırasına dözümlü şəkildə qurun. Mümkün olduqda dublikatların qarşısını almaq üçün provayder hadisə identifikatorundan istifadə edin. Əks halda uyğun hadisə sahələrinə əsaslanan barmaq izi müəyyənləşdirin və sınaqdan keçirin; belə bir barmaq izinin məlumatlarınıza uyğunlaşdırılması tələb oluna biləcəyini nəzərə alın.

Vebhuk əsaslı inteqrasiya uzlaşdırma üçün nəzarət olunan əldəetmədən də istifadə edə bilər. Məsələn, bərpa işi qəbul edicinin işləmədiyi müddətdə təsirlənmiş qeydləri yoxlaya bilər. Bu, dayanıqlılıq nümunəsidir, tarif limitlərinə və ya provayderə xas təlimatlara məhəl qoymamaq icazəsi deyil.

6. İzləmə məlumatlarını təhlükəsiz biznes əməliyyatlarına çevirin

Müştəriyə yönəlmiş əməliyyatları işə salmazdan əvvəl daxili göndəriş qeydini yeniləyin. Təkrar hadisənin təkrar mesajlar yaratmaması üçün bildirişlərin və iş axını keçidlərinin davamlı qeydini saxlayın.

Biznes əməliyyatlarını hər API cavabına deyil, mənalı dəyişikliklərə uyğunlaşdırın. Yeni müşahidə edilmiş çatdırılma hadisəsi çatdırılma bildirişini əsaslandıra bilər. Eyni hadisəni ehtiva edən təkrar cavab isə bunu etməməlidir. İstisna daxili araşdırmanı əsaslandıra bilər, lakin müştəri mesajı hadisənin faktiki olaraq bildirdiyini əks etdirməlidir.

Göndəriş tamamlanmış hesab edildikdən sonra qəbul edilən hadisələri necə idarə edəcəyinizi müəyyənləşdirin. Xülasə terminal vəziyyətə çatdığı üçün hadisə tarixçəsini silməyin və ya bütün sonrakı yeniləmələri həmişəlik bloklamayın. Saxlama, uzlaşdırma və bildiriş qaydalarınız tamamlanmış iş axınlarını dəfələrlə yenidən açmadan qanuni düzəlişləri nəzərə almalıdır.

İş axınının 17TRACK inteqrasiyasına tətbiqi

Fərdi izləmə inteqrasiyası üçün müvafiq başlanğıc nöqtələri 17TRACK Tracking API səhifəsi və onun tərtibatçı sənədləridir. Təklifi qiymətləndirmək üçün məhsul səhifəsindən, faktiki inteqrasiya müqaviləsini müəyyənləşdirmək üçün isə sənədlərdən istifadə edin. İstehlakçı izləmə səhifələri API spesifikasiyalarını əvəz etmir.

Adapterinizi yazmazdan əvvəl autentifikasiya formatını, qeydiyyat və əldəetmə əməliyyatlarını, daşıyıcı identifikasiyası qaydalarını, element səviyyəsində cavab emalını və tətbiq olunan sorğu limitlərini təsdiqləyin. Vebhuk əsaslı emal üçün faydalı yük sxemini, yoxlama prosesini, təsdiqləmə tələblərini və təkrar cəhd davranışını da təsdiqləyin.

Provayderə xas bu detalları cavab sahələri ilə bağlı fərziyyələri sifariş sisteminizin hər yerinə yaymaq əvəzinə adapter daxilində saxlayın. Beləliklə tətbiqinizin qalan hissəsi qeydiyyat nəticəsi, göndəriş statusu, hadisə tarixçəsi və son uğurlu sinxronizasiya kimi daxili anlayışlarla işləyə bilər.

Bahalı səhvləri aşkarlayan işə salınmazdan əvvəl yoxlamalar

  • Qəbul edilib, lakin qeyd boşdur: İnterfeys bağlamanın hərəkətdə olduğunu deyil, izləmə məlumatlarının gözlənildiyini göstərir.
  • Qarışıq paket nəticəsi: Hər göndəriş öz saxlanılmış nəticəsini alır.
  • Təqdimatdan sonra vaxt aşımı: İşçi uğursuzluğu fərz etmək əvəzinə qeyri-müəyyən nəticəni uzlaşdırır.
  • Təkrar hadisə: Göndəriş qrafiki və müştəri bildirişi dublikatlardan qorunur.
  • Daha köhnə hadisə sonradan qəbul edilir: Daha yeni xülasəni kor-koranə əvəz etmədən hadisə qorunur.
  • Yuxarı axın xidməti əlçatmazdır: Müştəri səhifəsi uyğun yenilik göstəricisi ilə son saxlanılan nəticəni göstərə bilər.
  • Səhv daşıyıcı uyğunlaşdırması: Qeyd sənədləşdirilmiş bərpa yolu ilə düzəldilə bilər.
  • Bölünmüş sifariş: Hər bağlama öz izləmə vəziyyətini və hadisə tarixçəsini saxlayır.
  • Etimadnamələrin və ya faydalı yükün ifşası: Jurnallarda sirlər və lazımsız şəxsi məlumatlar sızdırılmadan diaqnostik istinadlar saxlanılır.

Praktiki tamamlanma meyarı sadəcə uğurlu qeydiyyat cavabını almaq deyil. Əsas meyar bağlamanı təqdimatdan yeniləmələrədək izləyə bilmək, boş və ya uğursuz nəticəni izah etmək və hadisələri itirmədən və ya müştəri əməliyyatlarını təkrarlamadan kəsilmiş emaldan bərpa olunmaqdır.

Tez-tez verilən suallar

İzləmə nömrəsinin qeydiyyata alınması göndəriş yaradırmı?

Bu təlimatda təsvir olunan iş axınında yox. İzləmə qeydiyyatı mövcud identifikatoru izləmə xidmətinə təqdim edir. Konkret API onları açıq şəkildə birləşdirmədiyi halda etiketin yaradılması, poçt haqqının ödənilməsi və daşıyıcı sifarişi ayrıca əməliyyatlardır.

Qeydiyyat uğurla başa çatdıqdan sonra izləmə məlumatları niyə boşdur?

Qeydiyyatın qəbul edilməsi və izləmə məlumatlarının əlçatan olması fərqli şərtlərdir. Daşıyıcı hələ hadisə qeyd etməmiş ola bilər və ya izləmə nömrəsinin, daşıyıcı uyğunlaşdırmasının və ya əlavə axtarış məlumatlarının yoxlanması tələb oluna bilər. Qeydi uğurla qeydiyyata alınmış hesab etməzdən əvvəl element səviyyəsində nəticəni yoxlayın.

Statusu hər dəfə əldə etdikdə göndərişi qeydiyyata almalıyam?

Təkrar qeydiyyatı standart yeniləmə mexanizmi kimi istifadə etməyin. Qəbul edilmiş qeydiyyat vəziyyətini saxlayın və sənədləşdirilmiş əldəetmə və ya yeniləmə mexanizmindən istifadə edin. Düzəlişlər, yenidən aktivləşdirmə və ya dublikat təqdimatlar üçün provayderin açıq qaydalarına əməl edin.

Səsvermədən, yoxsa vebhuklardan istifadə etməliyəm?

Sənədləşdirilmiş API müqaviləsinə və əməliyyat tələblərinizə uyğun mexanizmdən istifadə edin. Səsvermə nəzarət olunan sorğu cədvəli tələb edir. Vebhuklar təhlükəsiz, davamlı qəbul edici və dublikatlara davamlı emal tələb edir. Dəstəkləndiyi halda vebhuk yeniləmələri hədəfli uzlaşdırma ilə birlikdə praktiki bərpa yolu təmin edə bilər.

İzləmə nömrəsindən verilənlər bazamın yeganə göndəriş identifikatoru kimi istifadə edə bilərəmmi?

Bunun əvəzinə daxili göndəriş identifikatorundan istifadə edin. İzləmə nömrəsini və müvafiq daşıyıcı kontekstini həmin qeydin atributları kimi saxlayın. Bu, daxili göndərişinizin identifikatorunu dəyişmədən bölünmüş sifarişləri, düzəldilmiş izləmə nömrələrini və provayderə xas istinadları idarə etməyi asanlaşdırır.

Mənbələr

  • 17TRACK Tracking API — 17TRACK API inteqrasiyasını qiymətləndirmək üçün rəsmi məhsul giriş nöqtəsi.
  • 17TRACK API documentation — tətbiqə xas sorğu formatları, əməliyyatlar, cavablar və inteqrasiya tələbləri üçün rəsmi istinad. Bu təlimatdakı psevdokod və daxili sahə təklifləri tətbiq dizaynı nümunələridir, bu API müqaviləsindən sitatlar deyil.