İş ortakları — KolayMiles

Onboarding veridir, kod değil

Bir ürünü KolayMiles'a bağlamak için bu tarafta kod yazılmaz. Ürün üç satır edinir: hesap tutulacak bir program, üyeye görünen bir marka ve gönderebileceği olay tipleriyle sınırlı bir API anahtarı.

Tek uç

Tüm kazanım trafiği POST /v1/events üzerinden akar. Kuyruk yok, broker yok: ihtiyaç duyulan garanti "olay satırıyla iş satırı birlikte commit olur" ve bunu bir veritabanı işlemi zaten verir.

{
  "event_id":       "pur_9f3a2b7c",
  "type":           "fuel.purchased",
  "schema_version": 1,
  "tenant_id":      "t_talyasmart",
  "program_id":     "kolaymiles",
  "source_app":     "kolaymarin",
  "occurred_at":    "2026-08-10T09:14:22Z",
  "payload": {
    "purchase_id":  "pur_9f3a2b7c",
    "customer_ref": "bfy_9c1e…",
    "total_kurus":  125000,
    "currency":     "TRY",
    "purchased_at": "2026-08-10T09:14:22Z"
  }
}

event_id sizindir ve değişmez

event_id üreticinin kendi iş anahtarıdır — purchase_id, order_id, bill_id. Her HTTP denemesinde yeni bir kimlik üretmek tekrar tespitini bozar ve üyeyi iki kez ödüllendirir. Yeniden denerken aynı değeri gönderin.

Kimlik ve imza

Authorization:          Bearer km_live_<prefix>_<secret>
X-KolayMiles-Signature: t=<unix>,v1=<hex hmac_sha256>

İmza ham gövde üzerinden hesaplanır; yeniden serialize edilmiş bir gövde üzerindeki imza hiçbir şey kanıtlamaz. İmzalama anahtarı, sunduğunuz API sırrından türetilir — yani saklanan ikinci bir düz metin sır yoktur. Beş dakikalık pencerenin dışında kalan zaman damgaları reddedilir, böylece yakalanmış bir gövde tekrar oynatılamaz.

Kiracı gövdeden okunmaz. tenant_id ve program_id anahtar kaydından gelir. Gövdede farklı bir değer göndermek sessizce ezilmez; 403 döner.

Yanıtlar

Kod	Anlamı	Ne yapmalı
`202`	Kabul edildi	Bitti
`200`	Tekrar — daha önce alınmıştı	Bitti; ikinci kez ödüllendirilmedi
`401`	Anahtar ya da imza geçersiz	Terminal — tekrar denemeyin
`403`	Bu tip/kiracı bu anahtara kapalı	Terminal — anahtar kapsamını düzeltin
`409`	Aynı `event_id`, farklı gövde	Terminal — üretici tarafında hata
`422`	Şema ihlali ya da tanınmayan tip	Terminal — gövdeyi düzeltin
`5xx`	Geçici	Aynı `event_id` ile yeniden deneyin

Kural basit: 4xx terminaldir, 5xx yeniden denenir. Aynı iş anahtarıyla yeniden deneme her zaman güvenlidir.

Kişisel veri göndermeyin

customer_ref opak bir referanstır. KolayMiles bir kimlik sağlayıcı değildir ve ham kişisel veri tutmaz: e-posta, telefon, ad ve adres bu uca hiç gelmemelidir. Üyenin kim olduğunu ürününüz bilir; KolayMiles yalnızca hangi cüzdana yazacağını bilir.

Sırada ne var

Bir olay tipi tanımlanmadan gönderilemez — tanınmayan tip 422 alır ve hiçbir şey saklanmaz, çünkü geçersiz bir olay dünya hakkında bir olgu değildir. Ürününüz için hangi tiplerin açılacağını konuşarak başlıyoruz.

Entegrasyon için yazın