Entegrasyon Akışı¶

Baştan sona entegrasyon sürecinin adım adım açıklaması.

Aşamalar¶

gantt
    title Entegrasyon Süreci
    dateFormat  X
    axisFormat %s

    section Hazırlık
    Hesap Oluşturma           :done, a1, 0, 1
    API Key Teslimi            :done, a2, 1, 2
    Webhook URL Bildirimi      :done, a3, 2, 3

    section Geliştirme
    Webhook Endpoint Geliştirme :active, b1, 3, 5
    İmza Doğrulama Ekleme      :b2, 5, 6
    Status API Entegrasyonu     :b3, 6, 8

    section Test
    Stage Ortamında Test       :c1, 8, 10
    Uçtan Uca Test             :c2, 10, 11

    section Canlı
    Production Geçiş           :c3, 11, 12
    İzleme ve Destek           :c4, 12, 13

Aşama 1: Hazırlık¶

1.1 Hesap Oluşturma¶

MuditaPOS ekibi sizin için bir Customer kaydı oluşturur ve şu bilgileri paylaşır:

Bilgi	Açıklama
Customer ID	UUID formatında benzersiz kimlik
API Key	Webhook'larda gönderilir
API Secret	İmza doğrulamada kullanılır
Internal API Key	Status update çağrılarında kullanılır

1.2 Entegrasyon Kaydı¶

Hangi platformlardan sipariş alacağınız belirlenir ve her biri için bir Integration kaydı oluşturulur.

Örnek:

Müşteri: Acme Restoran
├── Entegrasyon #1: Getir    → restaurantId: "getir-rest-123"
├── Entegrasyon #2: Yemeksepeti → vendorId: "ys-vendor-456"  
└── Entegrasyon #3: Trendyol → supplierId: "trendyol-789"

1.3 Webhook URL Bildirimi¶

Aşağıdaki webhook URL'lerinizi MuditaPOS ekibine bildirin:

Yeni Sipariş:       https://api.sizinfirma.com/webhooks/new-order
İptal:              https://api.sizinfirma.com/webhooks/cancel-order
Durum Güncelleme:   https://api.sizinfirma.com/webhooks/order-status

Aşama 2: Geliştirme¶

2.1 Webhook Endpoint¶

Minimum gereksinimleri karşılayan bir endpoint oluşturun:

[x] POST method kabul eder
[x] JSON body okur
[x] HTTP 200 döndürür
[x] 10 saniye içinde yanıt verir

2.2 İmza Doğrulama¶

Güvenlik için webhook isteklerinde X-MuditaPOS-Signature header'ını doğrulayın:

HMAC-SHA256(api_secret, request_body) == signature_header

→ Detaylı bilgi: Kimlik Doğrulama

2.3 Status Update¶

Sipariş durumu değiştiğinde MuditaPOS'a bildirin:

POST /internal/orders/status
{
  "providerOrderId": "...",
  "platform": "GETIR",
  "action": "VERIFY"
}

→ Detaylı bilgi: Durum Gönderme

Aşama 3: Test¶

3.1 Stage Ortamı¶

Stage ortamında tüm akışı test edin:

Base URL: https://stage.pos.muditakurye.com.tr

3.2 Test Senaryoları¶

Aşağıdaki senaryoları test edin:

#	Senaryo	Beklenen
1	Yeni sipariş al	Webhook'a sipariş gelir
2	Siparişi onayla (VERIFY)	Platform'a iletilir
3	Hazırlamaya başla (PREPARE)	Platform'a iletilir
4	Teslim et (DELIVER)	Platform'a iletilir
5	Sipariş iptal et (CANCEL)	Platform'a iletilir
6	Webhook endpoint kapalıyken	3x retry + Telegram bildirim
7	Aynı siparişi tekrar gönder	Mükerrer filtrelenir
8	Hatalı durum geçişi	Guard reddeder

3.3 Test Checklist¶

- [ ] Webhook endpoint HTTP 200 döndürüyor
- [ ] İmza doğrulama çalışıyor
- [ ] Sipariş verisi doğru parse ediliyor
- [ ] Tüm ürünler ve seçenekler görünüyor
- [ ] Status update API çalışıyor
- [ ] İptal webhook'u alınıyor
- [ ] Retry mekanizması doğru çalışıyor
- [ ] Farklı platformlardan test siparişleri geldi

Aşama 4: Canlıya Geçiş¶

4.1 Production Geçiş¶

MuditaPOS ekibi entegrasyonlarınızı production ortamına taşır:

Base URL: https://pos.muditakurye.com.tr

4.2 Checklist¶

Canlıya Geçmeden Önce

[ ] Production webhook URL'leri bildirildi
[ ] SSL sertifikası geçerli (HTTPS zorunlu)
[ ] Server uptime %99.9+ garantili
[ ] Hata loglama aktif
[ ] Telegram bildirim ayarları yapıldı

4.3 İzleme¶

Canlıya geçtikten sonra:

İlk 24 saat — Tüm platform siparişlerini yakından izleyin
İlk hafta — Retry/hata oranlarını kontrol edin
Sürekli — Telegram bildirimleri ile anlık takip

Zaman Çizelgesi¶

Aşama	Tahmini Süre
Hazırlık	1 gün
Geliştirme	3-5 gün
Test	2-3 gün
Canlıya geçiş	1 gün
Toplam	~1-2 hafta