Taslak · Faz 6

Partner API v2

SiparişMatik dışındaki restoran yazılımları, kurye sağlayıcıları ve gelecekteki mobil uygulama için modern arayüz: JSON, kuruş tabanlı tutarlar, idempotent yazma, imzalı webhook. Bu sayfa tasarım taslağıdır; alan adları ve şekiller Faz 6 kontrat testleriyle kesinleşir ve o zaman planlandı → hazır olur.

Kimlik ve kapsam

X-Api-Key başlığı; anahtar sunucuda sha256 özet olarak saklanır (KuryeMatik partner deseni). Bir anahtar birden çok şubeyi kapsayabilir; her yanıt anahtarın kapsamına göre süzülür — kapsam dışı kayıt 404.
Partner başına kota (varsayılan 600 istek/dk) ve sandbox ortamı (ayrı anahtar, gerçek SMS/ödeme yok).
Fiyat, indirim, minimum sepet ve teslimat ücreti yalnız Lezzet35’te hesaplanır; partner tutar göndermez.

İdempotency

Yazma uçları Idempotency-Key başlığı ister (UUID). Aynı anahtarla tekrar gelen istek 24 saat boyunca ilk yanıtı döner ve yan etki üretmez; aynı anahtar farklı gövdeyle gelirse 409. Ağ hatasında partner güvenle tekrar dener.

Uçlar (taslak)

Metod	Yol	Özet
get	/api/v2/restoranlar	Partnerin bağlı şubeleri
get	/api/v2/restoranlar/{subeId}/menu	Şube menüsü
put	/api/v2/restoranlar/{subeId}/menu	Menü senkronu (partner → Lezzet35)
put	/api/v2/restoranlar/{subeId}/durum	Şubeyi aç/kapat
get	/api/v2/siparisler	Siparişleri listele
get	/api/v2/siparisler/{id}	Sipariş detayı
put	/api/v2/siparisler/{id}/durum	Sipariş durumunu güncelle
post	/api/v2/webhooks	Webhook aboneliği

Alan tabloları ve curl örnekleri ana belgede (bağlantılar tabloda).

Webhook olayları ve imza

Olay	İçerik	Teslim hedefi
siparis.olusturuldu	Yeni sipariş; tam kalem listesi ve teslimat bilgisi	≤ 2 sn
siparis.durum	Durum geçişi (kaynak, önceki, yeni, açıklama)	≤ 2 sn
menu.degisti	Panelden ya da moderasyondan menü değişikliği (ürün/fiyat/durum)	≤ 30 sn
sube.durum	Şube açıldı/kapandı	≤ 5 sn

Her teslim X-Lezzet35-Imza: sha256=HMAC_SHA256(gizliAnahtar, hamGovde) başlığı taşır; partner ham gövde üzerinden imzayı doğrular (JSON yeniden serileştirilmez). X-Lezzet35-Teslim-Id tekrar teslimlerde aynı kalır → partner tarafında tekilleştirme anahtarı. 2xx dışı yanıtta 1, 2, 5, 15, 60 dk aralıklarla 5 deneme; sonra dead-letter ve restoran panelinde uyarı.

Örnek teslim

POST https://pos.ornek.com/lezzet35/webhook
X-Lezzet35-Olay: siparis.olusturuldu
X-Lezzet35-Teslim-Id: 7a1c…
X-Lezzet35-Imza: sha256=3f2b…

{
  "olay": "siparis.olusturuldu",
  "kimlik": "L35-20260916-4F2A9C",
  "zaman": "2026-09-16T09:05:12.000Z",
  "veri": { "id": "cmfl…", "no": "L35-20260916-4F2A9C", "subeId": "cmfl…", "durum": "ALINDI", "toplamKurus": 36000 }
}

İmza doğrulama (Node.js)

import { createHmac, timingSafeEqual } from "node:crypto";

export function imzaGecerliMi(hamGovde: string, baslik: string, gizliAnahtar: string): boolean {
  const beklenen = "sha256=" + createHmac("sha256", gizliAnahtar).update(hamGovde).digest("hex");
  return beklenen.length === baslik.length && timingSafeEqual(Buffer.from(beklenen), Buffer.from(baslik));
}

Sürüm ve geri uyumluluk

Yayın sonrası alan eklemek serbest; alan silmek/tip değiştirmek yalnız yeni büyük sürümle (v3).
Webhook gövdesine yeni alan eklenebilir; partner bilinmeyen alanları yok saymalı.
Kesinleşen sözleşme bu sayfada ve makine biçiminde (/api/openapi.json) duyurulur.