API sifarişlərinin tamamlanması barədə bildirişləri necə qurmaq olar

Hansı hadisələr sifarişin tamamlanması sayılmalıdır

Əvvəlcə API-də hansı statusun sifarişin faktiki tamamlanması demək olduğunu müəyyənləşdirin. Müxtəlif təchizatçılarda bu, icra edilmiş, çatdırılmış, ləğv edilmiş, rədd edilmiş, qaytarılmış və ya qismən icra edilmiş sifariş ola bilər. Avtomatlaşdırmanı yalnız «uğur» sözünə bağlamayın: sifariş bir neçə aralıq vəziyyətdən keçə, sonra isə limit, yoxlama və ya ləğv səbəbindən dayana bilər.

Yalnız müsbət nəticəni emal etmək lazım deyil. Əgər servis xəta, ləğv, qaytarma və ya qismən icra barədə bildiriş göndərirsə, bu da daxili sistemə yazılmalıdır. Əks halda paneldə, CRM-də və ya botda sifariş gözləmə vəziyyətində qalacaq, halbuki sonrakı icra artıq baş verməyəcək.

Statusların uyğunluq cədvəlini tərtib edin

API statusunu emal etmədən interfeysə ötürməyin. Təchizatçının adları və məntiqi dəyişə bilər, eyni daxili status isə bəzən bir neçə xarici statusu birləşdirir. İlkin dəyəri ayrıca saxlayın: bu, xətaların araşdırılması və sənədləşmə ilə tutuşdurma üçün lazım olacaq.

• pending, created, queued — yeni və ya emal gözləyən sifariş.
• processing, in_progress, running — sifariş icra olunur.
• completed, delivered, success — icra edilmiş sifariş.
• partial, partially_completed — qismən icra edilmiş sifariş.
• cancelled, rejected, failed — ləğv edilmiş və ya xəta ilə bitmiş sifariş.
• refunded, returned — sifariş qaytarma və ya düzəliş tələb edir.
• Naməlum status — kartı avtomatik dəyişmir və yoxlamaya ötürülür.

Yuxarıdakı adlar sxem nümunəsi kimi verilmişdir. Yekun cədvəl konkret API-nin statusları əsasında qurulmalıdır. Əl ilə xəritələşdirmənin çatışmazlığı ondadır ki, API yeniləndikdən sonra onu dəstəkləmək lazımdır: yeni status üçün qayda yaranmazdan əvvəl emal ediciyə düşə bilər.

Webhook-ları, API sorğusunu və ya hər iki sxemi seçin

Webhook — sifarişin statusu dəyişdikdə servisin sizin URL-ünizə göndərdiyi sorğudur. API sorğusu isə əksinə işləyir: sizin sistem müəyyən intervaldan sonra sifariş barədə məlumat sorğulayır. Tamamlanma barədə bildirişlər üçün adətən webhook-lar daha rahatdır, çünki yenilənmə status yoxlama metoduna daimi sorğular göndərmədən gəlir.

• Webhook-lar sürətli reaksiya üçün uyğundur: kartın yenilənməsi, növbəti mərhələnin başladılması və ya məsul şəxsə mesaj göndərilməsi.
• Sorğu üsulu təchizatçı callback-bildirişlərini dəstəkləmədikdə və ya server xarici sorğuları qəbul etmədikdə uyğundur.
• Birləşdirilmiş sxem webhook-lardan əsas kanal kimi istifadə edir, sorğu üsulu isə buraxılmış və ya ilişib qalmış sifarişlərin axtarışı üçün.

Sorğu üsulunun çatışmazlığı — gecikmə və API-yə artıq yükdür. Webhook-ların çatışmazlığı — endpoint-i qorumaq, dublikatları nəzərə almaq və hadisələrin çatdırılma ardıcıllığına arxalanmamaq lazımdır.

Hadisələrin qəbulu üçün endpoint qurun

Bildirişlər üçün API-servis tərəfindən əlçatan olan publik HTTPS ünvanı lazımdır. İnteqrasiya parametrlərində adətən emal edicinin URL-i, imza sirri və hadisələrin siyahısı göstərilir: statusun dəyişməsi, tamamlanma, ləğv, xəta və ya qismən icra.

Yalnız API hadisələri üçün ayrıca marşrut ayırın. Beləliklə jurnallaşdırmanı qurmaq, girişi məhdudlaşdırmaq, sorğu limitlərini təyin etmək və xidməti trafiki saytın formaları ilə qarışdırmamaq daha asan olar. İşçi sifarişlər üçün test mühitinin ünvanından istifadə etməyin: mühit yeniləndikdən sonra təchizatçı hadisələri saxlanılmış URL-ə göndərməyə davam edəcək.

İşə salmazdan əvvəl sorğu metodunu və gövdə formatını sənədləşməyə əsasən yoxlayın. Çox vaxt bu, JSON ilə POST olur, lakin form-data, query-parametrlər və ya öz seriyalaşdırma sxeminə də rast gəlinir. Emal xətası jurnala yazılmalıdır, əks halda səhv payload-u tətbiqin nasazlığından ayırmaq çətin olacaq.

Sifarişlə hadisə arasındakı əlaqəni saxlayın

API vasitəsilə sifariş yaradarkən təchizatçının qaytardığı identifikatoru saxlayın. Yanında daxili sifariş nömrəsini, xidmətin növünü, ilkin statusu, son dəyişiklik vaxtını və API-nin ilkin cavabını təhlükəsiz formada saxlayın. Daxil olan webhook-u kanala keçid, xidmətin adı və ya müştərinin adı ilə deyil, təchizatçının ID-si ilə tutuşdurun.

Əgər API yaradılma zamanı xarici identifikator ötürməyə icazə verirsə, öz sifariş nömrənizi external_id və ya client_reference kimi sahəyə əlavə edin. Bu, loqlarda axtarışı və mübahisəli halların araşdırılmasını asanlaşdırır. Lakin xarici nömrəni yeganə açar etməyin: bəzi təchizatçılar onu hər bildirişdə qaytarmır.

Webhook-dan gələn naməlum ID ilə yeni sifariş yaratmayın. Naməlum hadisə jurnala yazılmalı və ayrıca yoxlanmalıdır. Qeydin avtomatik yaradılması səhv məlumatlara və ya saxta sorğunun emalına səbəb ola bilər.

Aydın payload strukturundan istifadə edin

Sahələrin dəqiq adları API-dən asılıdır. Aşağıdakı konkret servisin kontraktı deyil, daxili emal edicinin layihələndirilməsi zamanı rəhbər tutula biləcək JSON-hadisə nümunəsidir. Hadisənin identifikatoru, təchizatçıda sifarişin ID-si, status, dəyişiklik vaxtı və diaqnostika üçün məlumatlar vacibdir.

{

  "event_id": "evt_7f31",

  "event_type": "order.status_changed",

  "created_at": "2025-01-15T12:40:00Z",

  "data": {

    "order_id": "provider_order_4815",

    "external_id": "internal_order_9021",

    "status": "completed",

    "completed_quantity": 1000,

    "requested_quantity": 1000

  }

}

İcra edilmiş vahidlərin sayını status olmadan tamamlanma əlaməti kimi istifadə etməyin. Sifariş qismən icra edilə bilər, payload-dakı rəqəm isə yuvarlaqlaşdırıla, gecikmə ilə yenilənə və ya ümumiyyətlə ötürülməyə bilər. Hadisənin tam gövdəsinin saxlanmasının çatışmazlığı ondadır ki, orada şəxsi məlumatlar və ya xidməti sahələr ola bilər, buna görə belə qeydlər maskalanmalı və saxlama müddəti məhdudlaşdırılmalıdır.

İmzanı sorğunun ilkin gövdəsinə əsasən yoxlayın

Emal edicinin açıq URL-i sorğunu yalnız API-servisdən ala bilməz. Əgər təchizatçı imza, sirr və ya token ötürürsə, sifarişi dəyişməzdən əvvəl onları yoxlayın. Geniş yayılmış sxem HMAC-SHA256-dır: təchizatçı sorğu gövdəsinin baytlarından və ümumi sirrdən imza hesablayır, sonra nəticəni HTTP başlığında ötürür.

Hesablama prinsipi belədir: ilkin sorğu gövdəsi, məsələn dəyişdirilməmiş JSON baytları, və inteqrasiyanın sirri götürülür. Sonra HMAC-SHA256 hesablanır. Əgər onaltılıq formada nəticə başlıqdakı dəyərlə üst-üstə düşürsə, gövdə imzalandıqdan sonra dəyişməyib və sorğu, ehtimal ki, sirri bilən tərəf tərəfindən göndərilib.

Şərti nümunə: HMAC_SHA256(sirr, raw_body) = X-Signature başlığındakı imza. Başlığın adı, alqoritm və nəticənin formatı yalnız API sənədləşməsindən götürülməlidir. Bəzi servislər imza üçün sətrə zaman nişanı və ya hadisə ID-si əlavə edir. Bu halda yalnız JSON gövdəsini yoxlamaq olmaz.

İmzanı yoxlamazdan əvvəl JSON-u dəyişməyin

İmza tətbiqin artıq emal edib yenidən yığdığı JSON obyektinə görə deyil, sorğunun ilkin baytlarına görə yoxlanılır. Təkrar seriyalaşdırma zamanı sahələrin sırası, boşluqlar, simvolların ekranlaşdırılması, sətir keçidi və ya kodlaşdırma dəyişə bilər. İnsan üçün JSON eyni qalacaq, lakin bayt dəsti dəyişəcək və HMAC artıq uyğun gəlməyəcək.

Bunun qarşısını almaq üçün əvvəlcə raw body-ni bytes və ya buffer kimi alın, yaddaşda saxlayın, imzanı hesablayın və yalnız uğurlu yoxlamadan sonra JSON-u emal edin. Gövdəyə trim, kodlaşdırma çevrilməsi, açarların sıralanması və formatlaşdırma tətbiq etməyin. Freymvorkun middleware-ində ilkin gövdəyə çıxışdan əvvəl JSON-un avtomatik emal edilib-edilmədiyini yoxlayın.

Bu sxemin çatışmazlığı — emal edici middleware sırasından asılı olur. Səhv konfiqurasiya zamanı tətbiq yalnız çevrilmiş obyekti görəcək və qanuni bildirişlər rədd edilməyə başlayacaq.

HMAC yoxlaması ilə emal edici nümunəsi

Aşağıda Python dilində şərti nümunə verilmişdir. O, hazır inteqrasiyanı deyil, hərəkətlərin ardıcıllığını göstərir: başlıqlar, alqoritm, imza formatı və payload sahələri təchizatçının sənədləşməsindəki dəyərlərlə əvəz edilməlidir.

import hmac

import hashlib

import json

from hmac import compare_digest

def handle_webhook(request):

  raw_body = request.body

  received_signature = request.headers.get("X-Signature", "")

  secret = get_webhook_secret()

  expected_signature = hmac.new(

    secret.encode("utf-8"), raw_body, hashlib.sha256

  ).hexdigest()

  if not compare_digest(expected_signature, received_signature):

    log_invalid_signature(request)

    return response(status=401)

  payload = json.loads(raw_body.decode("utf-8"))

  return process_event(payload)

Müqayisə üçün ilk uyğunsuz simvolda işini dayandırmayan funksiyadan istifadə edin. Bu, cavab vaxtı vasitəsilə imza barədə məlumatların sızması riskini azaldır. Sirri müştəri koduna ötürməyin, URL-ə əlavə etməyin və loqlara tam şəkildə yazmayın.

Hadisələrin emalını idempotent edin

Təchizatçı eyni hadisəni bir neçə dəfə çatdıra bilər. Səbəblər adidir: serveriniz uzun müddət cavab verdi, məlumatlar saxlanıldıqdan sonra bağlantı kəsildi, endpoint müvəqqəti xəta qaytardı və ya servis öz qaydalarına əsasən təkrar çatdırılmanı başlatdı. Təkrar API-nin yeni sifariş yaratdığı anlamına gəlmir.

İdempotentlik o deməkdir ki, eyni hadisə nəticəni yalnız bir dəfə dəyişir. Bu qayda nəzərə alınmasa, dublikat müştəriyə mesajı təkrar göndərəcək, menecerə bir neçə tapşırıq yaradacaq, kompensasiya hesablayacaq və ya təkrar əməliyyatı başladacaq.

Ən yaxşısı payload-dakı event_id-dən istifadə etməkdir. Onu ayrıca cədvəldə və ya unikal məhdudiyyətli emal edilmiş hadisələr jurnalında saxlayın. Əgər ayrıca ID yoxdursa, açarı sabit sahələrdən formalaşdırın: təchizatçının sifariş ID-si, hadisənin növü, status və dəyişiklik vaxtı. Bu variant daha pisdir: qeyri-dəqiq zaman nişanları zamanı müxtəlif hadisələr eyni görünə bilər.

Hadisəni və statusu bir əməliyyatda saxlayın

«Hadisə emal edilibmi» yoxlaması və nəticənin yazılması atomar yerinə yetirilməlidir. Əks halda eyni vaxtda gələn iki eyni sorğu hər ikisi qeydin olmadığını görəcək və əməliyyatı iki dəfə başladacaq. Praktik variant — event_id üzrə unikal indeks və verilənlər bazası tranzaksiyasıdır.

Emal edicinin şərti davamı belə görünür:

def process_event(payload):

  event_id = payload["event_id"]

  provider_order_id = payload["data"]["order_id"]

  new_status = map_status(payload["data"]["status"])

  with database_transaction():

    if event_exists(event_id):

      return response(status=200)

    order = find_order_by_provider_id(provider_order_id)

    if order is None:

      save_unmatched_event(event_id, payload)

      return response(status=200)

    apply_status_if_allowed(order, new_status, payload)

    save_processed_event(event_id, provider_order_id)

  enqueue_follow_up_actions(event_id)

  return response(status=200)

Naməlum sifariş üçün uğurlu kodla cavabın çatışmazlığı — təchizatçı çatdırılmanı təkrarlamaya bilər. Buna görə naməlum hadisələr ayrıca monitorinq edilməli və tez araşdırılmalıdır. Əgər API sənədləşməsi belə hallar üçün başqa cavab kodu tövsiyə edirsə, ona əməl edin.

Hadisələrin ardıcıllığının pozulmasını nəzərə alın

Webhook-lar həmişə statusun dəyişmə vaxtına ciddi uyğun gəlmir. Əvvəlcə tamamlanma barədə hadisə, sonra isə «icrada» statusu barədə gecikmiş bildiriş gələ bilər. Əgər sadəcə son alınan dəyəri yazsanız, icra edilmiş sifariş yenidən aktiv olacaq.

İcazə verilən keçidləri təyin edin. Məsələn, aralıq status yekun statusun üzərinə yaza bilməz, ləğv edilmiş sifariş isə ayrıca yoxlama olmadan icra edilmiş vəziyyətə keçirilmir. Əgər API yekun statusun düzəlişinə icazə verirsə, səbəbi, ilkin dəyəri və dəyişiklik mənbəyini saxlayın.

Əgər payload sifarişin dəyişiklik vaxtını ehtiva edirsə, webhook-un alınma vaxtını deyil, məhz onu müqayisə edin. API belə nişan ötürmürsə, vəziyyətlərin prioritetlərindən və sifarişin alınması metodu vasitəsilə tutuşdurmadan istifadə edin. Prioritetlərin çatışmazlığı — onlar real ardıcıllığı əvəz etmir, xüsusən təchizatçı yekun statusdan qaytarmaya icazə verirsə.

Çatdırılmanı tez təsdiqləyin və əməliyyatları növbəyə çıxarın

Təchizatçıya cavab verməzdən əvvəl uzun əməliyyatları yerinə yetirməyin. İmzanın yoxlanması, sifarişin axtarışı, hadisənin yazılması və statusun yenilənməsi adətən tez tamamlana bilər. Mesajın göndərilməsi, CRM ilə sinxronizasiya, hesabatın formalaşdırılması və ya üçüncü tərəf sistemlərə sorğular tapşırıqlar növbəsinə ötürülməlidir.

İş qaydası belədir: imzanı yoxla, hadisəni və status dəyişikliyini atomar saxla, uğurlu cavab qaytar, sonra ikinci dərəcəli əməliyyatları yerinə yetir. Əgər saxlamaqdan əvvəl cavab versəniz, nasazlıq zamanı məlumatlar itəcək. Əgər uzun bildiriş göndərilməsindən sonra cavab versəniz, təchizatçı çatdırılmanı uğursuz hesab edib dublikat göndərə bilər.

Növbənin çatışmazlığı — nəzarət edilməli ayrıca komponent yaranır: tapşırıqların xətaları, gecikmələr və təkrar işə salınmalar. Lakin menecerə bildirişdəki nasazlıq sifariş statuslarının qəbulunu bloklamır.

Komanda və müştəri üçün bildirişləri qurun

Status dəyişdikdən sonra hamını eyni cür məlumatlandırmaq lazım deyil. Menecer üçün adətən ləğvlər, xətalar, qismən icra və uzun müddət dəyişməyən sifarişlər vacibdir. Müştəri üçün çox vaxt aydın yekun kifayətdir: sifariş icra edildi, ləğv edildi və ya dəqiqləşdirmə tələb edir.

• Tamamlanmış sifariş — şəxsi kabinetdə yenilənmə və ya müştəriyə qısa mesaj.
• İcra xətası — API-nin ötürdüyü səbəblə məsul şəxsə bildiriş.
• Qismən icra — düzəliş, qaytarma və ya növbəti əməliyyat üçün yoxlama tapşırığı.
• Naməlum status — jurnala yazı və texniki mütəxəssisə mesaj.
• Naməlum sifariş ID-si — sizin sistemlə təchizatçı arasındakı əlaqənin ayrıca yoxlanması.

Hər texniki keçiddə mesaj göndərməyin. Lent tez bir zamanda səs-küyə çevriləcək və vacib problem diqqətdən kənarda qalacaq. Daxili bildiriş sifariş nömrəsini, xidməti, cari statusu, xarici ID-ni və kartın keçidini ehtiva etməlidir.

Jurnal aparın və tamamlanmamış sifarişləri tutuşdurun

Loqlar servisin hadisə göndərib-göndərmədiyini, hansı gövdənin gəldiyini, imzanın niyə keçmədiyini və emalın hansı mərhələdə dayandığını anlamaq üçün lazımdır. Alınma vaxtını, hadisə ID-sini, sifariş ID-sini, hadisənin növünü, imza yoxlamasının nəticəsini, daxili statusu və cavab kodunu saxlayın. Sirrləri, tokenləri və şəxsi məlumatları maskalayın.

Çatdırılma xətalarını, etibarsız imzaları, naməlum sifarişləri, dəstəklənməyən statusları, dublikatları və vəziyyətlərin ardıcıllığı səbəbindən tətbiq edilə bilməyən hadisələri ayrıca izləyin. Belə qeydlərin artması API sxeminin dəyişməsi, sirrin vaxtının bitməsi, marşrutun nasazlığı və ya emal edicinin məntiqində xəta anlamına gələ bilər.

Aralıq statuslardakı sifarişləri vaxtaşırı API məlumatlarının alınması metodu vasitəsilə tutuşdurun. Bu yoxlama webhook-ları əvəz etmir, lakin buraxılmış hadisəni, növbənin nasazlığını və ya xarici statusun düzgün bildiriş olmadan dəyişdiyi halı aşkar etməyə kömək edir.