Kurye yazılımınız ile KuryeX arasında ölçülebilir bir bağlantı kurun.

Kimlik ve anahtarlar

/auth/register veya /auth/login HttpOnly, SameSite=Lax oturum cookie'si verir. Cookie isteklerinde X-Portal-Request: 1 gerekir; Origin gönderiliyorsa aynı origin kontrol edilir. Firma API uçları X-API-Key kullanır. Anahtar yenileme mevcut şifreyi tekrar ister ve raw API key ile signing secret yalnızca başarılı yanıtta bir kez döner. GET /me sadece prefix, tarih ve yapılandırma bilgilerini verir.

POST /api/integration-portal/credentials/rotate
X-Portal-Request: 1
Content-Type: application/json

{"current_password":"••••••••••••"}

Sunucuya sipariş bildirimi

Aktif abonelik, onaylı mağaza eşlemesi ve açık hedef bulunduğunda sipariş işlemi izin verilen alanlardan değişmez bir kayıt oluşturur. external_order_details, secret'lar ve finansal kurye alanları bildirime alınmaz.

{
  "version": 1,
  "event_id": "ipe_opaque",
  "event_type": "order.created",
  "occurred_at": "2026-10-05T10:00:00.000Z",
  "order_version": 1,
  "order": {"customer": {"name": "Örnek"}, "items_text": "1 x Ürün"},
  "order_ref": "ipo_opaque",
  "provider": "getir",
  "provider_order_id": "provider-ref"
}

POST gövdesi byte-for-byte korunur. Header'lar: X-KuryeX-Event-ID, X-KuryeX-Timestamp, X-KuryeX-Version, Idempotency-Key, X-KuryeX-Signature: sha256=<hex>.

import crypto from 'node:crypto';
const raw = req.rawBody; // JSON.parse öncesi byte dizisi
const timestamp = req.get('X-KuryeX-Timestamp');
const received = req.get('X-KuryeX-Signature') || '';
const expected = 'sha256=' + crypto.createHmac('sha256', SIGNING_SECRET)
  .update(timestamp + '.' + raw, 'utf8').digest('hex');
const signaturePattern = /^sha256=[a-f0-9]{64}$/i;
const age = Math.abs(Date.now() / 1000 - Number(timestamp));
const fresh = Boolean(timestamp) && Number.isFinite(Number(timestamp)) && age <= 300;
const receivedBuffer = Buffer.from(received, 'ascii');
const expectedBuffer = Buffer.from(expected, 'ascii');
const valid = fresh && signaturePattern.test(received)
  && receivedBuffer.length === expectedBuffer.length
  && crypto.timingSafeEqual(receivedBuffer, expectedBuffer);
// event_id + body hash'i kalıcı kaydet, aynı idempotency tekrarında
// mevcut sonucu döndür, sonra 2xx ver.

Durum bildirimi

POST /api/integration-portal/v1/orders/{order_ref}/status X-API-Key ve benzersiz Idempotency-Key ister. Başarılı kabul 202 ve receipt_id döndürür. Kanal sonucu doğrulanana kadar portal durumunu onaylanmış saymayın; GET /v1/status-updates/{id} ile job id veya receipt id polling yapılır.

curl -X POST https://kuryex.net/api/integration-portal/v1/orders/ipo_opaque/status \
  -H 'X-API-Key: kxip_...' \
  -H 'Idempotency-Key: status-0001' \
  -H 'Content-Type: application/json' \
  -d '{"status":"accepted","occurred_at":"2026-10-05T10:02:00Z"}'

Yeni siparişte ilk bildirim, kanalın desteklediği ilk durum olmalıdır; Getir örneğinde akış accepted → provider sonucu applied → ready → provider sonucu applied → delivered şeklindedir. Önceki durum kanal tarafından onaylanmadan yeni durum STATUS_IN_PROGRESS ile reddedilebilir. Aynı anahtar farklı gövde veya siparişte kullanılırsa 409 IDEMPOTENCY_CONFLICT döner.

Durum matrisi

Güncel değerleri GET /api/integration-portal/catalog içindeki capabilities alanından okuyun. Gerçek kanal sonucu alınmayan işlem başarılı kabul edilmez.

Tekrar deneme ve sıra

DNS + HTTPS gönderimi için 10 saniyelik toplam deadline ve 64 KiB response sınırı vardır. Sunucu bildirimi başarısızsa exponential backoff ile sekiz deneme yapılır. Aynı siparişin bildirim sürümü sırası korunur; önceki bildirim başarısızsa sonraki bildirim manuel düzeltme bekler. Firma panelinden başarısız sunucu bildirimi veya durum işi için yeni deneme döngüsü başlatılabilir.

Kurulum ve veri sınırı

Migration uygulandıktan sonra yönetici hesabı aboneliği manuel fiyat kaydı, geçerlilik bitişi ve ödeme referansı ile etkinleştirir. Firma hedefi public DNS üzerinde HTTPS 443 olmalı; auth bilgisi, query, fragment, redirect ve private IP kabul edilmez. JSON yanıtları firmaya özel ve cache dışıdır. Makine sözleşmesi OpenAPI JSON içinde bulunur.