Masa Ödemeleri — POST /plugin-api/tables/update-payments ✓ Canlı

İstek

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

{
  "tableId": "tbl-7a3f...",                       // ZORUNLU — açık masanın doc id'si
  "expectedUuid": "9f3ab27c-...",                  // ops AMA verilirse ZORUNLU eşleşir — oturum kapısı (409 session_changed)
  "mode": "replace",                               // ops — "replace" (VARSAYILAN) | "append"  🧪 append yalnız SANDBOX (prod'da YOK, planlanmıyor)
  "payments": [                                    // ZORUNLU — replace: masanın YENİ ödeme listesi (FULL REPLACE)
    { "price": 268, "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 · write rate-limit.
• mode opsiyonel, varsayılan "replace" — göndermezsen davranış eskisiyle bit-bit aynı.
• "replace": payments masanın 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.
• tableId: açık masa doc id'si — tables/open'dan al.
• expectedUuid: opsiyonel oturum kapısı — gönderirsen masanın o anki oturum uuid'si ile eşleşmek zorundadır; eşleşmezse 409 session_changed ve hiçbir şey yazılmaz. Aşağıdaki bölüme bak — gecikmeli yazan her entegrasyon için pratikte zorunludur.

expectedUuid — oturum kapısı

• Opsiyonel ama verildiğinde zorunlu eşleşir: göndermezsen kapı çalışmaz; gönderdiğin değer tutmuyorsa istek 409 session_changed alır ve yazma hiç yapılmaz.
• Değeri nereden alırsın: ödeme terminali sağlayıcısıysan komut gövdesinde write.expectedUuid olarak gelir — satır yazarken onu geri ver. Kendi akışını kuruyorsan masanın okuma yanıtındaki oturum uuid'sini taşı.
• Gerçek ortamda doğrulandı: oturum değişince yazma reddediliyor ve yeni müşterinin hesabına hiçbir şey yazılmıyor.

Ekleme modu — mode: "append"

Sözleşme packets/update-payments ile birebir aynıdır — yalnız kimlik alanı değişir (tableId). Gerekçe, lineId zorunluluğu, replayed ve hata kodlarının tamamı için o sayfayı oku; burada özet:

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

{
  "tableId": "tbl-7a3f...",
  "mode": "append",                                // mevcut satırlara DOKUNMAZ — üzerine ekler
  "payments": [
    { "price": 268, "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 (onları tekrar gönderme).
• lineId ZORUNLU — tekrar gönderim kalkanı: kimliksiz satıra platform her çağrıda farklı kimlik üretir, ağ hatasındaki retry ikinci satır olur = çift tahsilat.
• lineId GÜÇLÜ olmalı — en az 8 karakter, saf rakam değil ("00000001" reddedilir). Grandfather affı ekleme modunda İŞLEMEZ: af yalnız dokümanda zaten var olan kimlikleri bağışlar. Kalıp: pay-01H9XYZ… (önek + uuid).
• paid birleşim üzerinden yeniden hesaplanır; paid ≤ total kapısı geçerli. Kapatma yok.
• İki tavan: istek başına ≤ 20 satır (şema, her iki modda); ekleme modunda birleşim ≤ 100.
• Yanıttaki replayed: true = aynı lineId ile tekrar gönderim, yazma yapılmadı, event yayılmadı.
• Hatalar (400): append_requires_line_id · append_requires_payment_line · append_partial_duplicate · append_replay_amount_mismatch · append_replay_method_mismatch · too_many_payment_lines (birleşim > 100 satır).

Yanıt

// ekleme başarılı (masadaki 100₺ nakit KORUNDU, 150₺ eklendi → 250)
{ "success": true, "data": { "tableId": "e2e-table-A2", "paid": 250, "replayed": false } }

// aynı lineId ikinci kez → yazma YOK, ikinci satır oluşmadı
{ "success": true, "data": { "tableId": "e2e-table-A2", "paid": 250, "replayed": true } }

Ödeme yöntemi doğrulaması (packets ile birebir)

Kurallar packets/update-payments ile aynı. Önce payment-methods/list (payment_methods:read).

Kurallar & hatalar

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.