Paket Ödemeleri — POST /plugin-api/packets/update-payments ✓ Canlı

İstek

POST {RESTOMENUM_BASE}/plugin-api/packets/update-payments
Authorization: Bearer <apiKey>

{
  "packetId": "a72d70cd-...",                    // ZORUNLU
  "mode": "replace",                              // ops — "replace" (VARSAYILAN) | "append"  🧪 append yalnız SANDBOX (prod'da YOK, planlanmıyor)
  "payments": [                                   // ZORUNLU — replace: paketin YENİ ödeme listesi (FULL REPLACE)
    { "price": 240, "id": "cash", "title": "Nakit", "isDiscount": false,
      "lineId": "pay-7c31",                       // ops (replace) / ZORUNLU (append) — ödeme SATIRININ kimliği (id = YÖNTEM id'si!)
      "metadata": [ { "key": "terminal", "value": "kiosk-1" } ] }  // ops — DİZİ (map değil)
  ]
}

• Scope: orders:write.
• mode opsiyonel, varsayılan "replace". Göndermezsen davranış bit-bit eskisiyle aynıdır — bu bir ekleme, kırıcı değişiklik değil.
• "replace": payments paketin tüm ödemelerini değiştirir. Satır: { price, id, title, isDiscount?, lineId?, metadata? }.
• "append": gönderilen satırlar mevcutların üzerine eklenir — aşağıdaki bölüm.
• İstek başına en fazla 20 ödeme satırı (payments şema tavanı) — her iki modda da. replace dokümanın satırlarını gönderdiğinle değiştirdiği için bu, bir replace çağrısından sonra dokümanı fiilen 20 satıra indirir: doküman tavanı değil, istek tavanının yan etkisidir.
• paid yeniden hesaplanır — yalnız price > 0 satırlar saklanır.
• Boş payments: [] → paid: 0 (ödemeleri sıfırlar). Yalnız replace: append'de geçerli satır yoksa istek reddedilir.

Ödeme yöntemi doğrulaması (ÖNEMLİ)

Ödeme satırları tenant'ın gerçek ödeme yöntemlerine karşı doğrulanır ("ID al, sunucuda türet"). Önce payment-methods/list çağır (payment_methods:read), geçerli id'leri oradan al.

Ekleme modu — mode: "append"

Neden var: POS terminali eklentileri ödeme satırını bu uçtan yazıyor ve full-replace onlar için bir tuzak: "kendi satırımı gönderdim" diyen en doğal geliştirici davranışı, aynı hesaptaki nakit tahsilatı, ikinci kartı ve indirim satırlarını SİLER ve paid düşer. Ekleme modu bunu kaldırır.

POST {RESTOMENUM_BASE}/plugin-api/packets/update-payments
Authorization: Bearer <apiKey>

{
  "packetId": "a72d70cd-...",
  "mode": "append",                               // mevcut satırlara DOKUNMAZ — üzerine ekler
  "payments": [
    { "price": 240, "id": "m-card", "lineId": "pay-term-01H9..." }   // lineId ZORUNLU (tekrar gönderim kalkanı)
  ]
}

• Gönderilen satırlar mevcutların üzerine eklenir; mevcut satırlara dokunulmaz. Mevcut satırları tekrar gönderme (aşağıdaki append_partial_duplicate).
• lineId ZORUNLUDUR — keyfi bir kural değil, tekrar gönderim kalkanı: platform kimlik göndermeyen satıra her çağrıda FARKLI bir kimlik üretir, yani ağ hatasında tekrarlanan istek ikinci bir satır olarak eklenir = çift tahsilat. Kimliği kendi kaydından türet ve retry'de aynısını gönder.
• lineId GÜÇLÜ olmalı: en az 8 karakter ve saf rakam DEĞİL. "00000001" sekiz karakterdir ama ayırt etmez — sayaç kalıbı reddedilir. Eski satırlara tanınan grandfather affı ekleme modunda İŞLEMEZ: af yalnız dokümanda zaten var olan kimlikleri bağışlar, ekleme modundaki yeni satırın kimliği ise tanım gereği dokümanda yoktur (olsaydı tekrar gönderim olurdu). Önerilen kalıp: sabit önek + uuid — pay-01H9XYZ…. (replace'te lineId opsiyoneldir; göndermezsen platform üretir.)
• paid birleşim üzerinden yeniden hesaplanır; paid ≤ total kapısı aynen geçerli.
• price ≤ 0 satırlar süzülür → süzme sonrası geçerli satır kalmazsa istek reddedilir.
• İki ayrı tavan: tek istekte en fazla 20 satır gönderebilirsin (şema, her iki modda), ve ekleme modunda birleşim (mevcut + gönderilen) 100'ü aşamaz → too_many_payment_lines. İkincisi iş kuralı değil, kaçak büyümeye karşı emniyet supabıdır.
• KAPAMA YOK politikası değişmedi: paid == total olsa bile hesap kapanmaz.

Tekrar gönderim — replayed

Yanıttaki replayed: true = aynı lineId ile tekrar gönderim algılandı, yazma YAPILMADI, doküman değişmedi. Retry sonrası bunu görüp "ödemem zaten kayıtlı" diyebilirsin. Bu durumda hiçbir event yayılmaz (doküman değişmediği için).

Ekleme moduna özgü hatalar

Yanıt

// ekleme başarılı (dokümandaki 100₺ nakit korundu, 240₺ kart eklendi → 340)
{ "success": true, "data": { "packetId": "e2e-append-packet", "paid": 340, "replayed": false } }

// aynı lineId ikinci kez → YAZMA YOK, doküman değişmedi
{ "success": true, "data": { "packetId": "e2e-append-packet", "paid": 340, "replayed": true } }

// hata — gövde `status` alanını da taşır (HTTP kodunun kopyası)
{ "success": false, "status": 400, "message": "append_replay_amount_mismatch" }

replayed ⏳ ekleme modu ile birlikte gelir; replace modunda anlamı yoktur.

Kurallar & hatalar

Hepsi HTTP 200 + { success:false, message } (rate limit 429 hariç). Gerçek mesajlar:

payments[] — satır kimliği (lineId) & metadata

İki alan da opsiyoneldir; hiçbiri gönderilmezse davranış bugünküyle aynıdır (mevcut eklentiler etkilenmez). Tam kurallar: Satır Kimliği & metadata.