E-pin ve hediye kartı bayi API’sinde neler olmalı?

Bayi ağı, mağazanızı bir toptancıya dönüştürür: başka siteler, botlar ve pazar yerleri sizden kod ve yükleme alıp yeniden satar. API ile bağlanırlar, binlerce sipariş gönderirler ve her seferinde aynı sonucu beklerler.

Bu rehberde dijital ürünler için bir bayi API’sinin parçalarını, örnek olarak Kavia Commerce API’siyle anlatıyoruz. Bayi paneli ve API, Pro ve Max paketlerinde yer alır.

Anahtarlar: bir kez gösterilir, hash olarak saklanır

Her iş ortağına ayrı bir API anahtarı verilir. Anahtar oluşturulduğunda bir kez gösterilir ve şifreler gibi yalnızca hash olarak saklanır. Veritabanı bir gün sızsa bile içindeki anahtarlar kullanılamaz.

Her anahtar izin verilen IP adresleri listesiyle sınırlanabilir ve kendi istek limitine sahiptir; böylece bir iş ortağının hatası diğerlerini yavaşlatmaz.

İmzalı istekler

Tek başına anahtar yetmez: bir isteği kayıtlarda gören biri onu tekrar gönderebilir. Kavia Commerce istekleri HMAC ile imzalanır; bu, mesajın anahtar sahibinden geldiğini ve değiştirilmediğini kanıtlamanın standart yoludur (RFC 2104). Her istekte ayrıca bir zaman damgası ve tek kullanımlık bir nonce bulunur; eski bir istek yeniden gönderilemez.

Tekrar edilemeyen siparişler: para kurtaran kural

Ağlar kesilir. İş ortağı bir sipariş gönderir, yanıt gelmeden bağlantı kopar ve sistemi isteği yeniler. Koruma yoksa sonuç iki sipariş ve iki tahsilattır.

Çözüm idempotency’dir: iş ortağı her siparişte kendi sipariş numarasını gönderir. Kavia Commerce’te bir externalOrderId bir siparişe karşılık gelir. Aynı numarayla gelen tekrar yeni sipariş açmaz, ilk siparişi döndürür. Ödeme API’leri de aynı ilkeyi kullanır; bkz. Stripe’ın idempotent istek açıklaması.

Basitleştirilmiş bir sipariş şöyle görünür:

productId, quantity ve externalOrderId "A-77812" ile POST /v1/orders
Yanıt: COMPLETED durumu, ondalık metin olarak toplam tutar, para birimi ve kodlar.

Tutarlar kayan noktalı sayı olarak değil, ondalık metin olarak taşınır; böylece 11.20 her zaman 11.20 kalır.

Fiyat grupları ve toplu siparişler

Her iş ortağı aynı fiyatı ödemez. Fiyat grupları, ayrı katalog tutmadan büyük bir bayiye küçük bir bayiden farklı bir fiyat listesi vermenizi sağlar. Toplu siparişlerle iş ortağı tek istekte çok sayıda kod alabilir.

Webhook’lar: iş ortağına ne olduğunu bildirin

Yüklemeler birkaç saniye sürebilir, bazıları başarısız olur. İş ortaklarını sürekli sorgu yapmaya zorlamak yerine platform webhook gönderir: order.created, order.completed, order.failed ve order.refunded. Başarısız bir siparişte iş ortağının bakiyesindeki bekletme kalkar.

Test anahtarları

İş ortakları para harcamadan önce test etmek ister. Sandbox anahtarlarıyla gerçek stoğa dokunmadan test siparişi verip webhook alabilirler.

Deneyin

Canlı demolar sayfasında tarayıcıda çalışan etkileşimli bir bayi API demosu var; platform sayfası da örnek değerlerle gerçek bir istek ve yanıt gösteriyor. İş ortaklarının sipariş verdiği türden bir kataloğu canlı demo mağazada görebilirsiniz. API’nin kendisini denemek için sandbox anahtarı isteyin. Anahtarların, bakiyelerin ve siparişlerin nasıl korunduğu güvenlik sayfamızda.