UPS İzləmə API-si: Başlamaq üçün yeni başlayanlar üçün bələdçi

UPS Tracking API biznesə göndəriş statusunu əldə etməyə və çatdırılma yeniləmələrini öz veb-saytında, tətbiqində, sifarişlərin idarə edilməsi sistemində və ya müştəri xidməti alətlərində göstərməyə imkan verir. Başlamaq üçün adətən UPS tərtibatçı hesabı yaratmaq, tətbiqi qeydiyyatdan keçirmək, autentifikasiya məlumatlarını əldə etmək, izləmə sorğusu göndərmək və cavabı müştərilər üçün faydalı hadisələrə çevirmək lazımdır. Bu təlimat əvvəlcədən API təcrübəsi tələb etmədən prosesi izah edir.

Nümunələr etiket yaratmaq, tarif hesablamaq və ya ünvanı təsdiqləməkdən deyil, izləmədən bəhs edir. UPS ayrıca API məhsulları və sənədlər təqdim edir. Buna görə istehsal iş axınlarını qurmazdan əvvəl qeydiyyatdan keçirdiyiniz tətbiqin ehtiyacınız olan izləmə imkanına çıxışı olduğunu təsdiqləyin.

UPS Tracking API nə edir

API bir proqram sisteminin digərindən məlumat istəməsi üçün strukturlaşdırılmış üsuldur. İzləmə iş axınında sisteminiz göndəriş identifikatorunu, məsələn, izləmə nömrəsini daşıyıcıya və ya izləmə platformasına göndərir. Xidmət sorğu zamanı mövcud olan xidmət, göndəriş və cavab sahələrindən asılı olaraq cari status, statusun təsviri, məkan məlumatları, tarixlər və bağlamanın mərhələlərini əhatə edə bilən göndəriş məlumatlarını qaytarır.

Bu məlumat bir neçə praktiki funksiyanı dəstəkləyə bilər:

• Elektron ticarət mağazasına yerləşdirilmiş izləmə səhifəsi.
• Sifarişlərin idarə edilməsi və ya müəssisə resurslarının planlaşdırılması sistemi daxilində göndərişin görünməsi.
• Daşıyıcının veb-saytını əl ilə yoxlamaq ehtiyacını azaldan müştəri xidməti ekranları.
• Çatdırılma istisnaları, gecikmələr və ya tamamlanmış çatdırılmalar üçün daxili xəbərdarlıqlar.
• Göndəriş hadisələrinə əsaslanan satınalmadan sonrakı mesajlar.

API tətbiqinizin məntiqini əvəz etmir. Yeniləmələri nə qədər tez-tez tələb etməyi, cavabları necə saxlamağı, natamam məlumatları necə idarə etməyi və daşıyıcı statuslarını müştərilərə necə izah etməyi hələ də siz müəyyənləşdirməlisiniz.

UPS Tracking API və UPS veb-saytı

UPS veb-saytı insanın izləmə nömrəsini daxil edib nəticəni oxuması üçün hazırlanıb. API isə proqram təminatı üçün nəzərdə tutulub. İzləmə məlumatlarının avtomatik olaraq başqa sistemdə görünməsi və ya daxili prosesi işə salması lazım olduqda API faydalıdır.

Bu fərq vacibdir, çünki API inteqrasiyası əl ilə axtarışın tələb etmədiyi məsuliyyətləri yaradır. Komandanız məlumatları qorumalı, istifadəçi girişini təsdiqləməli, sorğuları və cavabları lazımi qaydada qeyd etməli, müvəqqəti nasazlıqları idarə etməli və daşıyıcı platformasında dəyişikliklərdən sonra inteqrasiyanın işləməyə davam edib-etmədiyini izləməlidir.

Cari qeydiyyat və texniki tələblər üçün UPS tərtibatçı platforması uyğun başlanğıc nöqtəsidir. Autentifikasiya üsulları, API versiyaları, tələb olunan başlıqlar və məhsula giriş qaydaları dəyişə bildiyi üçün onun sənədləri köhnə təlimatlardan, kod nümunələrindən və forum yazılarından üstün tutulmalıdır.

Sorğu göndərməzdən əvvəl sizə lazım olanlar

İnteqrasiyanı yazmazdan əvvəl aşağıdakıları hazırlayın:

1. UPS tərtibatçı hesabı. Mövcud API-ləri nəzərdən keçirmək və tətbiq yaratmaq üçün rəsmi UPS Developer Portal-dan istifadə edin.
2. Tətbiq məlumatları. Dəqiq məlumat adları və autentifikasiya axını cari UPS sənədlərindən götürülməlidir. Müştəri sirlərini brauzer koduna, mobil tətbiqlərə, ictimai repozitorilərə və ya müştərilərin görə bildiyi səhifələrə yerləşdirməyin.
3. Sınaq üçün etibarlı izləmə nömrəsi. Təşkilatınızın giriş icazəsi olan göndərişlərlə sınaq aparın və şəxsi və ya kommersiya göndəriş məlumatlarını jurnallarda açıqlamaqdan çəkinin.
4. Server tərəfli inteqrasiya nöqtəsi. Backend xidməti adətən daşıyıcıya birbaşa ictimai veb-səhifədən zəng etməkdən daha təhlükəsizdir, çünki o, məlumatları məxfi saxlaya və sorğu həcminə nəzarət edə bilər.
5. Cavabların saxlanması planı. Hansı sahələrə ehtiyacınız olduğunu, onları nə qədər müddət saxlamağı və daşıyıcı hadisəsini daxili sifarişlə necə əlaqələndirməyi müəyyənləşdirin.

Yeni başlayanlar üçün inteqrasiya iş axını

1. Biznes tələbini təsdiqləyin

Əvvəlcə məhsulunuzda “izləmə”nin nə demək olduğunu müəyyənləşdirin. Müştəriyə təqdim olunan səhifəyə yalnız cari status və gözlənilən çatdırılma məlumatı lazım ola bilər. Anbar və ya dəstək panelinə isə skan tarixçəsi, vaxt möhürləri, istisna təsvirləri və ilkin izləmə nömrəsi də lazım ola bilər.

Səbəb olmadan mövcud olan bütün sahələri tələb etməkdən çəkinin. Daha kiçik məlumat modeli daha asan saxlanılır və istifadəçilərinizə lazım olmayan məlumatların açıqlanması ehtimalını azaldır.

2. Tətbiqi qeydiyyatdan keçirin

UPS tərtibatçı mühitində tətbiq yaradın və cari portal təlimatlarına uyğun olaraq müvafiq izləmə məhsulunu seçin. Tətbiq identifikatorunu təhlükəsiz şəkildə qeyd edin. UPS istehsal mühitinə giriş üçün təsdiq, hesab əlaqələndirməsi və ya əlavə quraşdırma tələb edirsə, canlı işə salınma tarixi barədə öhdəlik götürməzdən əvvəl bu addımları tamamlayın.

Platforma bu modeli dəstəklədikdə sınaq və istehsal üçün ayrı məlumatları və konfiqurasiyanı qoruyun. Bu, sınaq skriptinin canlı iş axınına təsir etməsi ehtimalını azaldır.

3. Autentifikasiyanı tətbiq edin

Autentifikasiya tətbiqinizin xidmətə müraciət etməyə icazəsi olduğunu sübut edir. Cari UPS sənədlərində göstərilən autentifikasiya üsuluna, token son nöqtəsinə, əhatə dairəsi tələblərinə və başlıq formatına əməl edin. Giriş tokenlərini müvəqqəti sirlər kimi qəbul edin və onları tətbiq jurnallarına yazmayın.

Məntiqli tətbiq tokeni yalnız lazım olduqda tələb edir, icazə verilən istifadə müddəti ərzində ondan təkrar istifadə edir və müddəti bitdikdən sonra yenisini əldə edir. Kodunuz autentifikasiya xətası ilə izləmə nömrəsi xətasını da fərqləndirməlidir. Çarə fərqlidir: birincidə məlumatların və ya konfiqurasiyanın yoxlanılması, ikincidə isə girişin təsdiqlənməsi tələb oluna bilər.

4. İzləmə sorğusu göndərin

Autentifikasiyadan sonra UPS tərəfindən müəyyən edilmiş izləmə əməliyyatından və identifikator formatından istifadə edərək sorğu göndərin. Dəqiq URL, HTTP metodu, başlıqlar və cavab sxemi seçdiyiniz API versiyasının rəsmi sənədlərinə aiddir.

Konseptual sorğu belə görünür:

POST /tracking-operation
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

{
  "trackingNumber": "YOUR_TRACKING_NUMBER"
}

Bu, öyrənmə nümunəsidir, kopyalayıb istehsalda istifadə ediləcək sorğu deyil. Əməliyyat adını, son nöqtəni, başlıqları və gövdəni cari UPS API arayışındakı dəyərlərlə əvəz edin. Bəzi API-lər yol parametrindən və ya fərqli sorğu strukturundan istifadə edir.

5. Cavabı normallaşdırın

Daşıyıcı cavabları həmişə müştərilərinizin gözlədiyi dildə yazılmır. Aşağıdakılar kimi sabit sahələrə malik daxili hadisə modeli yaradın:

• Daxili sifariş və ya göndəriş ID-si.
• Daşıyıcının adı və izləmə nömrəsi.
• Daşıyıcının ən son status kodu və xam təsviri.
• Tətbiqiniz tərəfindən istifadə olunan normallaşdırılmış status.
• Hadisənin vaxt möhürü və təqdim edildikdə məkan.
• Son uğurlu yenilənmə vaxtı.

Mümkün olduqda daşıyıcının ilkin statusunu qoruyun. “Yoldadır” kimi normallaşdırılmış etiket müştəri interfeysi üçün faydalıdır, lakin xam təsvir dəstək əməkdaşlarına qeyri-adi hadisəni araşdırmağa kömək edə bilər.

6. Yeniləmələrin necə əldə ediləcəyinə qərar verin

Bəzi sistemlər planlaşdırılmış sorğulardan istifadə edir: backend uyğun göndərişləri müəyyən intervallarda yoxlayır və dəyişiklikləri saxlayır. Digərləri müvafiq platforma dəstəklədikdə hadisə bildirişlərindən istifadə edir. Hər UPS izləmə məhsulunun eyni bildiriş mexanizmini təqdim etdiyini düşünməyin. Vebhuk əsaslı iş axını hazırlamazdan əvvəl cari sənədləri və kommersiya şərtlərini təsdiqləyin.

Sorğular seçici aparılmalıdır. Yeni göndərilmiş və ya aktiv şəkildə hərəkətdə olan bağlamalar çatdırılmış və ya ləğv edilmiş göndərişlərdən daha tez-tez yoxlanıla bilər. Müvəqqəti xətalar üçün gecikmə ilə təkrar cəhdlər tətbiq edin, sənədləşdirilmiş limitlərə əməl edin və biznes prosesiniz sonradan yoxlama tələb etmədikdə yekun statusdan sonra lazımsız sorğuları dayandırın.

Ümumi xətalar və onların idarə edilməsi

İstifadəçi təcrübəsi baxımından ən vacib qayda çatışmayan məlumatı əminlik ifadə edən nəticəyə çevirməməkdir. “Yeni skan yoxdur” avtomatik olaraq “itib” demək deyil və “etiket yaradılıb” mütləq “yoldadır” mənasına gəlmir. Statusları diqqətlə xəritələndirin və istisnaların idarə edilməsini dəstək komandaları üçün görünən saxlayın.

Çoxdaşıyıcılı API nə vaxt daha uyğun seçimdir

Göndərişləriniz əsasən UPS tərəfindən idarə olunursa və komandanız daşıyıcı bağlantısına birbaşa nəzarət etmək istəyirsə, birbaşa UPS inteqrasiyası məntiqli seçim ola bilər. Bunun əvəzində hər əlavə daşıyıcı başqa autentifikasiya modeli, məlumat sxemi, xəta siyasəti və texniki xidmət prosesi tələb edə bilər.

Əməliyyatınız bir neçə daşıyıcıdan istifadə edirsə, çoxdaşıyıcılı xidmət ayrı-ayrı inteqrasiyaların sayını azalda bilər. 17TRACK's Tracking API tətbiq əsaslı göndəriş izləməsi üçün hazırlanıb və onun official developer documentation mövcud inteqrasiya modelini izah edir. Əsl tələb yalnız UPS izləməsi deyil, daşıyıcılar arasında ardıcıl izləmə qatıdırsa, bunu qiymətləndirmək faydalı ola bilər.

Bu, birbaşa UPS bağlantısını avtomatik olaraq əvəz etmək üçün səbəb deyil. Lazım olan daşıyıcı əhatəsini, hadisə təfərrüatlarını, məlumatların saxlanması tələblərini, autentifikasiya modelini, əməliyyat limitlərini, dəstək prosesini və ümumi tətbiq səylərini müqayisə edin. Provayderin ictimai sənədləri texniki konsepsiyanın yoxlanılması üçün başlanğıc nöqtəsi kimi qəbul edilməlidir, öz göndəriş nümunələrinizin sınağını əvəz edən vasitə kimi yox.

İstehsala hazırlıq yoxlama siyahısı

• Məlumatlar sirr menecerində saxlanılır və heç vaxt brauzerə açıqlanmır.
• Sınaq və istehsal mühitləri aydın şəkildə ayrılıb.
• Sorğuların vaxt aşımı, idarə olunan təkrar cəhdləri və faydalı xəta qeydiyyatı var.
• İzləmə nömrələri göndərilməzdən əvvəl təsdiqlənir.
• Sistem son uğurlu yenilənməni saxlayır və boş cavabla onun üzərinə yazmaqdan çəkinir.
• Daşıyıcının xam mesajları və müştəriyə təqdim olunan etiketlər ayrı idarə olunur.
• Sorğu tezliyi provayderin dərc etdiyi limitlərə və əməliyyat ehtiyacınıza uyğundur.
• Monitorinq autentifikasiya xətalarını, artan xəta dərəcələrini və köhnəlmiş göndərişləri aşkar edə bilir.
• Dəstək əməkdaşları müştəri sualını araşdırmaq üçün kifayət qədər təfərrüat görə bilir.
• UPS sənədləri, məlumatları, son nöqtələri və ya cavab sahələrini dəyişdikdə inteqrasiya yenidən sınaqdan keçirilir.

Bir tam yolla başlayın: autentifikasiya edin, bir sınaq göndərişini izləyin, cavabı saxlayın, sadə status göstərin və xətanı idarə edin. Bu yol etibarlı olduqdan sonra genişləndirin. Bu yanaşma adətən əsas məlumatlar və xəta davranışı başa düşülməzdən əvvəl böyük müştəri yönümlü izləmə təcrübəsi yaratmaqdan daha təhlükəsizdir.

FAQ

Yalnız bir neçə bağlamanı izləyirəmsə, API-yə ehtiyacım varmı?

Adətən yox. Təsadüfi axtarışlar üçün daşıyıcının veb-saytında əl ilə izləmə daha praktik ola bilər. İzləmə təkrarlanan iş axınının bir hissəsi olduqda və ya başqa bir tətbiq daxilində görünməli olduqda API daha dəyərli olur.

UPS Tracking API-yə Shopify mövzusundan və ya brauzerdən zəng edə bilərəm?

Birbaşa brauzer sorğusu məlumatları açıqlaya və sorğulara nəzarəti çətinləşdirə bilər. Server tərəfli xidmət və ya mövcud izləmə inteqrasiyası, ümumiyyətlə, daha təhlükəsizdir. Cari UPS sənədlərində texniki tələbləri və icazə verilən arxitekturanı təsdiqləyin.

İzləmə API-si göndəriş etiketləri yaradır?

Mütləq deyil. İzləmə, etiket yaratma, tarif hesablama, ünvanın təsdiqlənməsi və digər logistika funksiyaları ayrı API məhsulları ola bilər. Ehtiyacınız olan əməliyyata uyğun məhsulu seçin.

Etibarlı izləmə nömrəsi niyə az məlumat qaytara bilər?

Bağlama ilk skanı almamış ola bilər, məlumatlar hələ mövcud olmaya bilər və ya sorğu API-nin tələb etdiyi formatla və ya giriş icazələri ilə uyğunlaşmaya bilər. Boş və ya məhdud cavabı göndərişin itdiyinə sübut kimi deyil, araşdırılmalı vəziyyət kimi qəbul edin.

Birbaşa UPS-i, yoxsa çoxdaşıyıcılı izləmə API-sini seçməliyəm?

UPS əsas daşıyıcıdırsa və fokuslanmış inteqrasiya istəyirsinizsə, birbaşa bağlantını seçin. Əməliyyat məqsədiniz bir neçə daşıyıcı arasında vahid izləmə iş axını yaratmaqdırsa, çoxdaşıyıcılı xidməti nəzərdən keçirin. Son qərarı verməzdən əvvəl tələb olunan daşıyıcıları və hadisə ssenarilərini sınaqdan keçirin.

Mənbələr

• UPS Developer Portal
• UPS Tracking API documentation and product resources
• 17TRACK Tracking API
• 17TRACK API documentation