UPS İzləmə API-dən necə istifadə etməli: Addım-addım quraşdırma təlimatı

UPS Tracking API-dən istifadə etmək üçün UPS Developer hesabı yaradın, tətbiqi qeydiyyatdan keçirin, OAuth 2.0 məlumatlarını əldə edin, giriş tokeni tələb edin və etibarlı UPS izləmə nömrəsi ilə autentifikasiya olunmuş izləmə sorğuları göndərin. Dəqiq portal etiketləri, təsdiq mərhələləri və API tələbləri dəyişə bilər, buna görə istehsal inteqrasiyasını aktivləşdirməzdən əvvəl cari təlimatları rəsmi UPS Developer Portalında təsdiqləyin.

Bu təlimat onlayn mağazada, sifarişlərin idarə edilməsi sistemində, anbar iş axınında, müştəri xidməti alətində və ya daxili paneldə göndəriş statusuna ehtiyacı olan tərtibatçılar və e-ticarət əməliyyatları komandaları üçündür. Təlimat inteqrasiya ardıcıllığına, etibarlılığa təsir edən qərarlara və ümumi izləmə xətalarının qarşısını alan yoxlamalara diqqət yetirir.

UPS Tracking API nə edir

API inteqrasiyası proqram təminatına daşıyıcının izləmə səhifəsini əl ilə açmağı əməkdaşdan və ya müştəridən tələb etmək əvəzinə UPS-dən göndəriş məlumatı istəməyə imkan verir. Tətbiqiniz cavabdan son məlum statusu göstərmək, çatdırılma hadisələrini müəyyən etmək, müştəri xidməti araşdırmalarını dəstəkləmək və ya daxili iş axınını işə salmaq üçün istifadə edə bilər.

API izləmə səhifəsi ilə eyni deyil. İzləmə səhifəsi insanın oxuması üçün hazırlanıb. API cavabı proqram təminatının təhlil etməli, saxlamalı və təqdim etməli olduğu strukturlaşdırılmış məlumatdır. Sisteminiz autentifikasiya, xətaların idarə edilməsi, sorğuların təkrarlanması və ya hadisələrin toplanması, məlumatların saxlanma müddəti, istifadəçi interfeysinin dizaynı və çatdırılma hadisələri əsasında qurulan istənilən biznes qaydalarına görə məsul olaraq qalır.

Başlamazdan əvvəl

Developer portalını açmazdan əvvəl aşağıdakıları hazırlayın:

• UPS Developer hesabı və ya cari UPS qeydiyyat prosesinin tələb etdiyi hesab növü.
• Qeydiyyatdan keçirilmiş tətbiq və həmin tətbiq üçün verilmiş məlumatlar.
• Test izləmə nömrəsi və ya təsdiqlənmiş digər test üsulu. UPS sənədlərində ayrıca test mühiti və ya test proseduru təqdim olunursa, canlı müştəri məlumatları ilə başlamayın.
• Göndəriş qeydlərinin, izləmə hadisələrinin və müştəriyə göstərilən status mesajlarının hansı sistemə məxsus olacağı barədə aydın qərar.
• Müştəri məlumatlarını və giriş tokenlərini saxlamaq üçün təhlükəsiz yer. Məxfi məlumatları heç vaxt brauzer koduna, açıq repozitorilərə, ekran görüntülərinə və ya istifadəçilərin yoxlaya biləcəyi mobil tətbiqlərə yerləşdirməyin.

Tətbiqinizin yalnız izləməyə, yoxsa daha geniş UPS inteqrasiyasına ehtiyac duyduğuna da qərar verməlisiniz. İzləmə, tariflərin hesablanması, göndərmə, ünvanın yoxlanması və sənəd xidmətləri fərqli məhsullara, icazələrə, sorğu formatlarına və əməliyyat tələblərinə malik ola bilər.

Addım 1: UPS Developer Portalını açın

Başlamaq üçün rəsmi UPS Developer Portalına keçin. Cari API kataloqunu, autentifikasiya təlimatlarını, qeydiyyat tələblərini, şərtləri və mühit haqqında məlumatları nəzərdən keçirin. Başqa UPS xidmətinə aid təlimatların izləməyə də tətbiq olunduğunu fərz etmək əvəzinə, xüsusilə Tracking API sənədlərini axtarın.

Portal cari sorğu sahələri, avtorizasiya əhatə dairələri, cavab tərifləri, tezlik limitləri, xəta kodları və mühit məlumatları üçün uyğun mənbədir. Bu məlumatlar dəyişə bilər və üçüncü tərəfin kod nümunəsində köhnə UPS interfeysindən və ya köhnəlmiş autentifikasiya üsulundan istifadə oluna bilər.

Addım 2: Tətbiqi qeydiyyatdan keçirin

Developer portalında tətbiq yaradın və tətbiqin həqiqətən ehtiyac duyduğu UPS API-lərini seçin. Yalnız izləmə layihəsi üçün iş axınınız əlavə xidmətlər tələb etmədiyi halda yalnız izləmə imkanını tələb edin. İcazələrin məhdudlaşdırılması konfiqurasiyanın mürəkkəbliyini azaldır və sonrakı problemlərin aradan qaldırılmasını asanlaşdırır.

Tətbiq identifikatorunu və məxfi açarı server tərəfli məxfi məlumat menecerində və ya qorunan mühit dəyişənləri sistemində saxlayın. Məxfi açara parol kimi yanaşın. Aşkar olunarsa, UPS tərəfindən təqdim edilən proses vasitəsilə onu dəyişdirin və icazəsiz istifadə üçün jurnalları nəzərdən keçirin.

Portal hesab, ödəniş, biznes və ya tətbiq məlumatları tələb edərsə, dəqiq məlumatlar təqdim edin. Sadəcə testi tamamlamaq üçün istehsal istifadə ssenarisi uydurmayın və başqasının hesab məlumatlarından istifadə etməyin. Xidmətə giriş hesab konfiqurasiyasından və cari UPS təsdiq prosesindən asılı ola bilər.

Addım 3: OAuth 2.0 autentifikasiyasını tətbiq edin

Cari UPS developer sənədlərində API-lər üçün OAuth əsaslı autentifikasiyadan istifadə olunur. Serveriniz adətən sənədləşdirilmiş token axını vasitəsilə tətbiq məlumatlarını mübadilə edir və giriş tokeni alır. Daha sonra API sorğusunun avtorizasiya başlığında həmin tokeni göndərir.

Autentifikasiyanı izləmə məntiqindən ayrı saxlayın. Praktik dizaynda bir komponent etibarlı token əldə edib keşləyir, digəri isə izləmə endpoint-inə müraciət edir. Token komponenti aşağıdakıları etməlidir:

• Məlumatları yalnız sənədləşdirilmiş UPS avtorizasiya endpoint-inə göndərmək.
• Cari UPS sənədlərində göstərilən məzmun tipindən və grant parametrlərindən istifadə etmək.
• Tokeni müvəqqəti saxlamaq və müddəti bitənədək təkrar istifadə etmək; hər izləmə nömrəsi üçün yeni token tələb etməmək.
• Sənədləşdirilmiş müddət bitmə şərti baş verdikdə tokeni yeniləmək və ya yenidən əldə etmək.
• Məlumatları və tokenləri tətbiq jurnallarında, xəta hesabatlarında və dəstək sorğularında gizlətmək.

Brauzer sessiyasından tokeni kopyalayıb daimi inteqrasiyada istifadə etməyin. Backend xidməti adətən məlumatları idarə etmək üçün daha təhlükəsiz yerdir, çünki məxfi məlumatları açıq müştəri kodundan uzaq saxlayır.

Addım 4: İzləmə sorğusunu yaradın

Rəsmi Tracking API istinadında göstərilən sorğu formatından istifadə edin. Tipik sorğuya yolda və ya sorğu parametrlərində izləmə nömrəsi, avtorizasiya başlığında giriş tokeni və UPS API tərəfindən tələb olunan başlıqlar daxildir. İzləmə nömrəsinin yeganə tələb olunan dəyər olduğunu fərz etməyin: cari istinadda versiya, tranzaksiya, məzmun tipi və ya korrelyasiya başlıqları göstərilə bilər.

Sadələşdirilmiş sorğu nümunəsi belə görünür:

GET [UPS tracking endpoint]/[tracking-number]
Authorization: Bearer [access-token]
Accept: application/json

Bu struktur nümunəsidir, birbaşa kopyalayıb istifadə ediləcək endpoint deyil. Tətbiqiniz üçün UPS sənədlərində dərc olunmuş endpoint, versiya, başlıqlar və parametr adlarından istifadə edin. İzləmə nömrəsini öz sifariş məlumatı qaydalarınıza uyğun normallaşdırın, lakin daşıyıcının sənədlərində bunun təhlükəsiz olduğu təsdiqlənməyibsə, simvolları silməyin.

Addım 5: Hadisələri məlumat modelinizə uyğunlaşdırın

Daşıyıcı cavablarında çox vaxt tək status etiketindən daha çox məlumat olur. Müştəriyə göstərilən səhifəni kodlaşdırmazdan əvvəl cavabı göndəriş identifikatoru, daşıyıcı, son status, hadisə kodu, hadisənin təsviri, hadisə vaxtı, məkan, təxmini çatdırılma məlumatları və mümkün olduqda çatdırılma vaxtı kimi daxili modelə uyğunlaşdırın.

Saxlama və məxfilik siyasətləriniz icazə verdikdə, daşıyıcının ilkin cavabını qoruyun. İlkin cavab uyğunlaşdırma xətasını araşdırmağa və ya normallaşdırılmış statusunuzun daşıyıcının ifadəsindən niyə fərqləndiyini izah etməyə kömək edə bilər. Eyni zamanda texniki hadisə kodlarını oxunaqlı izah olmadan müştərilərə göstərməkdən çəkinin.

Hər statusu yekun çatdırılma nəticəsi kimi qəbul etməyin. Məsələn, daşınma zamanı hadisəsi, istisna, çatdırılma cəhdi və çatdırılıb hadisəsi eyni müştəri mesajına çevrilməməlidir. Açıq uyğunlaşdırmalar yaradın və UPS kodunuzun tanımadığı hadisə dəyəri əlavə etdikdə nə baş verəcəyini müəyyənləşdirin.

Addım 6: Yenidən cəhdlər, yoxlama və monitorinq əlavə edin

İstehsal inteqrasiyası inkişaf konsolunda uğurlu sorğudan daha çoxunu tələb edir. Yoxlama və əməliyyat təhlükəsizlik tədbirləri əlavə edin:

• Giriş məlumatlarının yoxlanması: sorğu göndərməzdən əvvəl boş, yanlış formatlı və ya açıq şəkildə natamam izləmə nömrələrini rədd edin.
• Vaxt aşımı: yavaş daşıyıcı cavabının ödəniş, dəstək və ya anbar iş axınının tamamını bloklamasının qarşısını alın.
• Yenidən cəhd qaydaları: müvəqqəti şəbəkə və ya xidmət xətaları zamanı gecikmə ilə ehtiyatlı şəkildə yenidən cəhd edin. Autentifikasiya xətalarını və etibarsız izləmə nömrələrini təkrar-təkrar yoxlamayın.
• Tezlik limitlərini nəzərə alma: UPS sənədlərindəki limitlərə və istifadə qaydalarına əməl edin. Biznes prosesiniz imkan verdikdə son nəticələri keşləyin.
• Naməlum vəziyyətlər: tanınmayan hadisəni yanlış olaraq çatdırılıb və ya itirilib kimi etiketləmək əvəzinə nəzərdən keçirmək üçün saxlayın.
• Müşahidə edilə bilənlik: məxfi məlumatları və lazımsız şəxsi məlumatları jurnala yazmadan sorğu vaxtını, cavab kateqoriyasını və korrelyasiya məlumatlarını qeydə alın.

İzləmə sistemi göndərişi nə qədər tez-tez yenilədiyini də müəyyənləşdirməlidir. Həddindən artıq tez-tez sorğu göndərmək qarşısı alına bilən yük yarada və yeni məlumat verməyə bilər. Çox seyrək sorğu göndərmək müştəriyə göstərilən səhifənin köhnəlmiş görünməsinə səbəb ola bilər. Aralığı göndəriş həcminə, əməliyyat təciliyinə, daşıyıcının qaydalarına və istifadəçilərinizin həqiqətən ehtiyac duyduğu yenilik səviyyəsinə əsasən seçin.

Addım 7: Realistik ssenarilərlə test edin

Uğurla çatdırılmış göndərişdən daha çoxunu test edin. Naməlum izləmə nömrəsini, daşınma mərhələsində olan göndərişi, istisnanı, bir neçə hadisəsi olan göndərişi, müddəti bitmiş tokeni, vaxt aşımını, avtorizasiya xətasını və təhlilçinizin gözləmədiyi sahələri ehtiva edən cavabı yoxlayın. UPS ayrıca test mühiti və ya test məlumatları təqdim edirsə, əvvəlcə həmin prosedura əməl edin.

Sorğudan istifadəçi interfeysinə qədər tam yolu yoxlayın. Düzgün sifarişin düzgün göndərişi qəbul etdiyini, vaxt göstəricilərinin nəzərdə tutulan saat qurşağında göstərildiyini, təkrarlanan hadisələrin təkrarlanan müştəri mesajları yaratmadığını və daşıyıcıda yaranan problemin əvvəlki etibarlı statusu yanıltıcı mətnlə əvəz etmədiyini təsdiqləyin.

Çoxdaşıyıcılı izləmə API-si nə zaman daha uyğun seçimdir

Birbaşa UPS inteqrasiyası əsasən UPS ilə göndəriş edən və daşıyıcı iş axınına ciddi nəzarətə ehtiyacı olan əməliyyat üçün uyğun ola bilər. Sifarişlər bir neçə daşıyıcı, marketplace, poçt operatoru və ya regional çatdırılma şirkəti arasında bölündükdə bu yanaşma daha az rahat olur. Belə vəziyyətdə ayrıca məlumatlar, cavab formatları, status lüğətləri və yenidən cəhd qaydaları texniki xidmət işini artıra bilər.

17TRACK Tracking API kimi çoxdaşıyıcılı xidmətlər bir neçə daşıyıcı üzrə izləməyə ehtiyacı olan tətbiqlər üçün alternativ inteqrasiya modeli təqdim edə bilər. Dəstəklənən daşıyıcılar, sorğu formatları, autentifikasiya, istifadə şərtləri və mövcud imkanlar barədə developer sənədləri birbaşa nəzərdən keçirilməlidir. Bu, onu avtomatik olaraq birbaşa UPS bağlantısından üstün etmir: düzgün seçim daşıyıcı qarışığından, məlumat tələblərindən, inteqrasiyaya nəzarətdən və kommersiya və ya uyğunluq məhdudiyyətlərindən asılıdır.

Developer inteqrasiyası əvəzinə istehlakçıya yönəlmiş axtarış üçün 17TRACK-in izləmə səhifəsi API bağlantısı qurmaqdan daha uyğun ola bilər. Brendli satınalma sonrası yeniləmələrə ehtiyacı olan onlayn mağaza üçün mağazanın tələb etmədiyi API işini əlavə etmək əvəzinə müvafiq platforma inteqrasiyasını ayrıca nəzərdən keçirin.

Ümumi tətbiq səhvləri

• Köhnə nümunələrdən istifadə: kod nümunəsi istifadədən çıxarılmış versiyaya, köhnə autentifikasiya üsuluna və ya başqa UPS xidmətinə istinad edə bilər.
• Məxfi məlumatları frontend koduna yerləşdirmək: brauzerə göndərilən hər şey yoxlanıla bilən hesab edilməlidir.
• Boş nəticənin göndərişin olmaması demək olduğunu düşünmək: biznes nəticəsi çıxarmazdan əvvəl izləmə nömrəsini, hesab icazələrini, mühiti və cavab mesajını yoxlayın.
• Yalnız mətnə uyğunlaşdırmaq: status təsvirləri dəyişə bilər. Sənədləşdirilmiş kodlardan istifadə edin və naməlum dəyərləri nəzərdən keçirmək üçün saxlayın.
• Hesab və istifadə tələblərini nəzərə almamaq: texniki kod düzgün ola bilər, lakin tətbiq tələb olunan xidmət üçün konfiqurasiya edilməyə bilər.
• Biznes qaydası olmadan yeniləmək: lazımsız sorğular müştəri təcrübəsini yaxşılaşdırmadan xərci, yükü və əməliyyat səs-küyünü artıra bilər.

İstehsala buraxılış üçün praktiki yoxlama siyahısı

1. Tətbiqin cari UPS sənədlərindən və təsdiqlənmiş mühitdən istifadə etdiyini təsdiqləyin.
2. Məlumatların server tərəfində saxlandığını və dəyişdirilə bildiyini yoxlayın.
3. Autentifikasiya xətasını, daşıyıcı xətalarını, yanlış formatlı girişi və vaxt aşımını test edin.
4. Nümunəvi göndərişlər üçün normallaşdırılmış statusları ilkin cavabla müqayisə edin.
5. Yeniləmə siyasəti müəyyənləşdirin və sorğu həcminə nəzarət edin.
6. Naməlum hadisələr, gecikmiş yeniləmələr və müştəri eskalasiyaları üçün məsuliyyəti müəyyən edin.
7. Başqa bir tərtibatçının məlumatları, endpoint versiyalarını və status uyğunlaşdırmalarını təhlükəsiz şəkildə yeniləyə bilməsi üçün inteqrasiyanı sənədləşdirin.

Tez-tez verilən suallar

Tracking API-dən istifadə etmək üçün UPS hesabına ehtiyacım varmı?

Cari UPS qeydiyyat və giriş tələblərini Developer Portalında nəzərdən keçirməlisiniz. API-yə giriş tətbiq qeydiyyatından, məlumatlardan, hesab konfiqurasiyasından və tələb olunan konkret xidmətdən asılı ola bilər. İctimai izləmə səhifəsinin giriş məlumatlarının developer API giriş məlumatları ilə eyni olduğunu düşünməyin.

UPS Tracking API pulsuzdurmu?

API girişinin kommersiya və ya istifadə şərtlərinin olmadığını düşünməyin. UPS cari xidmət və hesab məlumatlarını rəsmi kanalları vasitəsilə dərc edir və bəzi tələblər məhsuldan, hesabdan və ya razılaşmadan asılı ola bilər. İstehsal büdcəsini planlaşdırmazdan əvvəl tətbiq olunan şərtləri birbaşa təsdiqləyin.

UPS API-sinə birbaşa brauzerdə JavaScript-dən müraciət edə bilərəmmi?

Brauzer əsaslı sorğu tətbiq məlumatlarını açıqlaya və mənbələrarası sorğu, təhlükəsizlik və istifadə nəzarəti problemləri yarada bilər. Məxfi məlumatları saxlamaq, tokenlər əldə etmək, yenidən cəhd qaydalarını tətbiq etmək və göndəriş məlumatlarına girişi məhdudlaşdırmaq üçün server tərəfli inteqrasiya ümumiyyətlə daha təhlükəsiz yanaşmadır.

Tətbiqim izləmə yeniləmələrini nə qədər tez-tez tələb etməlidir?

Yeniləmə siyasətini daşıyıcının sənədləşdirilmiş limitlərinə, göndəriş həcminə, əməliyyat təciliyinə və istifadəçilərinizin tələb etdiyi yenilik səviyyəsinə əsasən müəyyən edin. Uyğun olduqda son nəticələri keşləyin, müvəqqəti xətalardan sonra gecikmədən istifadə edin və təkrarlanan sorğuları sənədləşdirilmiş hadisə və ya bildiriş imkanının əvəzi kimi qəbul etməyin.

Birbaşa UPS inteqrasiyasından, yoxsa çoxdaşıyıcılı API-dən istifadə etməliyəm?

Birbaşa UPS inteqrasiyası daşıyıcıya xas nəzarət tələb edən və UPS yönümlü iş axını üçün uyğun ola bilər. Çoxdaşıyıcılı API göndərişləriniz bir neçə daşıyıcıdan istifadə etdikdə inteqrasiyaların sayını azalda bilər. Seçim etməzdən əvvəl dəstəklənən daşıyıcıları, autentifikasiyanı, məlumat sahələrini, etibarlılıq tələblərini, istifadə şərtlərini və tətbiq səylərini müqayisə edin.

Mənbələr

• UPS Developer Portal — rəsmi API kataloqu, tətbiq girişi, autentifikasiya və developer sənədləri.
• UPS Technology Integration — UPS texnologiyasının biznes sistemləri ilə inteqrasiyası barədə rəsmi məlumat.
• 17TRACK Tracking API — çoxdaşıyıcılı izləmə üçün rəsmi məhsul və developer giriş səhifəsi.
• 17TRACK API Documentation — autentifikasiya, sorğular və cavabların idarə edilməsi üçün rəsmi API sənədləri.