Göndərmə API-sində çatdırılma statusu: status kodları, vebhuklar və istisna xəbərdarlıqları

Çatdırılma API-sində çatdırılma statusu API sorğusunun uğurlu olub-olmadığını deyil, bağlamanın irəliləyişini təsvir edir. Etibarlı izləmə sistemi qurmaq üçün HTTP cavab kodlarını göndəriş statuslarından ayrı saxlayın, webhook-ları onların yalnız bir dəfə və ya ardıcıllıqla gələcəyini düşünmədən emal edin və tədbir görülməsini tələb edən istisnaları məsul şəxsləri aydın göstərən xəbərdarlıqlara çevirin. Mühəndislik və e-ticarət əməliyyatları komandaları üçün məqsəd daşıyıcı yeniləmələri gecikdirildikdə, təkrarlandıqda və ya düzəldildikdə də etibarlı qalan göndəriş qeydidir.

Bu təlimat həmin qeydin necə strukturlaşdırılacağını, daxil olan izləmə hadisələrinin necə idarə ediləcəyini və çatdırılma problemi ilə izləmə inteqrasiyası probleminin necə fərqləndiriləcəyini izah edir.

HTTP kodlarını, API nəticələrini və göndəriş statuslarını ayırın

“Status kodu” ifadəsi üç fərqli təbəqəyə aid ola bilər. Onları qarışdırmaq yanıltıcı panellər və lazımsız müştəri bildirişləri yaradır.

Təbəqə	Nəyi bildirir	Nümunə izah
HTTP cavabı	HTTP sorğusunun nəticəsi	200 cavabı HTTP səviyyəsində uğuru göstərir; bu, bağlamanın çatdırıldığı demək deyil.
API biznes nəticəsi	Tələb olunan əməliyyatın provayderin tətbiq qaydalarına əsasən uğurlu olub-olmaması	API bu dizayndan istifadə edirsə, hətta uğurlu HTTP cavabı daxilində belə cavab gövdəsi izləmənin qeydiyyata alınmasının rədd edildiyini bildirə bilər.
Göndəriş statusu	Bağlamanın bildirilmiş fiziki və ya əməliyyat vəziyyəti	Yoldadır, götürülməyi gözləyir və ya çatdırılıb.

HTTP semantikası standartı HTTP cavablarının mənalarını müəyyən edir. Məsələn, 202 Accepted sorğunun emal üçün qəbul edildiyini, lakin emalın mütləq başa çatmadığını bildirir. Bu, daşıyıcının bağlamanı qəbul etdiyinə dair sübut deyil.

Eyni şəkildə, uğursuz izləmə sorğusu göndərişin hərəkətini dayandırdığını sübut etmir. Fiziki çatdırılma normal davam etdiyi halda tətbiqiniz müvəqqəti olaraq görünürlüğü itirə bilər. Bu təbəqələri müstəqil şəkildə izləyin.

Daşıyıcı təfərrüatlarını itirmədən status modeli yaradın

Bütün shipping API-lər və daşıyıcılar tərəfindən paylaşılan universal rəqəmsal çatdırılma-status kodu yoxdur. Bir inteqrasiyadan alınan dəyər başqa provayderin xəritələndirməsindən istifadə edilərək şərh edilməməlidir. Tətbiq etdiyiniz konkret API versiyasının sənədlərindən istifadə edin.

Praktik daxili model az sayda normallaşdırılmış statusu ilkin daşıyıcı hadisəsi ilə birləşdirir. Normallaşdırma ardıcıl hesabatları dəstəkləyir; ilkin hadisə isə araşdırma üçün lazım olan təfərrüatı qoruyur.

Nümunə daxili status	Məna	Əməliyyat xəbərdarlığı
Məlumat alındı	Elektron göndəriş məlumatı mövcuddur.	Etiketin yaradılmasını fiziki təhvilin təsdiqi kimi qəbul etməyin.
Yoldadır	İzləmə qeydi çatdırılma şəbəkəsində hərəkəti göstərir.	Bu geniş kateqoriyaya müxtəlif daşınma mərhələləri daxil ola bilər.
Çatdırılma üçün çıxıb	Bağlamanın çatdırılma marşrutunda olduğu bildirilir.	Bunu qeyd-şərtsiz çatdırılma zəmanətinə çevirməyin.
Götürülməyi gözləyir	Alıcının bağlamanı götürməsi gözlənilir.	Götürülmə təlimatlarını və ya son tarixləri yalnız mənbə onları dəstəklədikdə daxil edin.
Çatdırılıb	İzləmə mənbəyi çatdırılmanı bildirir.	Çatdırılma skanı öz-özlüyündə müştərinin bağlamanı almadığı iddiasını həll etmir.
İstisna	Hadisə diqqət tələb edə və ya normal irəliləyişi dayandıra bilər.	Hər istisnanı itki kimi qəbul etmək əvəzinə səbəbi saxlayın.
Qaytarılma prosesindədir və ya qaytarılıb	Bağlama geri hərəkət edir və ya qaytarılmanın başa çatdığı bildirilir.	Qaytarılma prosesini ilkin alıcıya çatdırılmadan ayrı saxlayın.
Naməlum	Mövcud məlumat inamla xəritələndirilə bilmir.	Çatdırılma vəziyyəti uydurmaq əvəzinə xəritələndirməni və ya məlumat boşluğunu araşdırın.

Bu etiketlər rəsmi 17TRACK kod siyahısı deyil, tövsiyə olunan tətbiq modelidir. Mövcud olduqda provayderin status kodunu, alt statusunu, təsvirini, hadisə vaxtını, saat qurşağı məlumatını, məkanı və qəbul vaxtını qoruyun. Xəritələndirmənin sonrakı dəyişikliklərinin audit edilə bilməsi üçün xəritələndirmə versiyasını da saxlayın.

Çoxdaşıyıcılı tətbiq üçün 17TRACK Tracking API uyğun inteqrasiya seçimidir. Tətbiq müqaviləsini müəyyən etmək üçün nümunəvi etiketləri provayderə xas sahələrə köçürmək əvəzinə onun rəsmi API sənədlərindən istifadə edin. Adapteri hazırlamazdan əvvəl tətbiq olunan status təriflərini, webhook konfiqurasiyasını, autentifikasiya tələblərini və cavab semantikasını təsdiqləyin.

Webhook emalını davamlı qəbul üzərində qurun

Webhook hadisə barədə məlumat vermək üçün endpoint-inizə göndərilən HTTP sorğusudur. O, təkrar sorğulara ehtiyacı azalda bilər, lakin dərhal, ardıcıl və ya dəqiq bir dəfə çatdırılma zəmanəti kimi qəbul edilməməlidir. Provayder açıq şəkildə başqa cür zəmanət vermədikcə, qəbul edən sistemi təkrar cəhdlərə, kəsintilərə və gözlənilməz payload-lara dözümlü şəkildə dizayn edin.

1. Sorğunu autentifikasiya edin. Provayderin sənədləşdirilmiş yoxlama metodunu tətbiq edin. İmzalar dəstəklənirsə, onları göstərilən alqoritm və xam sorğu baytlarından istifadə etməklə yoxlayın. İmza başlığı uydurmayın və hər xidmətin HMAC istifadə etdiyini düşünməyin.
2. Payload-u yoxlayın. Tələb olunan sahələri, tipləri, payload ölçüsünü və hesabınızın idarə etdiyi göndərişlə əlaqəni yoxlayın. Gələcək uyğunluğu lazımsız şəkildə pozmadan naməlum əlavə sahələri idarə edin.
3. Təsdiqdən əvvəl saxlayın. Sənədləşdirilmiş uğur cavabını göndərməzdən əvvəl qəbul edilmiş hadisəni saxlayın və ya davamlı növbəyə yerləşdirin. Saxlama uğursuz olarsa, hadisəni təhlükəsiz qəbul edilmiş kimi təsdiqləməyin.
4. Asinxron emal edin. Praktik olduğu hallarda status xəritələndirməsini, sifariş yeniləmələrini və bildiriş qərarlarını sorğu işləyicisindən kənarda həyata keçirin.
5. Yan təsirləri idempotent edin. Təkrarlanan hadisə əlavə dəstək bileti yaratmamalı və eyni müştəri mesajının əlavə nüsxəsini göndərməməlidir.

Dəqiq təsdiq kodu, vaxt aşımı, təkrar cəhd cədvəli və təkrar oynatma davranışı provayderdən asılıdır. Bu təfərrüatları açıq şəkildə yoxlayın. “200 qaytarın” kimi ümumi təlimat webhook müqaviləsini əvəz etmir.

HTTPS istifadə edin və giriş məlumatlarını URL-lərdən və adi jurnallardan uzaq saxlayın. Saxlanılan payload-lara giriş nəzarəti tətbiq edin, çünki izləmə məlumatlarında şəxsi informasiya ola bilər. OWASP REST Security Cheat Sheet nəqliyyatın qorunması, giriş məlumatlarının yoxlanılması və endpoint təhlükəsizliyi üzrə müvafiq təlimatlar təqdim edir.

Həqiqi yeniləmələri gizlətmədən hadisələri təkrarlanmalardan ayırın

Mümkün olduqda sənədləşdirilmiş, sabit hadisə identifikatoruna üstünlük verin. Əks halda, göndəriş identikliyi, hadisə vaxtı, hadisə kodu və məkanın diqqətlə seçilmiş kombinasiyasından təkrarlanmanın qarşısını alan açar yaradın. Bu yanaşmanı real payload-larla yoxlayın: iki qanuni hadisə eyni vaxt nişanını paylaşa bilər və eyni hadisə bir qədər fərqli təsviri mətnlə gələ bilər.

Hadisələrin qəbulu və sonrakı əməliyyatlar üçün ayrı təkrarlanma nəzarətlərindən istifadə edin. Status yeniləməsi düzəliş kimi yenidən saxlanmalı, lakin müştəri bildirişi göndərilməməlidir. Hər bildiriş və ya bilet əməliyyatına öz davamlı identikliyini verin.

Hadisə vaxtını qəbul vaxtından ayrı saxlayın

Tutaq ki, yolda olma hadisəsi çatdırılma üçün çıxma hadisəsindən sonra sisteminizə çatır, lakin onun daşıyıcı vaxt nişanı daha əvvələ aiddir. Onu tarixçədə saxlayın, lakin cari statusu avtomatik olaraq yenidən “yoldadır” vəziyyətinə dəyişməyin.

Yalnız vaxt nişanlarının ardıcıllığı hər vəziyyət üçün kifayət deyil. Çatışmayan saat qurşaqları, düzəldilmiş skanlar və ziddiyyətli mənbələr açıq qaydalar tələb edir. Vaxt nişanının dəqiqliyini və ofsetlərini qoruyun, sisteminizin hər hadisəni nə vaxt qəbul etdiyini qeyd edin və mövcud olduqda sənədləşdirilmiş provayder ardıcıllığı məlumatından istifadə edin. Sərt, yalnız irəliyə doğru status pilləsi tətbiq etməyin: çatdırılma cəhdləri, yönləndirmələr, qaytarmalar və düzəlişlər geriyə hərəkət kimi görünən qanuni keçidlər yarada bilər.

İstisnaları məsul şəxslərin üzərinə düşən tədbirlərə çevirin

İstisna xəbərdarlığı nə baş verdiyini, hansı tədbirin tələb olunduğunu və növbəti addıma kimin cavabdeh olduğunu izah etməlidir. Ümumi “göndəriş istisnası” mesajı əməliyyat əməkdaşlarını eyni araşdırmanı təkrarlamağa məcbur edir və müştəriləri faydalı məlumat vermədən narahat edə bilər.

Kiçik marşrutlaşdırma siyasəti ilə başlayın:

• Ünvan və ya giriş problemi: Problemi yoxlamaq və daşıyıcının mövcud düzəliş prosesini öyrənmək üçün müştəri dəstəyinə yönləndirin. Mümkün olduğunu təsdiqləmədən ünvan dəyişikliyinə söz verməyin.
• Götürülmə tələb olunur: Mənbə istifadə edilə bilən götürülmə təlimatı verdikdə alıcıya bildiriş göndərin. Təsdiqlənmiş son tarixi qoruyun.
• Gömrük tədbiri tələb olunur: İşi tələb olunan sənədləri və ya məlumatı təqdim etməli olan şəxsi nəzərə alaraq təyin edin. Təkcə gömrüklə bağlı hadisə ödənişin tələb olunduğunu müəyyən etmir.
• Uğursuz çatdırılma cəhdi: Yenidən çatdırılma və ya götürülmə barədə məsləhət verməzdən əvvəl bildirilmiş növbəti addımı yoxlayın.
• Göndərənə qaytarılır: Əməliyyat baxışı başladın. Siyasətiniz bunu açıq şəkildə təsdiqləmədikcə, yalnız ümumi izləmə etiketinə əsasən avtomatik geri ödəniş etməyin.
• Daşıyıcının bildirdiyi itki və ya zərər: İşi iddia üzrə məsul şəxsə yönləndirin və hadisə sübutlarını qoruyun. İddia qərarlarını ümumi gecikmə aşkarlanmasından ayrı saxlayın.

Hər xəbərdarlıqda göndəriş identifikatoru, sifariş istinadı, hadisə səbəbi, mənbə vaxt nişanı, son məlum vəziyyət, təyin edilmiş məsul şəxs və növbəti tədbir olmalıdır. Paylaşılan mesaj kanallarında lazımsız müştəri təfərrüatlarını göstərmək əvəzinə müvafiq daxili qeydə keçid əlavə edin.

“Yeniləmə yoxdur” vəziyyətini ayrıca şərt kimi qəbul edin

Son skanı olmayan göndəriş avtomatik olaraq itmiş sayılmır. O, yoxlama məntəqələri arasında ola, ilk fiziki skanı gözləyə və ya görünürlük boşluğundan təsirlənə bilər.

Fəaliyyətsizlik hədlərini vahid taymer tətbiq etmək əvəzinə xidmətə, marşruta, daşınma mərhələsinə və biznes öhdəliyinə görə müəyyən edin. Qəbul skanı heç vaxt olmayan bağlamanı şəbəkəyə daxil olduqdan sonra yenilənməsi dayanan bağlamadan fərqləndirin. Tarixi sübut məhduddursa, itkini elan etmək üçün deyil, araşdırma başlatmaq üçün həddən istifadə edin.

Dəyişməz iş açıq qaldığı müddətdə təkrar xəbərdarlıqları susdurun. Yeni sübut yarandıqda, razılaşdırılmış təqib edilmədikdə və ya müştəriyə çatdırılma öhdəliyi müdaxilə tələb etdikdə işi eskalasiya edin.

İnteqrasiya sağlamlığını çatdırılma göstəricilərindən ayrı izləyin

API monitorinqi izləmə inteqrasiyanızın işlək olub-olmadığına cavab verir. Çatdırılma monitorinqi göndərişlərə nə baş verdiyini göstərir. Sağlam endpoint köhnəlmiş daşıyıcı məlumatlarını qəbul edə, əlçatmaz endpoint isə normal hərəkət edən bağlamalar üzrə yeniləmələri qaçıra bilər.

• Sorğu sağlamlığı: Autentifikasiya xətalarını, vaxt aşımını, limit cavablarını, server xətalarını və tətbiq səviyyəsində rədd edilmələri izləyin.
• Webhook sağlamlığı: Yoxlama xətalarını, təsdiq gecikməsini, saxlama xətalarını, təkrar çatdırılmaları və emal xətalarını izləyin.
• Emal sağlamlığı: Növbənin yaşını, emal edilməmiş hadisələri, xəritələndirmə xətalarını və bildiriş xətalarını monitorinq edin.
• İzləmə aktuallığı: Son mənbə hadisəsindən keçən vaxtı son uğurlu qəbulunuzdan keçən vaxtdan ayrı ölçün.
• Əməliyyat nəticələri: Həll edilməmiş istisnaları, məsul şəxsin təyin olunmasına qədərki vaxtı və vaxtı keçmiş təqibləri izləyin.

Sorğu təkrarları üçün provayderin limit və təkrar cəhd təlimatlarına əməl edin. Təkrar qeydiyyatlar və ya digər yan təsirlər yarada biləcək əməliyyatları kor-koranə təkrarlamaqdan çəkinin; mövcud olduqda sənədləşdirilmiş idempotentlik mexanizmlərindən istifadə edin.

Dəstəkləndikdə, kəsintilərdən və ya buraxılmış hadisələrdən şübhələndikdən sonra ən son izləmə qeydini əldə etmək üçün uzlaşdırma prosesindən istifadə edin. Onun tezliyini müqavilə və limitlər çərçivəsində müəyyən edin. Webhook-lar və uzlaşdırma fərqli məqsədlərə xidmət edir: biri dəyişiklikləri çatdırır, digəri isə boşluqları aşkarlamağa və düzəltməyə kömək edir.

Müştəri bildirişlərini aktivləşdirməzdən əvvəl uğursuzluq hallarını yoxlayın

Daxili emalla başlayın və status dəyişikliklərinin müştəri mesajları göndərməsinə icazə verməzdən əvvəl nümunəvi göndərişləri yoxlayın. Yoldan çatdırılmaya qədər normal irəliləyişdən daha çoxunu sınaqdan keçirin.

• Təkrar webhook yalnız nəzərdə tutulan bir müştəri bildirişi yaradır.
• Gecikmiş köhnə hadisə cari vəziyyəti səhvən əvəz etmir.
• Naməlum status sakitcə “çatdırılıb” kimi xəritələndirmək əvəzinə saxlanılır və işarələnir.
• Davamlı yazmanın uğursuz olması uğurlu təsdiq yaratmır.
• Müvəqqəti sonrakı sistem kəsintisi hadisələri təkrar cəhd üçün əlçatan saxlayır.
• Çatdırılma hadisəsindən sonra gələn düzəliş audit edilə bilən olaraq qalır.
• Çoxbağlamalı sifariş yalnız bir bağlama çatdırıldıqda tam çatdırılmış sayılmır.
• API kəsintisi mühəndisliyi xəbərdar edir, lakin bağlamaların gecikdiyini müştərilərə avtomatik bildirmir.

Buraxılış meyarı əməliyyat ardıcıllığı olmalıdır: göndəriş qeydi, müştəri mesajı və dəstək tədbiri eyni əsas sübutla uyğun gəlməlidir. Təkcə uğurlu webhook cavabı çatdırılma təcrübəsinin işlədiyini göstərmir.

FAQ

HTTP 200 bağlamanın çatdırıldığı deməkdir?

Xeyr. Bu, sorğunun HTTP səviyyəsində uğurlu olduğunu göstərir. API-nin biznes nəticəsini və göndəriş-status sahələrini ayrıca oxuyun. Webhook üçün uğurlu təsdiq fiziki bağlamanın çatdırılmasına deyil, bildirişin qəbuluna aiddir.

İzləmə yeniləmələri üçün webhook-lardan, yoxsa sorğulamalardan istifadə etməliyəm?

Provayder onları dəstəklədikdə hadisə əsaslı yeniləmələr üçün webhook-lardan istifadə edin. Dəstəkləndikdə və əməliyyat baxımından əsaslandırıldıqda boşluqları bərpa etmək üçün məhdud uzlaşdırma sorğulaması əlavə edin. Webhook-lar mövcud olmadıqda yalnız sorğulama uyğun ola bilər, lakin tezliyi provayderin limitlərinə və aktuallıq tələblərinizə uyğun olmalıdır.

“Çatdırılıb” statusundan sonra izləmə statusu niyə dəyişə bilər?

Mənbə hadisəni düzəldə bilər və ya inteqrasiyanız gecikmiş və ya ziddiyyətli məlumat ala bilər. Tarixçəni qoruyun və “çatdırılıb” statusunu texniki baxımdan dəyişməz hesab etmək əvəzinə daha yeni sübutu qiymətləndirin. Bildirilmiş çatdırılma ilə müştərinin qəbulu təsdiqləməsi də fərqli faktlardır.

İstisna xəbərdarlığı nə qədər tez göndərilməlidir?

Təciliyyəti tələb olunan tədbirə və təsdiqlənmiş son tarixə əsaslandırın. Alıcının tədbirini tələb edən problem məlumat xarakterli gecikmədən fərqli idarə olunmalıdır. Emal sürəti gec dərc edilmiş daşıyıcı hadisəsini kompensasiya edə bilməz; buna görə həm mənbə, həm də qəbul vaxt nişanlarını qoruyun.

Müştərilər xam daşıyıcı statusunu görməlidirlər?

Adətən müştərilər izah olunmamış kod əvəzinə aydın izah və dəstəklənən növbəti addımdan faydalanırlar. Xam təfərrüatları dəstək və audit məqsədləri üçün saxlayın. Statusu heç vaxt əsas hadisənin dəstəklədiyindən daha güclü vədə çevirməyin.

Mənbələr

• RFC 9110: HTTP Semantics — 200 və 202 daxil olmaqla HTTP status-kodlarının mənaları üçün istinad.
• OWASP REST Security Cheat Sheet — API və webhook endpoint-ləri üçün müvafiq təhlükəsizlik təlimatları.
• 17TRACK Tracking API — müzakirə olunan izləmə inteqrasiyası seçimi üzrə rəsmi məhsul istinadı.
• 17TRACK API Documentation — provayderə xas inteqrasiya tələbləri üzrə rəsmi istinad; bu təlimatdakı nümunəvi sxemlər və iş axını tövsiyələri həmin müqaviləni əvəz etmir.