En İyi Uygulamalar¶

Bu rehber, MuditaKurye entegrasyonlarını güvenilir, ölçeklenebilir ve sürdürülebilir şekilde işletmeniz için öneriler sunar. Başlıklar ekiplerinizin günlük operasyonlarında referans olarak kullanabileceği şekilde düzenlenmiştir.

Güvenlik¶

Sırlarınızı koruyun: API anahtarlarını ve webhook gizli anahtarlarını çevresel değişkenlerde veya gizli yönetim servislerinde saklayın.
İmza doğrulaması: X-MuditaKurye-Signature başlığını zorunlu tutun; imzasız istekleri 401 ile reddedin.
IP kısıtlaması: Mümkünse firewall üzerinde MuditaKurye IP aralığını allowlist'e ekleyin.
Least privilege: Kimlik bilgilerini restoran bazında oluşturun, kullanmadığınız erişimleri devre dışı bırakın.
Audit log: Sipariş gönderimleri ve webhook çağrılarını ayrı log kanallarında takip edin.

Güvenilirlik¶

İdempotent tasarım: orderId alanının tekrar kullanılmamasını garanti edin. Webhook'lar birden fazla kez gelebilir; kendi tarafınızda idempotent işlem yapın.
Retry stratejisi: 500 ve ağ hatalarında üstel gecikmeli (ör. 1s, 2s, 4s, 8s) tekrar deneyin, deneme sayısını sınırlayın.
Queue kullanımı: Webhook işleme mantığını kuyruklara yerleştirerek giriş/çıkış yükünü ayırın.
Timeout ayarı: HTTP isteklerinizde 3-5 saniyelik timeout kullanın; sonsuza kadar yanıt beklemeyin.

İzleme & Loglama¶

Yapılandırılmış log: JSON formatlı loglar ile sipariş ve webhook olaylarını ayrıştırılabilir hale getirin.
Trace ID: Her siparişi ve webhook'u benzersiz bir traceId ile loglayın, MuditaKurye ile paylaşılan destek süreçlerini hızlandırır.
Alarm eşikleri: Başarısız sipariş oranı, webhook retry sayısı ve yanıt süreleri için alarm kurun.
SLA takibi: Sipariş işleme süresini (submit → DELIVERED) ölçerek SLA hedeflerinize uyumu raporlayın.

Operasyon¶

Bakım pencereleri: Planlı bakım ve deploy işlemlerini MuditaKurye ile önceden paylaşın.
Versiyonlama: Payload şemalarındaki değişiklikler için arayüz sürümleri oluşturun. Gerektiğinde iki versiyonu paralel çalıştırın.
Dev / Staging ortamı: Üretim öncesi testleri https://staging-api.muditakurye.com.tr adresinde yapın.
Runbook: Hata senaryoları için adım adım müdahale kılavuzu hazırlayın; örn. "webhook gelmiyor".

Performans¶

Toplu gönderimden kaçının: Her siparişi tek tek gönderin; sistem toplu gönderimleri desteklemez.
Payload boyutu: Metin alanlarını makul düzeyde tutun, gereksiz veri göndermeyin.
Önbellek: Sabit restoran bilgilerini (menü, adres) kendi tarafınızda cache'leyin.

Test ve Doğrulama¶

Unit test: Sipariş oluşturma fonksiyonlarını edge-case senaryolarıyla test edin.
Contract test: Webhook payload'larının beklediğiniz şemaya uyduğunu doğrulamak için JSON şema validasyonu kullanın.
Load test: Yoğun saatlerdeki trafiği simüle ederek retry ve timeout ayarlarının yeterli olduğundan emin olun.

İş Sürekliliği¶

Fallback planı: API veya webhook kesintilerinde devreye alabileceğiniz manuel süreçler belirleyin.
Veri tutarlılığı: Her gün sonunda MuditaKurye siparişlerini kendi sisteminizle mutabakat yapın.
Arşivleme: Eski sipariş ve webhook loglarını düzenli aralıklarla arşivleyin.

Kaynaklar¶

api/create-order.md: Talep gövdesi şeması ve örnekler
api/webhooks.md: Webhook olayları ve imza doğrulaması
examples/nodejs.md, examples/python.md, examples/curl.md: Uygulamalı örnekler
support.md: İletişim ve SLA politikaları