Qaytarma və sifarişlərin yerinə yetirilməsi komandaları üçün USPS Tracking API inteqrasiyası tələbləri

USPS izləmə API inteqrasiyası izləmə nömrəsini endpoint-ə göndərməkdən daha çoxunu tələb edir. Qaytarma və sifarişlərin icrası komandalarına təsdiqlənmiş giriş metodu, etibarlı göndəriş məlumatı modeli, hadisələrin normallaşdırılması, sorğu və ya webhook məntiqi, istisnaların idarə edilməsi, məxfilik və əməliyyatların bərpası üçün nəzarət mexanizmləri lazımdır. Düzgün dizayn həm göndəriş yaradan anbar iş prosesini, həm də tacirə geri hərəkət edən bağlamanı izləyən qaytarma iş prosesini dəstəkləməlidir.

USPS sənədləri və giriş razılaşmaları dəyişə bilər. Buna görə komandalar tətbiqdən əvvəl mövcud developer proqramını, autentifikasiya metodunu, xidmət şərtlərini və texniki məhdudiyyətləri təsdiqləməlidirlər. Aşağıdakı tələblər hər USPS hesabının eyni API girişinə malik olduğunu fərz etmədən davamlı planlaşdırma çərçivəsi təqdim edir.

İnteqrasiya nəyi təmin etməlidir

Sifarişlərin icrası üzrə inteqrasiya sadə əməliyyat sualına cavab verir: çıxış bağlaması haradadır və biznes bundan sonra nə etməlidir? Qaytarma inteqrasiyası isə bununla əlaqəli, lakin fərqli sual verir: qaytarılan məhsul daşıyıcının şəbəkəsinə daxil olub, tacirə çatıb, yoxsa yoxlama və geri ödənişdən əvvəl gecikib?

Hər iki iş prosesi üçün inteqrasiya USPS izləmə hadisəsini daxili göndəriş, sifariş, qaytarma icazəsi və müştəri qeydi ilə əlaqələndirməlidir. Təkcə izləmə nömrəsi kifayət deyil. Sistem həmçinin sifariş identifikatoru, bağlamanın istiqaməti, mövcud olduqda xidmət növü, təyinat və ya qaytarma ünvanı, yaradılma vaxtı və növbəti əməliyyata cavabdeh biznes sahibi kimi kontekstə də ehtiyac duyur.

• Sifarişlərin icrası: göndərişi yaratmaq və ya onunla əlaqələndirmək, qəbul və hərəkəti izləmək, çatdırılma və ya istisna diqqət tələb etdikdə komandaları xəbərdar etmək.
• Qaytarmalar: gözlənilən daxil olan bağlamanı müəyyənləşdirmək, daşıyıcının qəbulunu təsdiqləmək, qaytarma məntəqəsinə çatdırılmanı aşkar etmək və geri ödəniş qərarının yoxlanılmamış müştəri bəyanatına və ya köhnəlmiş statusa əsaslanmasının qarşısını almaq.
• Müştəri dəstəyi: audit və mübahisələrin idarə edilməsi üçün daşıyıcının orijinal hadisə məlumatlarını qoruyaraq başadüşülən izləmə məlumatlarını göstərmək.

Əsas USPS inteqrasiya tələbləri

1. Mövcud giriş və autentifikasiya modelini təsdiqləyin

Rəsmi USPS developer materiallarından başlayın və köhnə nümunə sorğunun və ya qeyri-rəsmi kitabxananın mövcud proqramı əks etdirdiyini fərz etməyin. Nəzərdə tutulan istifadə ssenarisinin hesab, tətbiq qeydiyyatı, məlumatlar, təsdiqlənmiş məhsul və ya xidmət, yaxud əlavə şərtlərin qəbulunu tələb edib-etmədiyini təsdiqləyin. Məlumatları secrets manager-də saxlayın, mümkün olduqda onların icazələrini məhdudlaşdırın və sandbox və ya test məlumatlarını istehsal məlumatlarından ayırın.

Autentifikasiya biznes məntiqindən kənarda idarə olunmalıdır. Tətbiq sifarişlərin emalı kodunu dəyişdirmədən məlumatları yeniləyə bilməli, autentifikasiya xətalarını daşıyıcının status xətalarından ayrıca qeyd etməli və məlumatların jurnallarda, brauzer kodunda, dəstək ekran görüntülərində və ya müştəriyə göstərilən URL-lərdə görünməsinin qarşısını almalıdır.

2. Minimum göndəriş məlumatları müqaviləsini müəyyənləşdirin

Daxili məlumat modeli konkret USPS cavab formatından asılı olmamalıdır. Minimum olaraq aşağıdakıları saxlayın:

• Daxili göndəriş və ya qaytarma ID-si
• Müvafiq olduqda sifariş ID-si və qaytarma icazəsi ID-si
• Daşıyıcının adı və daşıyıcıya məxsus izləmə nömrəsi
• Göndəriş istiqaməti: çıxış və ya giriş
• Təqdim edildikdə və əməliyyatlar üçün əhəmiyyətli olduqda xidmət səviyyəsi
• Mövcud olduqda hadisə kodu, hadisənin təsviri, hadisə vaxtı və hadisə yeri
• İlk görülmə vaxtı və son yoxlama vaxtı
• Daşıyıcının xam cavabı və ya ona audit edilə bilən istinad
• Cari normallaşdırılmış status və onu yaradan qayda

Daşıyıcının orijinal ifadələrini normallaşdırılmış statusla yanaşı saxlayın. “Tranzitdə” kimi geniş statuslar panellər üçün faydalıdır, lakin çatdırılma cəhdini, yönləndirmə təlimatını, ünvan problemini və ya istisnanı izah etmək üçün orijinal hadisə lazım ola bilər.

3. Sorğulardan əvvəl izləmə nömrələrini yoxlayın

Yoxlama təsadüfi boşluqları silməli, müvafiq olduqda başlanğıc simvollarını qorumalı və boş və ya açıq-aşkar səhv dəyərləri API-yə çatmazdan əvvəl rədd etməlidir. O, yalnız ehtimal edilən uzunluğa və ya nümunəyə uyğunluq əsasında bağlamanın mövcud olduğunu sübut etməyə çalışmamalıdır. Sintaktik baxımdan uyğun görünən izləmə nömrəsi hələ verilməmiş, aktiv olmayan, səhv yazılmış və ya başqa daşıyıcı ilə əlaqəli ola bilər.

Qaytarmalar üçün izləmə başlamazdan əvvəl izləmə nömrəsini gözlənilən qaytarma icazəsi ilə əlaqələndirin. Müştəri qaytarma metodunu dəyişərsə və ya fərqli nömrə təqdim edərsə, həm ilkin gözlənilən dəyəri, həm də əvəzləyici dəyəri audit qeydi ilə saxlayın. Bu, sonrakı skanın yanlış qaytarmaya əlavə edilməsinin qarşısını alır.

4. Sorğu strategiyasını düşünülmüş şəkildə seçin

Bir çox daşıyıcı inteqrasiyası təkrarlanan status yoxlamaları ətrafında qurulur, digər platformalar isə hadisələrin çatdırılmasını və ya idarə olunan izləmə qatını dəstəkləyə bilər. Tətbiq seçilmiş USPS giriş metodunun faktiki olaraq nə təklif etdiyini təsdiqləməlidir. Rəsmi sənədlər bu imkanı dəstəkləmədikcə sorğu API-sini webhook inteqrasiyası kimi təsvir etməyin.

Praktik sorğu dizaynı müxtəlif statuslar üçün fərqli intervallardan istifadə edir. Yeni yaradılmış göndərişlər üçün qısa ilkin yoxlama pəncərəsi lazım ola bilər, aktiv bağlamalar normal cədvəl üzrə yoxlanıla bilər, çatdırılmış və ya bağlanmış qaytarmalar isə aşağı tezlikli uzlaşdırma prosesinə keçirilə bilər. Dəqiq interval səlahiyyətli xidmətin şərtlərinə, sənədləşdirilmiş məhdudiyyətlərə, əməliyyat təciliyinə və lazımsız sorğuların dəyərinə əsaslanmalıdır.

Müvəqqəti xətalar üçün eksponensial geri çəkilmədən istifadə edin, sinxronlaşdırılmış təkrar cəhd artımlarının qarşısını almaq üçün təsadüfilik əlavə edin və daimi olaraq etibarsız sorğuları təkrar etməyi dayandırın. Növbə və ya tapşırıq planlaşdırıcısı adətən checkout, etiket çapı və ya geri ödəniş əməliyyatı daxilində izləmə sorğusu göndərməkdən daha təhlükəsizdir.

5. Qeyri-müəyyənliyi itirmədən hadisələri normallaşdırın

USPS hadisələri nəzarət olunan daxili lüğətə uyğunlaşdırılmalıdır, lakin uyğunlaşdırma qeyri-müəyyənliyi qorumalıdır. Məsələn, qəbulu göstərən skan təxmini çatdırılma tarixi ilə eyni deyil, çatdırılma cəhdi isə təsdiqlənmiş itki demək deyil. Faydalı modelə etiket yaradıldı, qəbul edildi, şəbəkə üzrə hərəkətdədir, çatdırılma cəhdi edildi, çatdırıldı, saxlanılır və ya götürülməyə hazırdır, istisna və son yeniləmə yoxdur kimi statuslar daxil ola bilər.

“Son daşıyıcı hadisəsi” və “biznes qərarı” üçün ayrıca sahə saxlayın. Bağlama son daşıyıcı skanına malik ola bilər, lakin yenə də əməliyyat qərarı tələb edə bilər. Əksinə, yeni skanı olmayan bağlama itmiş olmaya bilər; düzgün biznes addımı gözləmək, daşıyıcı ilə əlaqə saxlamaq, müştəri ilə əlaqə saxlamaq və ya müəyyən edilmiş araşdırma prosesinə başlamaq ola bilər.

6. Yeniləmələri idempotent və ardıcıl edin

Eyni hadisə bir dəfədən çox qaytarıla bilər və gecikmiş cavab ən yeni statusu əks etdirməyə bilər. Mövcud olduqda sabit hadisə identifikatorunu saxlayın. Bu mümkün deyilsə, izləmə nömrəsi, hadisə vaxtı, hadisə kodu, yer və təsvirə əsaslanan diqqətli kompozit açardan istifadə edin və qanuni olaraq təkrara bənzəyən skanlara imkan verin.

Sorğuların tamamlanma ardıcıllığı pozulduğuna görə çatdırılmış statusu ümumi daha əvvəlki statusla əvəz etməyin. Hadisə vaxtlarını müqayisə edin və audit izi saxlayın. Vaxt göstəriciləri natamam və ya uyğunsuzdursa, qeydi səssizcə nəticəyə məcbur etmək əvəzinə uzlaşdırma qaydasına yönləndirin.

Qaytarma əməliyyatlarına xas tələblər

Qaytarma komandalarına çatdırılmanın görünməsindən daha çox şey lazımdır. Onlar müştərinin qaytarma sorğusunu fiziki məhsulla və maliyyə qərarı ilə əlaqələndirən nəzarət zəncirinə ehtiyac duyurlar.

1. Qaytarma icazəsi: izləmə başlamazdan əvvəl qaytarma qeydini yaradın və gözlənilən daşıyıcını və izləmə nömrəsini qeyd edin.
2. İlk qəbul: daşıyıcının qəbul skanını bağlamanın şəbəkəyə daxil olduğuna sübut kimi qəbul edin, içəridə düzgün məhsulun olduğuna sübut kimi yox.
3. Daxil olan çatdırılma: tacir birdən çox qəbul məntəqəsi işlətdikdə belə, çatdırılmanı təyin olunmuş qaytarma ünvanı və ya müəssisə ilə əlaqələndirin.
4. Yoxlama növbəsi: qaytarma yalnız biznes qaydası yerinə yetirildikdən sonra yoxlamaya keçirilməlidir. Çatdırılma məhsulun vəziyyətini, sayını və ya uyğunluğunu təsdiqləmir.
5. İstisnaların idarə edilməsi: dayanmış hərəkəti, çatdırılma cəhdlərini, ünvan problemlərini və ziddiyyətli izləmə nömrələrini insan və ya avtomatlaşdırılmış iş prosesi üçün işarələyin.
6. Geri ödəniş nəzarətləri: geri ödənişin qəbul, çatdırılma, yoxlama və ya başqa siyasət hadisəsi əsasında verilib-verilməyəcəyini müəyyənləşdirin. API siyasət üçün sübut təqdim etməlidir, siyasətə səssizcə qərar verməməlidir.

Bu ayrım xüsusilə müştərilər tacir tərəfindən yaradılmış etiketdən istifadə etdikdə, bir qaytarmaya bir neçə bağlama aid olduqda və ya qaytarma üçüncü tərəf anbarına çatdırıldıqda vacibdir.

Sifarişlərin icrası və anbar komandaları üçün tələblər

Çıxış sifarişlərinin icrası düzgün ötürmələrdən asılıdır. Anbar idarəetmə sistemi, sifariş idarəetmə sistemi, göndəriş platforması və müştəri xidməti interfeysi izləmə nömrəsinin hansı sistemə məxsus olması və göndəriş statusunun hansı sistem tərəfindən idarə edilməsi barədə razılaşdırılmalıdır. Dublikat göndəriş qeydləri təkrarlanan bildirişlərin və yanlış istisna saylarının ümumi səbəbidir.

Etiket yaradılarkən izləmə nömrəsini və daşıyıcının kimliyini davamlı qeyddə saxlayın. Təslim zamanı müvafiq icra mərhələsini ilk USPS skanından ayrıca qeyd edin. Bu fərq komandaların gecikmənin daşıyıcı tərəfindən qəbuldan əvvəl, daşınma zamanı və ya çatdırılma cəhdindən sonra baş verdiyini müəyyənləşdirməsinə kömək edir.

Əməliyyat panelləri hər skanı eyni dərəcədə göstərmək əvəzinə, tədbir tələb edən istisnalara üstünlük verməlidir. Faydalı növbələrə müəyyən müddətdən sonra qəbul hadisəsi olmayan bağlamalar, təkrar cəhdləri olan paketlər, anbarın qəbulunu gözləyən çatdırılmış bağlamalar və izləmə nömrəsi icazə ilə uyğun gəlməyən qaytarmalar daxil ola bilər.

İstehsala keçiddən əvvəl test siyahısı

Uğurlu test yalnız bir çatdırılmış bağlamanı əhatə etməməlidir. Seçilmiş USPS proqramının icazə verdiyi test qeydlərindən və daşıyıcı cavablarından istifadə edin və real müştəri məlumatlarını inkişaf jurnallarına yerləşdirməyin.

• İlkin statusu olan etibarlı izləmə nömrəsi
• Hələ hadisə yaratmamış izləmə nömrəsi
• Çatdırılmış göndəriş
• Çatdırılma cəhdi və ya digər istisna statusu
• Dublikat cavab və təkrarlanan sorğu
• Mümkün olduqda test üçün səhv formatlı sorğu, etibarsız məlumat, vaxt aşımı və tarif limiti cavabı
• Ardıcıllıq pozularaq gələn hadisələr
• Əvəzləyici izləmə nömrəsi olan qaytarma
• Bir sifarişə və ya qaytarmaya əlavə edilmiş bir neçə bağlama
• Yeri, vaxt göstəricisi və ya tanış olmayan hadisə ifadəsi çatışmayan daşıyıcı cavabı

Sorğuların uğurunu, cavab gecikməsini, təkrar cəhdlərin həcmini, köhnəlmiş qeydləri, uyğunlaşdırılmamış izləmə nömrələrini və əhəmiyyətli hadisədən daxili yeniləməyə qədər keçən vaxtı ölçün. Bu göstəricilər problemin autentifikasiya, daşıyıcının əlçatanlığı, məlumatların uyğunlaşdırılması və ya anbar prosesi ilə bağlı olduğunu üzə çıxarır.

Çoxdaşıyıcılı izləmə qatı nə vaxt daha uyğun ola bilər

Əməliyyat USPS ilə yanaşı digər daşıyıcılardan da istifadə edirsə, çoxdaşıyıcılı izləmə xidməti sifarişlərin icrası və qaytarma komandalarının saxlamalı olduğu daşıyıcıya xas inteqrasiyaların sayını azalda bilər. 17TRACK-in Tracking API və developer documentation çoxdaşıyıcılı izləmə üçün ayrıca inteqrasiya seçimini təsvir edir. Komandalar seçim etməzdən əvvəl dəstəklənən daşıyıcıları, hadisə sahələrini, autentifikasiyanı, istifadə şərtlərini və əməliyyat məhdudiyyətlərini birbaşa cari sənədlərdə yoxlamalıdırlar.

Bu yanaşma biznesin yalnız USPS bağlantısı əvəzinə daşıyıcılar üzrə vahid normallaşdırılmış izləmə iş prosesi istədiyi zaman daha aktualdır. Bu, daxili göndəriş uyğunlaşdırması, qaytarma icazəsi məntiqi, məxfilik nəzarətləri və istisnaya sahiblik ehtiyacını aradan qaldırmır. Normallaşdırma qatı daşıyıcı fərqlərini sadələşdirə bilər, lakin səhv sifariş-izləmə əlaqələrini düzəldə bilməz.

Təhlükəsizlik, məxfilik və idarəetmə

Göndəriş məlumatlarına çıxışı iş funksiyasına uyğun olaraq məhdudlaşdırın. Müştəriyə açıq səhifələr çatdırılma dəstəyi üçün yalnız lazım olan məlumatları göstərməli, daxili sistemlər isə daha ətraflı hadisə tarixçəsini saxlaya bilər. Xam cavablar və jurnallar üçün saxlanma müddətlərini müəyyənləşdirin, məlumatları və lazımsız şəxsi məlumatları redaktə edin və göndəriş statusunu kimin əl ilə dəyişə biləcəyini sənədləşdirin.

Daşıyıcı məlumatları ilə biznes tərəfindən yaradılan təxminlər arasında aydın fərq saxlayın. Proqnozlaşdırılan çatdırılma tarixi, geri ödəniş uyğunluğu qərarı və ya “itmiş bağlama” etiketi daxili hesablamanı və ya siyasət nəticəsini göstərməlidir. Bu fərq müştəri ilə kommunikasiyanı daha dəqiq edir və daşıyıcı hadisələri dəyişdikdə araşdırmanı asanlaşdırır.

Tətbiq qərarı üzrə bələdçi

İş prosesi USPS ilə məhdudlaşdıqda, komanda daşıyıcıya xas məntiqi saxlaya bildikdə və mövcud USPS giriş metodu tələb olunan məlumat və əməliyyat ehtiyaclarını ödədikdə birbaşa USPS inteqrasiyasını seçin. Eyni sifariş, qaytarma və dəstək sistemləri bir neçə daşıyıcı ilə işləməli olduqda və ortaq hadisə modeli birbaşa nəzarətdən daha dəyərli olduqda çoxdaşıyıcılı qatı nəzərdən keçirin.

Hər iki halda dizaynı yalnız komanda beş suala cavab verə bildikdən sonra təsdiqləyin: Məlumatlara kim sahibdir? İzləmə qeydinə hansı sistem sahibdir? Qəbul, çatdırılma və bağlanma nə hesab olunur? Hadisələr dayandıqda və ya ziddiyyət təşkil etdikdə nə baş verir? Hər istisna üçün hansı əməliyyat işə salınır? Bu cavablar real inteqrasiya tələbləridir; API sorğusu isə həllin yalnız bir hissəsidir.

FAQ

Qaytarma komandalarına fərqli USPS izləmə inteqrasiyası lazımdır?

Mütləq deyil. Daşıyıcı məlumatları oxşar ola bilər, lakin biznes iş prosesi fərqlidir. Qaytarmalar üçün icazə qeydi, daxil olan təyinat, yoxlama və ya geri ödəniş qaydaları, uyğun gəlməyən və ya çoxsaylı izləmə nömrələri üçün nəzarət mexanizmləri tələb olunur.

Etibarlı izləmə nömrəsi USPS-in bağlamaya sahib olduğunu sübut edir?

Xeyr. İzləmə nömrəsi qəbul hadisəsi olmadan sintaktik baxımdan etibarlı ola bilər. Daşıyıcının qəbulunu ayrıca əməliyyat mərhələsi kimi nəzərdən keçirin və orijinal hadisə məlumatlarını saxlayın.

Hər USPS hadisəsi müştəri bildirişinə çevrilməlidir?

Xeyr. Əvvəlcə hadisələri daxildə normallaşdırın, sonra əhəmiyyətli mərhələlər və istisnalar üçün bildiriş qaydalarını müəyyənləşdirin. Həddindən artıq bildirişlər skanlar təkrarlandıqda və ya əməliyyat baxımından əhəmiyyətsiz olduqda çaşqınlıq yarada bilər.

Çoxdaşıyıcılı API USPS sənədlərini əvəz edə bilər?

Xeyr. Çoxdaşıyıcılı platforma inteqrasiyanı və normallaşdırmanı sadələşdirə bilər, lakin tətbiq üçün yenə də cari provayder sənədləri, hesab şərtləri, sahə uyğunlaşdırmaları və daşıyıcıya xas istisnaların idarə edilməsi prosesi lazımdır.

İşə salınmazdan əvvəl nə test edilməlidir?

İlkin skanları, çatdırılma və istisna statuslarını, dublikat və ardıcıllığı pozulmuş cavabları, autentifikasiya xətalarını, vaxt aşımını, uyğunlaşdırılmamış izləmə nömrələrini, çoxsaylı bağlamaları və qaytarmaya xas iş proseslərini test edin. Həmçinin anbar, dəstək və geri ödəniş sistemlərinin hər normallaşdırılmış statusa necə reaksiya verdiyini yoxlayın.

Mənbələr

• USPS Developer Portal — mövcud developer girişi və API məlumatları.
• USPS Web Tools and APIs — USPS biznes API materialları və proqram məlumatları.
• USPS Tracking — rəsmi izləmə interfeysi və daşıyıcı statusu konteksti.
• 17TRACK Tracking API — API əsaslı izləmə üçün rəsmi məhsul məlumatları.
• 17TRACK API Documentation — rəsmi developer sənədləri.