Ana içeriğe geç

Entegrasyon Akışı

Bu bölüm, MuditaKurye ile üçüncü taraf bir POS veya sipariş yönetim sistemi arasındaki uçtan uca veri akışını özetler. Amaç, ekiplerinizin teknik gereksinimleri hızlı kavramasını sağlamak ve olası arayüz açıklarını önlemektir.

Yüksek Seviye Adımlar

  1. Kimlik Bilgisi Oluşturma – Restoran panelinden API Key veya Basic Auth bilgileri alınır.
  2. Sipariş Gönderimi – Üçüncü taraf sistem siparişi POST /webhook/third-party/order ile MuditaKurye'ye iletir.
  3. Sipariş Doğrulama – MuditaKurye siparişi doğrular, veri bütünlüğünü kontrol eder ve 202 Accepted döner.
  4. Restoran Operasyonları – Restoran siparişi hazırlar, MuditaKurye iç operasyonları (VRP, kurye ataması) yürütür.
  5. Durum Bildirimleri – MuditaKurye, yapılandırılmış webhook URL'lerine sipariş durum güncellemeleri ve iptal bildirimleri gönderir.
  6. Muhasebe & Raporlama – Üçüncü taraf sistem bildirimleri işleyip kendi raporlama/muhasebe süreçlerini günceller.

Dizisel Diyagram

sequenceDiagram
    autonumber
    participant Client as Entegratör Sistemi
    participant API as MuditaKurye API
    participant Restaurant as Restoran Paneli
    participant Courier as Kurye Mobil

    Client->>API: POST /webhook/third-party/order (orderId, items, ...)
    API-->>Client: 202 Accepted (orderId)
    API->>Restaurant: Yeni sipariş bildirimi
    Restaurant-->>API: Sipariş onayı (VALIDATED)
    API->>Client: Webhook order.status_changed (VALIDATED)
    API->>Courier: Kurye ataması bildirimi
    Courier-->>API: Kurye atamayı kabul etti (ASSIGNED)
    API->>Client: Webhook order.status_changed (ASSIGNED)
    Courier->>Restaurant: Siparişi teslim aldı (ON_DELIVERY)
    API->>Client: Webhook order.status_changed (ON_DELIVERY)
    Courier->>Customer: Teslimat tamamlandı (DELIVERED)
    API->>Client: Webhook order.status_changed (DELIVERED)

Sistemler Arası Veri

Aşama MuditaKurye'den Beklenen Entegratörden Beklenen
Sipariş Gönderimi Geçerli restaurantId, fiyat kalemleri, müşteriye dair temel bilgiler orderId benzersizliği, para birimi tutarlılığı
Doğrulama Stok, restoran çalışma saatleri, adres doğruluğu İstenirse hataları loglama ve düzeltme
Webhook HMAC (opsiyonel), tekrar deneme mekanizması 2xx yanıt, geç gelen webhooks için idempotent iş mantığı
İptal reason, canceledBy alanları Kendi tarafında siparişi kapatma, müşteriye bilgilendirme

İç Sistemlere Etki

  • ERP / Muhasebe: Webhook'tan gelen durumlar ile finansal kayıtlar güncellenmelidir.
  • Kurye Yönetimi: VRP entegrasyonu varsa, ROUTED ve ASSIGNED durumları üzerinden planlama yapılır.
  • Müşteri Bildirimi: SMS/e-posta gönderimi için ON_DELIVERY ve DELIVERED durumları tetikleyici olarak kullanılabilir.

Başlama Kontrol Listesi

  • [ ] Restoran panelinden API anahtarları alındı.
  • [ ] orderId üreten sistemde çakışma önleyici mekanizma var.
  • [ ] Webhook URL'leri dış dünyadan erişilebilir ve TLS sertifikası geçerli.
  • [ ] X-MuditaKurye-Signature doğrulaması için gizli anahtar saklandı.
  • [ ] Üç aşamalı test senaryosu (happy path, hatalı veri, geciken webhook) automatize edildi.

Yaygın Sorunlar ve Çözümler

Belirti Olası Sebep Çözüm
401 Unauthorized Yanlış API Key veya IP kısıtı Restoran ayarlarını kontrol edin, gerekli IP'leri allowlist'e ekleyin
409 Conflict Aynı orderId daha önce gönderilmiş orderId üretim algoritmasını gözden geçirin
Webhook gelmiyor Güvenlik duvarı veya hatalı URL URL'yi doğrulayın, curl -I ile erişimi test edin
İmza doğrulaması başarısız Yanlış HMAC algoritması SHA-256 kullanarak ham body üzerinde HMAC hesaplayın

Trafik Akışı

flowchart LR
    POS[Entegratör POS] -- HTTPS --> API[MuditaKurye API]
    API -- "gRPC / Kafka" --> Services[MuditaKurye Servisleri]
    API --> Restaurant[Restoran Paneli]
    Restaurant --> Courier[Kurye Mobil]
    Courier --> Webhooks[Webhook Bildirimleri]
    Webhooks --> Integrator[Entegratör Sistemleri]

Ölçeklendirme Notları

  • Webhook'lar garantili teslimat sağlamaz; tekrar deneme mekanizmasına güvenin.
  • Sipariş gönderiminde orderId anahtarınızın doğal shard'lanabilir olmasına dikkat edin (örn. tarih + restaurantId + artan sayaç).
  • Yoğun saatlerde 202 Accepted yanıtı yalnızca kuyruğa alındığını gösterir; gerçek kabul sürecini webhooks üzerinden takip edin.

Ek Kaynaklar

  • docs/docs/api/create-order.md: Sipariş payload detayları
  • docs/docs/api/webhooks.md: Webhook şemaları ve imzalama
  • docs/docs/best-practices.md: Güvenlik, izleme ve operasyon tavsiyeleri