API siparişlerinin tamamlanma bildirimleri nasıl yapılandırılır

Hangi olaylar siparişin tamamlanması sayılmalı

Öncelikle API'de hangi durumun siparişin fiilen tamamlandığı anlamına geldiğini belirleyin. Farklı sağlayıcılarda bu; tamamlandı, teslim edildi, iptal edildi, reddedildi, iade edildi veya kısmen tamamlandı durumlarından biri olabilir. Otomasyonu yalnızca "başarılı" kelimesine bağlamayın: sipariş birkaç ara durumdan geçip ardından limit, doğrulama veya iptal nedeniyle durabilir.

Yalnızca olumlu sonucu işlemek gerekmez. Hizmet hata, iptal, iade veya kısmi tamamlama bildirimi gönderiyorsa bu da iç sisteme kaydedilmelidir. Aksi halde panelde, CRM'de veya botta sipariş beklemede kalır, oysa sonraki işlem artık gerçekleşmeyecektir.

Durum eşleştirme tablosu oluşturun

API durumunu işlemeden arayüze aktarmayın. Sağlayıcının adlandırmaları ve mantığı değişebilir, aynı iç durum bazen birkaç dış durumu birleştirebilir. Orijinal değeri ayrıca saklayın: hata ayıklama ve dokümantasyonla karşılaştırma için işinize yarar.

• pending, created, queued — yeni veya işlenmeyi bekleyen sipariş.
• processing, in_progress, running — sipariş işleniyor.
• completed, delivered, success — tamamlanmış sipariş.
• partial, partially_completed — kısmen tamamlanmış sipariş.
• cancelled, rejected, failed — iptal edilmiş veya hatayla sonuçlanmış sipariş.
• refunded, returned — sipariş iade veya düzeltme gerektiriyor.
• Bilinmeyen durum — kartı otomatik olarak değiştirmez ve kontrole iletilir.

Yukarıdaki adlar örnek bir şema olarak verilmiştir. Nihai tablo, belirli bir API'nin durumlarına göre oluşturulmalıdır. Manuel eşleştirmenin dezavantajı, API güncellendikten sonra bunun sürdürülmesi gerektiğidir: yeni bir durum, kendisi için bir kural oluşturulmadan önce işleyiciye ulaşabilir.

Webhook'ları, API yoklamasını veya her iki şemayı seçin

Webhook, sipariş durumu değiştiğinde hizmetin sizin URL'nize gönderdiği istektir. API yoklaması tersi şekilde çalışır: sisteminiz belirli aralıklarla sipariş bilgisini sorgular. Tamamlanma bildirimleri için genellikle webhook'lar daha uygundur, çünkü güncelleme durum kontrol yöntemine sürekli istek atmadan gelir.

• Webhook'lar hızlı tepki için uygundur: kartı güncelleme, sonraki aşamayı başlatma veya sorumluya mesaj gönderme.
• Yoklama, sağlayıcı callback bildirimlerini desteklemiyorsa veya sunucu dış istekleri kabul etmiyorsa uygundur.
• Birleşik şema, webhook'ları ana kanal olarak, yoklamayı ise kaçırılan veya takılı kalan siparişleri bulmak için kullanır.

Yoklamanın dezavantajı gecikme ve API üzerinde gereksiz yüktür. Webhook'ların dezavantajı ise endpoint'i korumanız, kopyaları hesaba katmanız ve olayların teslimat sırasına güvenmemeniz gerektiğidir.

Olayları almak için endpoint yapılandırın

Bildirimler için API hizmeti tarafından erişilebilen genel bir HTTPS adresi gerekir. Entegrasyon ayarlarında genellikle işleyici URL'si, imza sırrı ve olay listesi belirtilir: durum değişikliği, tamamlanma, iptal, hata veya kısmi tamamlama.

Yalnızca API olayları için ayrı bir rota ayırın. Böylece günlük kaydını yapılandırmak, erişimi kısıtlamak, istek limitleri belirlemek ve servis trafiğini site formlarıyla karıştırmamak daha kolay olur. Çalışan siparişler için test ortamı adresini kullanmayın: ortam güncellendikten sonra sağlayıcı olayları kayıtlı URL'ye göndermeye devam eder.

Başlatmadan önce istek yöntemini ve gövde formatını dokümantasyona göre kontrol edin. Çoğunlukla bu, JSON içeren POST'tur, ancak form-data, query parametreleri veya özel bir serileştirme şemasıyla da karşılaşılabilir. Ayrıştırma hatası günlüğe kaydedilmelidir, aksi halde hatalı payload ile uygulama arızasını ayırt etmek zorlaşır.

Sipariş ile olay arasındaki bağlantıyı saklayın

API üzerinden sipariş oluştururken sağlayıcının döndürdüğü tanımlayıcıyı saklayın. Yanında dahili sipariş numarasını, hizmet türünü, orijinal durumu, son değişiklik zamanını ve orijinal API yanıtını güvenli biçimde saklayın. Gelen webhook'u kanal bağlantısı, hizmet adı veya müşteri adıyla değil, sağlayıcının ID'siyle eşleştirin.

API, oluşturma sırasında harici bir tanımlayıcı iletmeye izin veriyorsa sipariş numaranızı external_id veya client_reference gibi bir alana ekleyin. Bu, günlüklerde arama yapmayı ve tartışmalı durumları çözmeyi kolaylaştırır. Ancak harici numarayı tek anahtar yapmayın: bazı sağlayıcılar bunu her bildirimde döndürmez.

Webhook'taki bilinmeyen bir ID ile yeni sipariş oluşturmayın. Bilinmeyen olay günlüğe kaydedilmeli ve ayrıca kontrol edilmelidir. Kaydın otomatik oluşturulması hatalı verilere veya sahte bir isteğin işlenmesine yol açabilir.

Anlaşılır bir payload yapısı kullanın

Alanların tam adları API'ye bağlıdır. Aşağıdakiler belirli bir hizmetin sözleşmesi değil, dahili işleyiciyi tasarlarken yol gösterebilecek örnek bir JSON olayıdır. Önemli olanlar; olay tanımlayıcısı, sağlayıcıdaki sipariş ID'si, durum, değişiklik zamanı ve tanılama verileridir.

{

  "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

  }

}

Tamamlanan birim sayısını durum olmadan tamamlanma göstergesi olarak kullanmayın. Sipariş kısmen tamamlanmış olabilir, payload'daki sayı yuvarlanmış, gecikmeyle güncellenmiş veya hiç iletilmemiş olabilir. Olayın tam gövdesini saklamanın dezavantajı, içinde kişisel veriler veya servis alanları bulunabilmesidir; bu nedenle bu tür kayıtlar maskelenmeli ve saklama süresi sınırlandırılmalıdır.

İmzayı isteğin orijinal gövdesine göre doğrulayın

Açık işleyici URL'si yalnızca API hizmetinden değil, başka kaynaklardan da istek alabilir. Sağlayıcı bir imza, sır veya token iletiyorsa bunları siparişi değiştirmeden önce doğrulayın. Yaygın şema HMAC-SHA256'dır: sağlayıcı istek gövdesinin baytlarından ve ortak sırdan bir imza hesaplar, ardından sonucu bir HTTP başlığında iletir.

Hesaplama mantığı şöyledir: isteğin orijinal gövdesi, örneğin değiştirilmemiş JSON baytları ve entegrasyon sırrı alınır. Ardından HMAC-SHA256 hesaplanır. Sonuç onaltılık biçimde başlıktaki değerle eşleşiyorsa gövde imzalandıktan sonra değişmemiştir ve istek büyük olasılıkla sırrı bilen tarafça gönderilmiştir.

Koşullu örnek: HMAC_SHA256(sır, raw_body) = X-Signature başlığındaki imza. Başlık adı, algoritma ve sonuç formatı yalnızca API dokümantasyonundan alınmalıdır. Bazı hizmetler imza dizesine zaman damgası veya olay ID'si ekler. Bu durumda yalnızca JSON gövdesini doğrulamak yeterli değildir.

İmza doğrulamasından önce JSON'u değiştirmeyin

İmza, uygulamanın ayrıştırıp yeniden oluşturduğu JSON nesnesine göre değil, isteğin orijinal baytlarına göre doğrulanır. Yeniden serileştirme sırasında alan sırası, boşluklar, karakter kaçışları, satır sonu veya kodlama değişebilir. İnsan için JSON aynı kalır, ancak bayt kümesi değişir ve HMAC artık eşleşmez.

Bunu önlemek için önce raw body'yi bytes veya buffer olarak alın, bellekte saklayın, imzayı hesaplayın ve yalnızca başarılı doğrulamadan sonra JSON'u ayrıştırın. Gövdeye trim, kodlama dönüşümü, anahtar sıralaması ve biçimlendirme uygulamayın. Framework middleware'inde JSON'un orijinal gövdeye erişmeden önce otomatik olarak ayrıştırılıp ayrıştırılmadığını kontrol edin.

Bu şemanın dezavantajı, işleyicinin middleware sırasına bağımlı hale gelmesidir. Yanlış yapılandırmada uygulama yalnızca dönüştürülmüş nesneyi görür ve meşru bildirimler reddedilmeye başlar.

HMAC doğrulamalı örnek işleyici

Aşağıda Python'da koşullu bir örnek verilmiştir. Hazır bir entegrasyon değil, işlem sırasını gösterir: başlıklar, algoritma, imza formatı ve payload alanları sağlayıcının dokümantasyonundaki değerlerle değiştirilmelidir.

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)

Karşılaştırma için ilk uyuşmayan karakterde durmayan bir fonksiyon kullanın. Bu, yanıt süresi üzerinden imza hakkında veri sızması riskini azaltır. Sırrı istemci koduna aktarmayın, URL'ye eklemeyin ve günlüklere tamamen yazmayın.

Olay işlemeyi idempotent hale getirin

Sağlayıcı aynı olayı birkaç kez teslim edebilir. Nedenler olağandır: sunucunuz uzun süre yanıt vermedi, veriler kaydedildikten sonra bağlantı kesildi, endpoint geçici olarak hata döndürdü veya hizmet kendi kurallarına göre yeniden teslimat başlattı. Tekrar, API'nin yeni bir sipariş oluşturduğu anlamına gelmez.

İdempotency, aynı olayın sonucu yalnızca bir kez değiştirmesi anlamına gelir. Bu kural dikkate alınmazsa kopya, müşteriye yeniden mesaj gönderir, yöneticiye birkaç görev oluşturur, tazminat tahakkuk ettirir veya işlemi yeniden başlatır.

En iyisi payload'daki event_id'yi kullanmaktır. Bunu ayrı bir tabloda veya benzersiz kısıtlamalı işlenmiş olaylar günlüğünde saklayın. Ayrı bir ID yoksa anahtarı kararlı alanlardan oluşturun: sağlayıcının sipariş ID'si, olay türü, durum ve değişiklik zamanı. Bu seçenek daha kötüdür: zaman damgaları kesin değilse farklı olaylar aynı görünebilir.

Olayı ve durumu tek işlemde kaydedin

"Olay işlendi mi" kontrolü ve sonucun kaydedilmesi atomik olarak yapılmalıdır. Aksi halde aynı anda gelen iki aynı istek, ikisi de kaydın olmadığını görür ve işlemi iki kez başlatır. Pratik bir seçenek, event_id üzerinde benzersiz indeks ve veritabanı işlemidir.

İşleyicinin koşullu devamı şöyledir:

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)

Bilinmeyen sipariş için başarılı kodla yanıt vermenin dezavantajı, sağlayıcının teslimatı tekrarlamayabilmesidir. Bu nedenle bilinmeyen olaylar ayrıca izlenmeli ve hızla incelenmelidir. API dokümantasyonu bu tür durumlar için farklı bir yanıt kodu öneriyorsa ona uyun.

Olay sırasının bozulmasını hesaba katın

Webhook'lar her zaman durum değişikliği zamanına göre tam sırayla gelmez. Önce tamamlanma olayı, ardından gecikmiş "işlemde" durumu bildirimi gelebilir. Yalnızca son alınan değeri kaydederseniz tamamlanmış sipariş yeniden etkin hale gelir.

İzin verilen geçişleri tanımlayın. Örneğin ara durum nihai durumun üzerine yazamaz ve iptal edilmiş sipariş ayrı bir kontrol olmadan tamamlandıya geçirilmez. API nihai durumun düzeltilmesine izin veriyorsa nedeni, orijinal değeri ve değişiklik kaynağını saklayın.

Payload siparişin değişiklik zamanını içeriyorsa webhook'un alınma zamanını değil, tam olarak onu karşılaştırın. API böyle bir etiket iletmiyorsa durum önceliklerini ve siparişi getirme yöntemiyle mutabakatı kullanın. Önceliklerin dezavantajı, gerçek sıranın yerini tutmamalarıdır; özellikle sağlayıcı nihai durumdan iadeye izin veriyorsa.

Teslimatı hızla onaylayın ve işlemleri kuyruğa alın

Sağlayıcıya yanıt vermeden önce uzun süren işlemler yapmayın. İmza doğrulaması, sipariş arama, olay kaydı ve durum güncellemesi genellikle hızla tamamlanabilir. Mesaj gönderme, CRM ile senkronizasyon, rapor oluşturma veya üçüncü taraf sistemlere istekler en iyisi görev kuyruğuna aktarılır.

Çalışma sırası şöyledir: imzayı doğrula, olayı ve durum değişikliğini atomik olarak kaydet, başarılı yanıt döndür, ardından ikincil işlemleri gerçekleştir. Kaydetmeden önce yanıt verirseniz arıza durumunda veriler kaybolur. Uzun süren bildirim gönderiminden sonra yanıt verirseniz sağlayıcı teslimatı başarısız sayabilir ve kopya gönderebilir.

Kuyruğun dezavantajı, kontrol edilmesi gereken ayrı bir bileşenin ortaya çıkmasıdır: görev hataları, gecikmeler ve yeniden çalıştırmalar. Ancak yönetici bildirimindeki bir arıza, sipariş durumlarının alınmasını engellemez.

Ekip ve müşteri için bildirimleri yapılandırın

Durum değiştikten sonra herkesi aynı şekilde bilgilendirmek gerekmez. Yönetici için genellikle iptaller, hatalar, kısmi tamamlama ve uzun süre değişmeyen siparişler önemlidir. Müşteri için çoğu zaman anlaşılır bir sonuç yeterlidir: sipariş tamamlandı, iptal edildi veya açıklama gerektiriyor.

• Tamamlanmış sipariş — kişisel kabinde güncelleme veya müşteriye kısa mesaj.
• İşlem hatası — API'nin ilettiği nedenle sorumluya bildirim.
• Kısmi tamamlama — düzeltme, iade veya sonraki işlem için kontrol görevi.
• Bilinmeyen durum — günlüğe kayıt ve teknik uzmana mesaj.
• Bilinmeyen sipariş ID'si — sisteminiz ile sağlayıcı arasındaki bağlantının ayrıca kontrolü.

Her teknik geçişte mesaj göndermeyin. Akış hızla gürültüye dönüşür ve önemli bir sorun fark edilmeden kalır. Dahili bildirim sipariş numarasını, hizmeti, mevcut durumu, harici ID'yi ve kart bağlantısını içermelidir.

Günlük tutun ve tamamlanmamış siparişleri karşılaştırın

Günlükler, hizmetin olay gönderip göndermediğini, hangi gövdenin geldiğini, imzanın neden geçmediğini ve işlemenin hangi aşamada durduğunu anlamak için gereklidir. Alınma zamanını, olay ID'sini, sipariş ID'sini, olay türünü, imza doğrulama sonucunu, iç durumu ve yanıt kodunu saklayın. Sırları, token'ları ve kişisel verileri maskeleyin.

Teslimat hatalarını, geçersiz imzaları, bilinmeyen siparişleri, desteklenmeyen durumları, kopyaları ve durum sırası nedeniyle uygulanamayan olayları ayrıca izleyin. Bu tür kayıtların artması API şemasının değiştiği, sırrın süresinin dolduğu, rotada arıza olduğu veya işleyici mantığında hata bulunduğu anlamına gelebilir.

Ara durumlardaki siparişleri düzenli olarak API veri getirme yöntemiyle karşılaştırın. Bu kontrol webhook'ların yerini almaz, ancak kaçırılan bir olayı, kuyruk arızasını veya dış durumun doğru bildirim olmadan değiştiği bir durumu tespit etmeye yardımcı olur.