Skip to main content
Ana səhifəBloqBələdçilərAPI vasitəsilə izləmə nömrəsini necə qeydiyyatdan keçirmək olar: sorğu sahələri, daşıyıcı kodları və cavablar

API vasitəsilə izləmə nömrəsini necə qeydiyyatdan keçirmək olar: sorğu sahələri, daşıyıcı kodları və cavablar

17TRACK

API vasitəsilə izləmə nömrəsini qeydiyyatdan keçirmək üçün göndərişin izləmə nömrəsini və tələb olunduqda daşıyıcı identifikatorunu ehtiva edən autentifikasiya edilmiş qeydiyyat sorğusu göndərin. Sonra yalnız HTTP statusunu deyil, təqdim edilmiş hər bir göndəriş üzrə cavabı yoxlayın və qeydiyyatın uğurlu, uğursuz və ya qeyri-müəyyən olaraq qaldığını yadda saxlayın. Qeydiyyat izləmə prosesini başladır; bu, daşıyıcının bağlamanı skan etdiyini və ya izləmə hadisələrinin artıq mövcud olduğunu sübut etmir.

API sorğu sahələri vasitəsilə izləmə nömrəsini necə qeydiyyatdan keçirmək olar

Bu təlimat sifarişlərin idarə edilməsi sistemini, anbar tətbiqini və ya e-ticarət platformasını izləmə API-sinə qoşan tərtibatçılar üçündür. Burada konkret inteqrasiya nümunəsi kimi 17TRACK istifadə olunur və seçdiyiniz API versiyası üzrə hansı məlumatların sənədlərlə yoxlanmalı olduğu izah edilir.

Qeydiyyat nə edir və nə etmir

Qeydiyyat sorğusu izləmə xidmətinə hansı göndərişi izləməli olduğunu bildirir. Bu, göndəriş etiketi almaqdan, götürülmə sifariş etməkdən və ya daşıyıcıdan göndəriş yaratmasını istəməkdən fərqlidir. Tipik inteqrasiyada göndəriş prosesi əvvəlcə izləmə nömrəsi yaradır, tətbiqiniz isə daha sonra həmin nömrəni qeydiyyatdan keçirir.

Tətbiqinizdə bu üç hadisəni ayrı saxlayın:

  • Göndəriş yaradıldı: göndəriş sisteminiz izləmə nömrəsi təyin edib.
  • Qeydiyyat qəbul edildi: izləmə xidməti göndərişi izləmək üçün qəbul edib.
  • İzləmə məlumatı alındı: daşıyıcı hadisələri izləmə xidməti vasitəsilə əlçatan olub.

Yalnız qeydiyyat uğurlu olduğuna görə sifarişi “yoldadır” statusuna keçirməyin. Yeni yaradılmış etiketin hələ fiziki qəbul skanı olmaya bilər. Müştəriyə göstərilən göndəriş statusu qeydiyyat cavabından deyil, status-xəritələmə qaydalarınız vasitəsilə şərh edilmiş izləmə hadisələrindən götürülməlidir.

17TRACK inteqrasiyaları üçün Tracking API overview ilə başlayın və son nöqtələr, sahə tərifləri, autentifikasiya və cavab kodları üzrə əsas mənbə kimi official API documentation istifadə edin. Aşağıdakı nümunələr nəticələrin əldə edilməsi və ya yeniləmələrin alınması kimi ayrıca tapşırıqlara deyil, qeydiyyata fokuslanır.

API çağırışını yazmazdan əvvəl sorğu sahələrini hazırlayın

Ən faydalı hazırlıq göndəriş sisteminizlə izləmə inteqrasiyanız arasında kiçik sahə müqaviləsi yaratmaqdır. Hər dəyərin haradan gəldiyini, çatışmaya bilib-bilmədiyini və necə yoxlanacağını müəyyənləşdirin.

Sahə və ya dəyərMəqsədTətbiq qaydası
İzləmə nömrəsiİzlənəcək göndərişi müəyyənləşdirir.Sətir kimi saxlayın və ötürün; başlanğıc sıfırlarını qoruyun.
Daşıyıcı identifikatoruİzləmə provayderinin sistemində daşıyıcını müəyyənləşdirir.Daxili anbar kodundan deyil, provayderin sənədləşdirilmiş identifikatorundan istifadə edin.
Daxili istinadQeydiyyatı göndəriş qeydinizlə əlaqələndirir.Mövcuddursa, dəstəklənən istinad sahəsindən istifadə edin; buna baxmayaraq öz verilənlər bazanızdakı uyğunluğu qoruyun.
Əlavə identifikasiya məlumatlarıDaşıyıcı yalnız izləmə nömrəsindən əlavə məlumat tələb etdikdə göndərişi müəyyənləşdirməyə kömək edə bilər.Yalnız həmin inteqrasiya və daşıyıcı üçün sənədləşdirilmiş sahələri göndərin.
API məlumatıÇağırışı edən hesabı autentifikasiya edir.Serverdə saxlayın və tətbiq jurnallarına daxil etməyin.

İzləmə nömrəsinə identifikator kimi yanaşın

İzləmə nömrəsini heç vaxt tam ədədə çevirməyin. Rəqəmsal çevirmə başlanğıc sıfırlarını silə bilər və bəzi proqramlaşdırma mühitlərində böyük dəyərlər dəqiqliyini itirə bilər. Təsadüfi kənar boşluqları silin, lakin müvafiq sənədlər və ya daşıyıcı formatı belə normallaşdırmanı dəstəkləmədikcə durğu işarələrini silməyin və hərf registrini dəyişməyin.

API-ni çağırmazdan əvvəl aşkar giriş xətalarını yoxlayın: boş sətirlər, gözlənilməz sətir keçidləri və izləmə nömrəsi sahəsinə köçürülmüş sifariş nömrəsi. Bütün daşıyıcılar üçün vahid uzunluq və ya simvol qaydası tətbiq etməkdən çəkinin. Bir daşıyıcıya uyğun olan yoxlama qaydası digərindən gələn düzgün nömrələri rədd edə bilər.

Sifariş istinadlarını göndəriş identifikatorlarından ayrı saxlayın

Sifarişdə bir neçə bağlama ola bilər və əvəzləyici göndəriş başqa izləmə nömrəsi yarada bilər. Hər sifariş üçün bir izləmə nömrəsi olduğunu fərz etmək əvəzinə qeydiyyatı göndəriş və ya bağlama səviyyəsində modelləşdirin.

Provayder tərəfindən dəstəklənən etiket və ya istinad sahəsindən istifadə edirsinizsə, müştərinin e-poçt ünvanı və ya küçə ünvanı əvəzinə anonim göndəriş istinadına üstünlük verin. Öz verilənlər bazanız sifarişlər, göndərişlər, izləmə nömrələri və daşıyıcı uyğunluqları arasındakı əsas əlaqə olaraq qalmalıdır.

Düzgün daşıyıcı kodunu seçin

Daşıyıcı kodu mütləq universal sənaye identifikatoru deyil. İzləmə platformasının tanıdığı dəyər göndəriş proqramınızda saxlanılan daşıyıcı adından fərqlənə bilər. Hətta rəqəmsal kodlardan istifadə edən iki sistem eyni daşıyıcıya fərqli nömrələr təyin edə bilər.

Göndəriş xidmətinizdən izləmə provayderinin daşıyıcı identifikatoruna açıq uyğunluq saxlayın. Lazım gəldikdə daşıyıcının regional əməliyyatını və ya xidmətini daha geniş brendindən fərqləndirin. Yalnız göstərilən ada əsaslanan uyğunluq, göndəriş sistemləri ləqəblərdən istifadə etdikdə qeyri-müəyyən ola bilər.

  • Daşıyıcı məlumdursa: dəstəkləndikdə sənədləşdirilmiş daşıyıcı identifikatorundan istifadə edin, xüsusilə izləmə nömrəsi formatları üst-üstə düşdükdə.
  • Daşıyıcı məlum deyilsə: avtomatik aşkarlamadan yalnız sənədləşdirilmiş mexanizm vasitəsilə istifadə edin. Buraxılmış sahənin, boş sətirin, sıfırın və null dəyərinin eyni məna daşıdığını fərz etməyin.
  • Nəticə səhv görünürsə: eyni nömrəni təkrar-təkrar qeydiyyatdan keçirməzdən əvvəl ilkin etiketi, göndəriş xidmətini və uyğunluğu yoxlayın.

Avtomatik aşkarlama faydalıdır, lakin konkret daşıyıcının göndərişi fiziki olaraq saxladığına sübut deyil. Eynilə, düzgün daşıyıcı kodu təqdim edilmiş izləmə nömrəsinin həmin daşıyıcıya aid olmasına zəmanət vermir.

Daşıyıcı uyğunluqlarını tətbiq koduna səpələmək əvəzinə konfiqurasiya edilə bilən saxlayın. Uyğunluğun sonuncu dəfə nə vaxt yoxlanıldığını qeyd edin və onu dəyişdirdikdə məlum göndərişi reqressiya testlərinə daxil edin.

Nümunə: 17TRACK qeydiyyat sorğusu göndərin

Aşağıdakı nümunə 17TRACK v2.2 qeydiyyat son nöqtəsini, 17token autentifikasiya başlığını və bir izləmə nömrəsi obyektindən ibarət massivi nümayiş etdirir. Yerləşdirmədən əvvəl bu versiyanın və onun sorğu tələblərinin hesabınıza və rəsmi sənədlərə uyğun olduğunu təsdiqləyin. İzləmə nömrəsi yer tutucudur və real göndəriş identifikatoru ilə əvəz edilməlidir.

curl --request POST \
  --url 'https://api.17track.net/track/v2.2/register' \
  --header "17token: ${TRACKING_API_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data '[
    {
      "number": "YOUR_TRACKING_NUMBER"
    }
  ]'

Bu minimal nümunə daşıyıcı seçimini və ya daşıyıcıya xas əlavə sahələri nümayiş etdirmir. Daşıyıcı sahəsi buraxıldıqda aşkarlamanın necə işlədiyini və göndərişinizin əlavə məlumat tələb edib-etmədiyini müəyyənləşdirmək üçün qeydiyyat sənədlərini yoxlayın. Daşıyıcı təqdim edirsinizsə, sənədləşdirilmiş carrier sahəsindən və həmin API versiyasının gözlədiyi identifikatordan istifadə edin.

Bu sorğunu server tərəfli mühitdən icra edin. Tokeni ictimai mağazaya, brauzer skriptinə və ya müştərilərə paylanan mobil tətbiqə yerləşdirməyin. Lokal nümunə üçün mühit dəyişənindən istifadə rahatdır; istehsal yerləşdirmələrində təşkilatınızın məxfi məlumatların idarə edilməsi nəzarətlərindən istifadə edilməlidir.

Həcmi artırmazdan əvvəl bir məlum göndərişi test edin və tam cavabı yoxlayın. Sonra etibarsız giriş və həm etibarlı, həm də etibarsız elementlərdən ibarət paket test edin. Bu yoxlamalar inteqrasiyanızın sadəcə HTTP uğur cavabını tanımaq əvəzinə element səviyyəsində nəticələri həqiqətən idarə edib-etmədiyini göstərir.

Cavabı üç səviyyədə oxuyun

Etibarlı cavab emalçısı üç ayrı suala cavab verir: sorğu xidmətə çatdımı, xidmət əməliyyatı qəbul etdimi və hər bir göndərişlə nə baş verdi?

1. HTTP və nəqliyyat nəticəsi

Bağlantı vaxt aşımı, TLS xətası və ya yarımçıq cavab serverin sorğunu emal edib-etmədiyini mütləq göstərmir. Nəticəni uyğunlaşdıra bilənədək onu qeyri-müəyyən kimi işarələyin. HTTP uğur statusu HTTP mübadiləsinin uğurlu olduğunu təsdiqləyir, lakin yenə də tətbiq cavabını yoxlamalısınız.

2. Sorğu səviyyəsində nəticə

API-nin sənədləşdirilmiş üst səviyyəli nəticəsini və xəta sahələrini yoxlayın. Autentifikasiya xətaları, səhv JSON və hesab məhdudiyyətləri fərqli tədbirlər tələb edir. Hər uğursuzluğu “izləmə əlçatan deyil” ifadəsinə endirmək əvəzinə provayderin ilkin xəta kodunu və mesajını saxlayın.

Rəqəmsal tətbiq kodunun HTTP status kodu ilə eyni məna daşıdığını fərz etməyin. Onların mənaları müxtəlif təbəqələrdən gəlir və ayrı-ayrılıqda şərh edilməlidir.

3. Göndəriş səviyyəsində nəticə

Paket qeydiyyatı zamanı təqdim edilmiş hər bir elementi nəzərə alın. Cavab qəbul edilmiş və rədd edilmiş göndərişləri fərqləndirə bilər; parseriniz seçilmiş versiya üçün sənədləşdirilmiş dəqiq sxemə əməl etməlidir. Yalnız bir element uğurlu oldu deyə bütün paketi qeydiyyatdan keçmiş kimi işarələməyin.

Provayder cavablarını öz sabit tətbiq vəziyyətlərinizə normallaşdırın. Məsələn, verilənlər bazanızda accepted, rejected və uncertain istifadə oluna bilər. Bunlar təklif olunan daxili vəziyyətlərdir, 17TRACK cavablarının hərfi dəyərləri deyil. Tərtibatçıların uyğunsuzluqları araşdıra bilməsi üçün provayderin ilkin cavabını uyğun saxlama və giriş siyasəti çərçivəsində əlçatan saxlayın.

Faydalı qeydiyyat qeydinə daxili göndəriş ID-si, təqdim edilmiş nömrə, daşıyıcı seçimi, cəhd vaxtı, API versiyası, nəticə və provayderin xəta detalları daxildir. Qeydiyyat statusunu çatdırılma statusundan ayrı saxlayın.

Sonsuz dövr yaratmadan təkrar cəhdləri idarə edin

Təkrar cəhd siyasəti sadəcə istisnanın baş verib-verməməsindən deyil, xətadan asılı olmalıdır.

  • Etibarsız giriş: təkrar cəhddən əvvəl sahəni düzəldin. Dəyişdirilməmiş səhv sorğunun təkrarlanmasının fayda verməsi ehtimalı azdır.
  • Autentifikasiya xətası: məlumatları və hesab konfiqurasiyasını yoxlayın. Eyni uğursuz paketi dəfələrlə göndərməkdən çəkinin.
  • Tezlik məhdudiyyəti: sənədləşdirilmiş limitlərə və tətbiq olunan təkrar cəhd təlimatlarına əməl edin. Dərhal paralel təkrar cəhdlər əvəzinə məhdudlaşdırılmış geriçəkilmədən istifadə edin.
  • Müvəqqəti xidmət xətası: müəyyən edilmiş cəhd və vaxt büdcəsi daxilində yenidən cəhd edin.
  • Göndərişdən sonra vaxt aşımı: ilk cəhdin uğursuz olduğunu fərz etməzdən əvvəl sənədləşdirilmiş API davranışından istifadə edərək göndərişin qeydiyyat vəziyyətini uyğunlaşdırın.
  • Dublikatla əlaqəli cavab: göndərişin artıq qeydiyyatdan keçib-keçmədiyini və tətbiq qeydinizlə düzgün əlaqələndirilib-əlaqələndirilmədiyini yoxlayın.

Sənədlər bu davranışı müəyyən etmədikcə qeydiyyatın idempotent olduğunu fərz etməyin. Tətbiq səviyyəsində dublikatların aradan qaldırılması təsadüfi təkrar göndərişləri azaldır, lakin provayderin dublikatlarla işləmə siyasətini müəyyən etmir.

Göndəriş modelinizə uyğun daxili unikallıq qaydasından istifadə edin. Yalnız izləmə nömrəsi daşıyıcılar və uzunmüddətli saxlama dövrləri arasında kifayət qədər daimi açar olmaya bilər. Daşıyıcı kontekstini və öz göndəriş identifikatorunuzu qoruyun, əvəzləyici və düzəldilmiş nömrələrin necə idarə edildiyini sənədləşdirin.

Qeydiyyatı izləmə yeniləmələrindən ayrı monitorinq edin

API monitorinqi inteqrasiya xətası ilə sadəcə yeni daşıyıcı hadisəsi olmayan göndərişi fərqləndirməlidir. Bu hallar fərqli məsul şəxslər və fərqli düzəlişlər tələb edir.

Qeydiyyat üçün qəbul və rədd saylarını, xəta kateqoriyalarını, qeyri-müəyyən nəticələri, təkrar cəhd növbəsini və cavab gecikməsini monitorinq edin. Sonrakı izləmə üçün yeniləmələrin alınması və ya əldə edilməməsi xətalarını ayrıca izləyin. Normal trafiki və provayderin sənədləşdirilmiş əməliyyat limitlərini başa düşməyənədək rəqəmsal xəbərdarlıq hədləri təyin etməkdən çəkinin.

Praktik istehsal yoxlaması aşağıdakı suallara cavab verməlidir:

  1. İzləmə gözləyən hər bir göndərişin qeydiyyat qeydi varmı?
  2. Qəbul edilmiş hər bir qeydiyyat düzgün bağlamaya qədər izlənə bilirmi?
  3. Rədd edilmiş elementlər əsas məlumatları düzəldə biləcək şəxsə yönləndirilirmi?
  4. Qeyri-müəyyən sorğular tərk edilmək və ya sonsuz təkrar edilmək əvəzinə uyğunlaşdırılırmı?
  5. Müştəriyə göstərilən statuslar qeydiyyat qəbulundan deyil, göndəriş hadisələrindən əldə olunurmu?
  6. Məlumatlar və lazımsız şəxsi məlumatlar jurnallardan çıxarılırmı?

E-ticarət əməliyyatlarında əməliyyat təhvil-təslimi API çağırışı qədər vacibdir. Tərtibatçılar nəqliyyat və təhlil xətalarına cavabdeh olmalıdır; göndəriş və ya icra komandaları səhv etiketləri, daşıyıcı uyğunluqlarını və çatışmayan göndəriş məlumatlarını araşdıra bilməlidir.

FAQ

İlk daşıyıcı skanından əvvəl izləmə nömrəsini qeydiyyatdan keçirə bilərəmmi?

Qeydiyyat və daşıyıcı skanları ayrı hadisələrdir. Xidmət öz yoxlama qaydalarına əsasən izləmə hadisələri əlçatan olmamışdan əvvəl nömrəni qəbul edə bilər. Qəbulu daşıyıcının bağlamanı aldığına sübut kimi şərh etməyin.

Həmişə daşıyıcı kodu təqdim etməliyəm?

Bu, API-nin sənədləşdirilmiş aşkarlama davranışından və göndərişdən asılıdır. Daşıyıcı məlumdursa, açıq və düzgün uyğunlaşdırılmış identifikator qeyri-müəyyənliyi azalda bilər. Məlum deyilsə, daşıyıcı dəyəri uydurmaq əvəzinə sənədləşdirilmiş avtomatik aşkarlama metodundan istifadə edin.

Göndəriş uğursuz olduğu halda API niyə HTTP uğuru qaytardı?

HTTP sorğusu uğurlu ola bilər, tətbiq isə ayrı-ayrı elementi rədd edə bilər. Üst səviyyəli tətbiq nəticəsini və göndəriş səviyyəli nəticələri oxuyun. Bu fərq paket sorğuları üçün xüsusilə vacibdir.

Qeydiyyat sorğusunun vaxtı bitdikdə nə etməliyəm?

Nəticəni qeyri-müəyyən hesab edin. Bağlantı uğursuz olmamışdan əvvəl server sorğunu emal etmiş ola bilər. Provayderin sənədləşdirilmiş dublikat davranışını və mövcud qeydiyyat və ya izləmə axtarışı metodlarını yoxlayın, sonra məhdudlaşdırılmış siyasət çərçivəsində uyğunlaşdırın və ya yenidən cəhd edin.

Qeydiyyat izləmə bildirişlərini avtomatik konfiqurasiya edirmi?

Bunu fərz etməyin. Qeydiyyat, izləmənin əldə edilməsi və webhook konfiqurasiyası ayrı inteqrasiya məsələləridir. Müvafiq sənədləri yoxlayın və müştəri bildirişlərinə etibar etməzdən əvvəl tam yeniləmə yolunu test edin.

Mənbələr

  • 17TRACK API documentation — qeydiyyat son nöqtələri, autentifikasiya, sorğu sahələri, daşıyıcı identifikatorları, cavab sxemləri və xəta idarəetməsi üçün istinad. Tətbiq detallarını yerləşdirdiyiniz API versiyasına uyğunlaşdırın.
  • 17TRACK Tracking API overview — izləmə API məhsulu və tərtibatçı inteqrasiyası resursları üçün rəsmi başlanğıc nöqtəsi.