BİLGİ BANKASI
E-ticaret API entegrasyonu ve webhook akışı nasıl tasarlanır?
İçindekiler — Türkçe
API ile webhook hangi görevleri üstlenir?
API, sistemler arasında tanımlı istek ve yanıtlarla veri veya işlev sunan arayüzdür. Webhook ise bir olay gerçekleştiğinde başka bir sisteme gönderilen bildirimdir. Sipariş detayını API ile çekebilir, sipariş oluştuğu haberini webhook ile alabilirsiniz. Kullanılan servisin teslim ve sıralama davranışı kendi belgesinden kontrol edilmelidir.
Başlamadan önce test ortamı, örnek veri, erişim kapsamı ve alan eşleme belgesi gereklidir. Canlı müşteri verilerini geliştirme ortamına gereksiz yere kopyalamayın. Yetki ve veri ihtiyacı, aktarılacak iş akışıyla sınırlandırılmalıdır.
Sipariş aktarımı nasıl kurulur?
1. Veri sözleşmesini yazın. Sipariş kimliği, para birimi, tutar birimi, kalemler, vergi gösterimi ve durum alanları açık olsun. Ondalık tutarı kuruş cinsinden tam sayıyla karıştırmak ciddi hesap hatası oluşturabilir.
2. Kaynak ve hedef kimlikleri eşleyin. Mağazadaki sipariş kimliği ile ERP kaydı arasında kalıcı ilişki tutun. Müşteri e-postasını tek eşleme anahtarı saymayın; e-posta değişebilir veya ortak kullanılabilir.
3. Gelen bildirimin kaynağını doğrulayın. Sağlayıcının tarif ettiği imza doğrulamasını ve ham gövde gereksinimini uygulayın. Gizli anahtarları kod içinde veya işlem günlüklerinde açıkça tutmayın.
4. Olayı kalıcı bir gelen kutusuna veya kuyruğa kaydedin. Başarılı alındı yanıtının hangi aşamada döndürüleceği sağlayıcının sözleşmesiyle uyumlu olmalıdır. Kaydı güvenceye almadan yanıt vermek kayıp riski oluşturabilir.
5. İşlemeyi tekrar güvenli tasarlayın. Aynı kaynak olay kimliği yeniden geldiğinde ikinci bir sipariş oluşturulmamalıdır. Benzersiz veritabanı kısıtı ve atomik kayıt, eşzamanlı işlem yarışlarını kontrol etmeye yardımcı olur.
Tekrar deneme neden ayrıca tasarlanmalıdır?
Stripe belgeleri, webhook olaylarının tekrarlanabileceğini ve sıra garantisi bulunmadığını belirtir. Bu somut örnek, kullanılan her servisin kendi davranışını incelemek gerektiğini gösterir; tüm sağlayıcılar için aynı süre ve politika varsayılmamalıdır.
Geçici bağlantı hatası yeniden denenebilir; eksik zorunlu alan ise veri düzeltilmeden aynı sonucu üretir. Bu iki hata türünü ayırın. Deneme sayısını sınırlayın ve çözülemeyen kayıtları görünür hata kuyruğuna taşıyın. Manuel tekrar işlem aynı kimlik kurallarına uymalıdır.
Akış hangi testlerle doğrulanır?
Aynı olayı iki kez ve eşzamanlı gönderin; hedefte tek iş sonucu oluşmalıdır. Bildirimleri ters sırayla deneyin; daha eski olay yeni durumu yanlışlıkla geri almamalıdır. Hedef sistem kapalıyken kaydın beklediğini, yeniden açıldığında kontrollü işlendiğini gözlemleyin.
Geçersiz imza, bilinmeyen ürün kimliği, sınırlandırılmış API isteği ve zaman aşımı için ayrı sonuçlar bekleyin. Test kaydında kaynak olay, deneme sayısı, hedef kayıt ve son durum bulunmalıdır. Ekip bu kayıtlarla bir siparişin nerede kaldığını bulabiliyorsa entegrasyon işletilebilir hâle gelmiştir.
Sık sorulan sorular nelerdir
Sonraki adım nedir
Kaynak ve hedef sistemlerinizin API belgeleriyle PROJX Digital’e başvurun; veri sözleşmesini ve hata senaryolarını birlikte değerlendirelim.
