UPS İzləmə API Sənədləri: Tərtibatçıların bilməli olduğu 7 əsas xüsusiyyət

UPS izləmə API sənədləri tərtibatçıya izləmə nömrəsindən etibarlı göndəriş statusu təcrübəsinə keçməyə kömək etdikdə ən faydalı olur. Araşdırılmalı yeddi sahə autentifikasiya, izləmə sorğuları, cavab sxemləri, hadisə tarixçəsi, xətaların idarə edilməsi, əməliyyat məhdudiyyətləri və sınaqdır. UPS birbaşa UPS inteqrasiyaları üçün öz tərtibatçı platformasını təqdim edir, halbuki 17TRACK Tracking API kimi çoxdaşıyıcılı xidmət bir inteqrasiyanın UPS və digər daşıyıcıları dəstəkləməli olduğu hallarda daha uyğun ola bilər.

Düzgün tətbiq qurduğunuz sistemdən asılıdır. Pərakəndə satıcıya sifariş səhifəsində çatdırılma yeniləmələri, anbar komandasına istisna xəbərdarlıqları, korporativ platformaya isə bir neçə daşıyıcı üzrə normallaşdırılmış izləmə məlumatları lazım ola bilər. Sənədləri bu istifadə ssenariləri vasitəsilə oxumaq ümumi bir səhvin qarşısını almağa kömək edir: uğurlu API cavabını tam göndəriş görünürlüğü həlli ilə eyniləşdirmək.

UPS izləmə API sənədləri hansı suallara cavab verməyə kömək etməlidir

Kod yazmazdan əvvəl dörd sualı dəqiqləşdirin:

• Yalnız UPS ilə inteqrasiya edirsiniz, yoxsa sistem bir neçə daşıyıcını izləyəcək?
• Sizə bağlamanın cari statusu, tam skan tarixçəsi, yoxsa hər ikisi lazımdır?
• Tətbiqiniz yeniləmələri tələb əsasında istəyəcək, bildirişlər qəbul edəcək, yoxsa hər iki üsuldan istifadə edəcək?
• Göndəriş gecikdikdə, çatdırıldıqda, geri qaytarıldıqda və ya hələ tapılmadıqda müştərilər və daxili komandalar nə görməlidir?

UPS sənədləri cari giriş məlumatları, dəstəklənən əməliyyatlar, sorğu tələbləri, cavab sahələri və kommersiya giriş şərtləri üçün əsas mənbədir. Bu məlumatlar API məhsuluna, hesab razılaşmasına və ya tərtibatçı platformasının versiyasına görə dəyişə bilər. Buna görə istehsal kodu köhnə kod nümunəsinə deyil, cari UPS tərtibatçı portalına əsaslanmalıdır.

Tərtibatçıların anlamalı olduğu 7 əsas xüsusiyyət

1. Autentifikasiya və tətbiqə giriş

Autentifikasiya ilk praktiki xüsusiyyətdir, çünki tətbiqin kimliyini necə sübut etdiyini və API-ni çağırmaq üçün icazəni necə əldə etdiyini müəyyən edir. UPS tərtibatçı sənədləri tətbiqin qeydiyyata alınması, giriş məlumatlarının yaradılması, giriş icazəsinin istənilməsi və tokenlərin idarə edilməsi üçün cari prosesi təqdim edir. Sənədlər UPS API-ləri üçün OAuth əsaslı girişi təsvir edir, lakin tərtibatçılar tətbiqdən əvvəl canlı portalda cari grant axınını, əhatə dairələrini, token müddətini və mühit tələblərini təsdiqləməlidirlər.

Giriş məlumatlarını server tərəfində saxlayın. Onlar brauzer JavaScript koduna, mobil tətbiq paketlərinə, açıq repozitoriyalara və ya müştərinin görə bildiyi izləmə səhifəsi koduna yerləşdirilməməlidir. Daha təhlükəsiz arxitekturada müştəriyə yönəlmiş tətbiq ilə UPS arasında backend xidməti yerləşir. Bu xidmət təhlükəsiz autentifikasiya edə, sorğu məhdudiyyətlərini tətbiq edə, sirləri açıqlamadan texniki nəticələri qeyd edə və yalnız ön hissənin ehtiyac duyduğu göndəriş məlumatlarını qaytara bilər.

Həmçinin UPS platforması ayrı mühitləri dəstəklədikdə inkişaf və istehsal giriş məlumatlarını ayırın. Yerləşdirmə yoxlama siyahısına sirrlərin saxlanması, rotasiyası, giriş sahibliyi, müddəti bitmiş tokenlərin idarə edilməsi və autentifikasiya uğursuzluqları artmağa başladıqda xəbərdarlıq daxil edilməlidir.

2. İzləmə nömrəsi sorğuları və daşıyıcı konteksti

İzləmə inteqrasiyasının izləmə identifikatorunu təqdim etmək və göndəriş məlumatlarını istəmək üçün proqnozlaşdırıla bilən üsula ehtiyacı var. Vacib suallar yalnız endpoint ünvanı ilə məhdudlaşmır. Buraya qəbul edilən izləmə nömrəsi formatı, sorğunun bir və ya bir neçə nömrəni dəstəkləyib-dəstəkləməməsi, daşıyıcının necə müəyyən edilməsi və nömrə natamam olduqda və ya hələ tanınmadıqda API-nin necə cavab verməsi daxildir.

İzləmə nömrəsinə bənzəyən hər simvol sətrinin UPS-ə aid olduğunu düşünməyin. Tətbiqiniz bir neçə göndərmə sistemindən etiketlər qəbul edirsə, daşıyıcı məlum olduqda onu ayrıca sahə kimi saxlayın. Daşıyıcıdan xəbərdar marşrutlaşdırma yanlış uyğunluqları azaldır və problemlərin araşdırılmasını asanlaşdırır. Bu, biznesiniz başqa daşıyıcı əlavə etdikdə gələcək genişlənmə üçün də təmiz yol yaradır.

Sorğu göndərməzdən əvvəl daxiletməni yoxlayın, lakin format dəyişdiyi və ya etiket yaxın zamanda yaradıldığı üçün düzgün identifikatoru rədd edən həddindən artıq sərt yoxlamadan qaçın. Əsas yoxlama mənbəyi API cavabı olaraq qalır. İlkin dəyəri, axtarış üçün istifadə edilən normallaşdırılmış dəyəri, daşıyıcını, sifariş istinadını və son uğurlu sorğunun vaxtını saxlayın.

3. Strukturlaşdırılmış cavab sxemi

Faydalı UPS izləmə API sənədləri göndəriş məlumatlarının necə təşkil edildiyini və hansı sahələrin məcburi olmadığını izah edir. Tərtibatçılar göndəriş identikliyi, cari status, status təsviri, skan vaxtları, məkanlar, çatdırılma təxminləri, xidmət məlumatları və bağlama səviyyəsində təfərrüatlar üçün cavab modelini araşdırmalıdırlar. Sahənin olmaması boş dəyər ehtiva edən sahə ilə eyni deyil və bunların heç biri avtomatik olaraq uğursuz göndəriş kimi qəbul edilməməlidir.

Bütün tətbiqi provayderə xas sahə adlarına birbaşa bağlamaq əvəzinə normallaşdırılmış daxili model yaradın. Məsələn, verilənlər bazanız göndəriş identifikatoru, daşıyıcı, cari status, son hadisə vaxtı, təxmini çatdırılma vaxtı, çatdırılma vaxtı, istisna kodu və provayderin ilkin yükünü saxlaya bilər. Normallaşdırılmış sahələr hesabatları və istifadəçi interfeyslərini dəstəkləyir; ilkin yük isə auditləri və gələcək uyğunlaşdırma dəyişikliklərini dəstəkləyir.

Təqdim edildikdə vaxt nişanlarını onların ofseti və ya saat qurşağı məlumatı ilə birlikdə qoruyun. Bir məkandakı skanı izləyicinin yerli vaxtında baş vermiş kimi göstərmək çaşdırıcı çatdırılma hekayələri yarada bilər. Eyni şəkildə, biznes qaydası sənədləşdirilməyənə qədər daşıyıcının ətraflı statusunu daha sadə etiketə çevirməyin.

4. Skan tarixçəsi və statusun şərhi

UPS tracking dəyəri çox vaxt tək cari etiketdən deyil, hadisələr ardıcıllığından ibarət olur. Bağlama etiket yaradılması, götürülmə, tranzit, gəliş skanı, istisna, çatdırılmaya çıxarılma hadisəsi və çatdırılma mərhələlərindən keçə bilər. İstifadəyə yararlı inteqrasiya hadisələri ardıcıllıqla saxlayır və mümkün olduqda onların ilkin təsvirlərini qoruyur.

Statusların uyğunlaşdırılması redaktə və əməliyyat mülahizəsi tələb edir. “Tranzitdə” bir neçə fərqli mərhələni əhatə edə bilər, “istisna” isə status adından daha konkret izah tələb edə bilər. Tətbiqiniz ən azı normal hərəkət, çatdırılma fəaliyyəti, çatdırılıb, istisna, geri qaytarılıb və hələ müəyyən edilə bilməyən statusları fərqləndirməlidir. Dəqiq uyğunlaşdırma yalnız ingiliscə təsvirlərə əsaslanan fərziyyələrə deyil, UPS tərəfindən sənədləşdirilmiş sahələrə və kodlara əsaslanmalıdır.

Müştəriyə yönəlmiş səhifələrdə ən son mənalı hadisəni, onun vaxtını və qısa izahını göstərin. Daxili əməliyyatlar üçün tam hadisə tarixçəsini və daşıyıcının ilkin ifadələrini saxlayın. Bu, dəstək əməkdaşlarına müştəridən sistemin artıq aldığı məlumatları təkrar istəmədən şikayəti araşdırmağa imkan verir.

5. Çatdırılma təxminləri və istisnaların idarə edilməsi

Tərtibatçılar çox vaxt normal ssenariyə diqqət yetirirlər, lakin çatdırılma təxminləri və istisnalar izləmə məlumatlarının praktikada faydalı olub-olmadığını müəyyən edir. Göndərişin təxmini olmaya bilər, təxmin dəyişə bilər və ya istisna normal hərəkəti müvəqqəti dayandıra bilər. Sənədlərdə bu halları göstərən sahələr və şərtlər yoxlanılmalıdır.

Müvafiq UPS xidmət şərtləri bu şərhi açıq şəkildə dəstəkləmədikcə təxmini zəmanət kimi təqdim etməyin. İstifadəçi interfeysində təxmini təxmin kimi etiketləyin və tarix və ya vaxt aralığını məlumatın dəstəklədiyi şəkildə dəqiq göstərin. API təxmin təqdim etmirsə, ümumi tranzit vaxtı qaydasından istifadə edərək təxmin uydurmaq əvəzinə “Hazırda çatdırılma təxmini mövcud deyil” kimi neytral mesaj göstərin.

İstisna iş axınları açıq şəkildə müəyyən edilməlidir. Yeni istisnanın e-poçt, yardım masası tapşırığı, sifariş idarəetmə əməliyyatı və ya yalnız status dəyişikliyinə səbəb olub-olmayacağına qərar verin. Təkrar sorğuların eyni xəbərdarlığı bir neçə dəfə göndərməməsi üçün deduplikasiya əlavə edin. Praktik qayda yeni bildiriş yaratmazdan əvvəl hadisə identifikatorunu və ya hadisə vaxtı, status və təsvirin sabit kombinasiyasını müqayisə etməkdir.

6. Xətalar, təkrar cəhdlər və əməliyyat məhdudiyyətləri

API sənədləri yalnız uğurlu nümunələr siyahısı kimi deyil, əməliyyat müqaviləsi kimi oxunmalıdır. Tərtibatçılar autentifikasiya xətalarını, etibarsız sorğuları, naməlum izləmə nömrələrini, müvəqqəti xidmət nasazlıqlarını, vaxt aşımını və tarif limiti cavablarını anlamalıdırlar. Hər kateqoriya fərqli cavab tələb edir.

• Autentifikasiya uğursuzluqları mühəndislik xəbərdarlığı yaratmalı və qeyri-müəyyən müddətə təkrar edilməməlidir.
• Yoxlama xətaları sorğunu düzəltmək üçün kifayət qədər kontekstlə qeyd edilməlidir.
• Müvəqqəti nasazlıqlar eksponensial geriçəkilmə və maksimum cəhd sayı ilə yenidən yoxlanıla bilər.
• Naməlum və ya yeni yaradılmış izləmə nömrələri daha sonra yenidən yoxlanıla bilər, lakin itirilmiş kimi təsnif edilməməlidir.
• Tarif limiti cavabları sorğu cədvəlini yavaşlatmalı və cari UPS sənədlərində göstərilən məhdudiyyətlərə əməl etməlidir.

Vaxt aşımı, dövrə kəsiciləri, sorğu identifikatorları və strukturlaşdırılmış jurnallardan istifadə edin. Giriş tokenlərini və lazımsız şəxsi məlumatları istisna etməklə provayderin cavab statusunu, daxili göndəriş identifikatorunu və vaxt nişanını saxlayın. Sənədlərdə cavab başlıqları və ya təkrar cəhd təlimatları göstərilibsə, ümumi siyasət tətbiq etmək əvəzinə həmin təlimatları daxil edin.

7. Sınaq, monitorinq və istehsala hazırlıq

İzləmə API inteqrasiyası birdən çox uğurlu izləmə nömrəsi ilə sınaqdan keçirilməlidir. Yeni yaradılmış etiket, bir neçə skanı olan göndəriş, istisna, çatdırılmış bağlama, naməlum nömrə, müddəti bitmiş giriş məlumatı, səhv formatlı sorğu, vaxt aşımı və təkrarlanan hadisə üçün sınaq halları yaradın. Dəqiq sınaq məlumatları və sandbox davranışı UPS tərtibatçı mühitində təsdiqlənməlidir, çünki canlı göndəriş məlumatları və sınaq mühitləri həmişə eyni davranmır.

Həm texniki, həm də biznes nəticələrini izləyin. Texniki göstəricilərə sorğu həcmi, gecikmə, vaxt aşımı dərəcəsi, autentifikasiya uğursuzluqları, provayder xətası dərəcəsi və təkrar cəhd sayı daxildir. Biznes göstəricilərinə son hadisəsi olan göndərişlərin faizi, yenilənməmiş ən köhnə göndərişin yaşı və istisnadan təsirlənən sifarişlərin sayı daxildir. Sorğu və ya hadisə emalı dayanıbsa, xidmət aşağı HTTP xətası dərəcəsinə malik olmaqla yanaşı köhnəlmiş izləmə məlumatları təqdim edə bilər.

İşə salınmazdan əvvəl sorğuları necə dayandırmaq, giriş məlumatlarını necə dəyişmək, uğursuz cavabları necə yenidən oynatmaq, səhv status uyğunluğunu necə düzəltmək və UPS dəstəyi ilə necə əlaqə saxlamaq barədə sənədləşdirin. Araşdırma üçün lazım olduqda provayderin ilkin yükünü nəzarətli saxlama müddəti ərzində qoruyun və məxfilik və məlumatların saxlanması tələblərini müvafiq məsul şəxslə nəzərdən keçirin.

Birbaşa UPS inteqrasiyası, yoxsa çoxdaşıyıcılı API?

UPS əhatə dairəsində yeganə daşıyıcı olduqda, komanda daşıyıcıya xas modeli idarə etmək istədikdə və tələb olunan UPS API giriş imkanı mövcud olduqda birbaşa UPS inteqrasiyası məntiqli seçimdir. Bu, UPS terminologiyasına və əməliyyat proseslərinə yaxın uyğunluq təmin edə bilər.

Eyni tətbiq UPS, poçt operatorları və digər logistika təminatçılarından bağlamaları izləməli olduqda çoxdaşıyıcılı API daha uyğun arxitektura seçimi ola bilər. Texniki qərar qəbul edilməzdən əvvəl 17TRACK API documentation üçün cari autentifikasiya modeli, dəstəklənən əməliyyatlar, cavab strukturu, webhook davranışı, istifadə şərtləri və daşıyıcı əhatəsi nəzərdən keçirilməlidir. Bu ssenaridə onun dəyəri sənədlərə ehtiyacı aradan qaldırması deyil; inkişaf komandasının bir inteqrasiya qatını bir neçə daşıyıcıya xas bağlantının saxlanması xərci ilə müqayisə edə bilməsidir.

Müqayisəni konsepsiyanın sübutu ilə aparın. Hər seçim üçün eyni göndəriş həyat dövründən istifadə edin və tətbiq səylərini, sahələrin tamlığını, hadisələrin yeniliyini, təkrar cəhd davranışını, webhook və ya sorğu tələblərini, müşahidəolunmanı və daşıyıcı cavabını dəyişdikdə tələb olunan işi ölçün. Provayderi yalnız nümunə sorğunun qısa olmasına görə seçməyin. Daha uyğun seçim tətbiqinizin təqdim etməli olduğu əməliyyat nəticəsini dəstəkləyəndir.

Praktik tətbiq ardıcıllığı

1. Müştəri izləmə səhifəsi və ya istisna növbəsi kimi istifadəçi və əməliyyat nəticələrini müəyyənləşdirin.
2. Əhatə dairəsinin yalnız UPS, yoxsa çoxdaşıyıcılı olduğunu təsdiqləyin.
3. Autentifikasiya, izləmə sorğuları, cavab sahələri, xətalar, məhdudiyyətlər və sınaq üçün cari rəsmi sənədləri oxuyun.
4. Provayderdən asılı olmayan göndəriş və hadisə modeli yaradın.
5. Təhlükəsiz server tərəfli autentifikasiya və daxiletmə yoxlamasını tətbiq edin.
6. İlkin cavabları və normallaşdırılmış sahələri ayrıca saxlayın.
7. Deduplikasiya və geriçəkilmə ilə sorğu və ya hadisə qəbulunu əlavə edin.
8. Normal, gecikmiş, istisna, naməlum və uğursuz sorğuları sınaqdan keçirin.
9. Yenilik, uğursuzluqlar və köhnəlmiş göndərişlər üçün monitorinqlə işə başlayın.

Bu ardıcıllıq API çağırışının bütün dizayna çevrilməsinin qarşısını alır. İzləmə davamlı məlumat prosesidir: tətbiq hadisələri əldə etməli, onları diqqətlə şərh etməli, aydın təqdim etməli və provayder və ya şəbəkə əlçatmaz olduqda bərpa olunmalıdır.

FAQ

UPS izləmə API sənədlərində əvvəlcə nəyi oxumalıyam?

Autentifikasiya və izləmə əməliyyatından başlayın. Sonra sorğu tələblərini, cavab sahələrini, xəta davranışını, istifadə məhdudiyyətlərini və sınaq təlimatlarını nəzərdən keçirin. Bu bölmələr tam inteqrasiyaya sərmayə qoymazdan əvvəl API-nin təhlükəsizlik modelinizə və məlumat tələblərinizə uyğun olub-olmadığını göstərir.

Müştəriyə yönəlmiş izləmə səhifəsi üçün UPS izləmə API-sindən istifadə edə bilərəm?

Bəli, API müştəriyə yönəlmiş səhifə üçün məlumat təmin edə bilər, lakin API giriş məlumatlarını brauzerdə açıqlamaq əvəzinə səhifə backend vasitəsilə təqdim edilməlidir. Səhifəni cari statusu, skan tarixçəsini, təxminləri və istisnaları fərqləndirəcək şəkildə dizayn edin və təxminləri zəmanət kimi təqdim etməkdən çəkinin.

İzləmə nömrələri davamlı olaraq sorğulanmalıdır?

Mütləq deyil. Sorğu tezliyi göndəriş mərhələsini, biznes aktuallığını, sənədləşdirilmiş istifadə məhdudiyyətlərini və hadisə əsaslı seçimin mövcud olub-olmadığını əks etdirməlidir. Dəyişməyən göndərişlər üçün geriçəkilmədən istifadə edin və çatdırılmadan və ya son geri qaytarılma statusundan sonra sorğunu dayandırın və ya azaldın.

Naməlum izləmə nömrəsi ilə itirilmiş bağlama arasındakı fərq nədir?

Naməlum izləmə nömrəsi cari sorğunun tanınmış göndəriş nəticəsi qaytarmadığını bildirir. Nömrə yeni yaradılmış, səhv daxil edilmiş, yanlış daşıyıcıya yönləndirilmiş və ya müvəqqəti əlçatmaz ola bilər. Ayrı biznes prosesi və dəstəkləyici sübut olmadan onu itirilmiş kimi etiketləmək olmaz.

Çoxdaşıyıcılı izləmə API-sini nə vaxt nəzərdən keçirməyə dəyər?

Tətbiqiniz bir neçə daşıyıcını dəstəkləməli olduqda və ya ayrıca autentifikasiya, sxemlər, status uyğunluqları və xəta siyasətlərinin saxlanması əhəmiyyətli əməliyyat işi yaradıqda onu qiymətləndirməyə dəyər. Provayderləri real göndəriş ssenariləri ilə müqayisə edin və cari daşıyıcı və xüsusiyyət məlumatlarını onların rəsmi sənədlərində yoxlayın.

Mənbələr

• UPS Developer Portal — UPS API məhsulları, tətbiq qurulması, autentifikasiya və tərtibatçı resursları üçün rəsmi giriş nöqtəsi.
• UPS Tracking — rəsmi UPS izləmə xidməti və terminologiya istinadı.
• 17TRACK Tracking API — çoxdaşıyıcılı izləmə inteqrasiyasını qiymətləndirmək üçün rəsmi məhsul səhifəsi.
• 17TRACK API Documentation — cari API təfərrüatları və inteqrasiya tələbləri üçün rəsmi tərtibatçı sənədləri.