POST /plugin-api/packets/update-orders ✓ CanlıBir paketin TÜM kalemlerini (cart) değiştirir — merge değil, FULL REPLACE. total Restomenum ürün fiyatlarından yeniden hesaplanır (gönderdiğin fiyat yok sayılır). Transaction'lı (paket oku → doğrula → yaz, atomik).
← API Uçları · Yazma ailesi: create · update · update-payments.
POST {RESTOMENUM_BASE}/plugin-api/packets/update-orders
Authorization: Bearer <apiKey>
{
"packetId": "a72d70cd-...", // ZORUNLU
"cart": [ // ZORUNLU (en az 1) — paketin YENİ kalem listesi (FULL REPLACE)
{ "product": "<productId>", "quantity": 2, "options": [{ "id": "1693060234600" }], "discount": 0, "note": "",
"taxRate": 19, // ops (0..100) — satırın KDV oranı; ürünün oranını EZER
"lineId": "kiosk-9f2c", // ops — kimlik; HER istekte yeniden beyan et (yoksa satır+metadata düşer)
"metadata": [ { "key": "course", "value": "main" } ] } // ops — DİZİ (map değil)
]
}orders:write.cart paketin tüm kalemlerini değiştirir (merge değil). Kalem: { product(id ≤128), quantity(0.001..9999), options?(≤50 beyan: { id } | { title } | düz string; fiyat beyan edilemez), discount?(≥0), note?(≤500), taxRate?(0..100), lineId?, metadata? }.lineId (ops.): full-replace'te satır kimliğini korumanın tek yolu — gönderilmezse her yazımda kimlik yeniden üretilir ve TSE/fiş zinciri kopar. Kurallar + metadata: Satır kimliği & metadata.total Restomenum kaydından yeniden hesaplanır.taxRate (ops., 0–100): satırın KDV oranı. Verilirse ürünün oranını ezer ve satırda dondurulur; verilmezse ürünün oranı kullanılır. Geçersiz değer → 400 (Invalid taxRate (0-100 expected): <id>), sessizce ürüne düşmez. Beyanı yapan eklenti satırda taxRateBy ile kaydedilir — bu iç denetim izidir, hiçbir okuma yanıtında dönmez (teyitli). Kaynak: mali fişleme (fiscal.de).{ "success": true, "data": { "packetId": "a72d70cd-...", "total": 240 } }orders[]'dan sessizce düşer ve cancels[]'a hiçbir kayıt yazılmazdı — kayda girmiş bir pozisyonun izsiz kaybolması mali değişmezlik (Unveränderbarkeit) ile bağdaşmıyordu. Artık düşen satır için void kaydı yazılır: cancels[]'a girer, lineChanges'te cancelled olarak gelir ve plugin:<pluginId> aktör damgası taşır. Kuver satırı türev olduğu için dışlanır. İstek reddedilmez (meşru satır silme de bu yola düşer) — davranışın kendisi değişmedi, artık izlenebilir.Gövde { success:false, message }; HTTP kodu iş hatasına göre (Hata Kodları). Gerçek mesajlar:
| Kural | message (teyitli) |
|---|---|
quantity en az 0.001 (tartılı ürün ondalık); 0 reddedilir | "cart[0].quantity" must be greater than or equal to 0.001 (400) |
| Olmayan ürün | Product not found: <id> (400) |
Satırın taxRate'i 0–100 dışında/geçersiz | Invalid taxRate (0-100 expected): <id> (400) |
lineId biçim ihlali ya da rezerve (kuver/new) | Invalid lineId: <id> (400) |
| Aynı istekte kimlik tekrar ediyor | Duplicate lineId: <id> (400) |
| İptal edilmiş (void) satırın kimliği yeniden beyan edildi | lineId belongs to a cancelled line (409) |
metadata düz map gönderildi (dizi bekleniyor) | metadata must be an array of {key, value} (400) |
| Geçersiz key/değer, aynı yazarın tekrar eden anahtarı ya da yazar bütçesi (10 öğe / 256 karakter) aşımı | Invalid metadata: <ürün>: <sebep> (400) |
| İstek başına 20 KB ya da belge geneli 100 KB bütçe aşımı | Total metadata size after merge … (yours: X, other plugins: Y) (400) |
Timer/süre-bazlı ürün (perMin+perPrice) | Timer-priced products are not supported… (400) |
Hesaplanan total negatif (aşırı indirim) | Computed total is negative — check discounts (400) |
Mevcut paid yeni total'ı aşıyor — önce ödemeleri düşür (update-payments) | Paid (25) exceeds new total (20.5)… (400) |
| Paket yok / kapanmış | Packet not found (404) |
Product not found: … döner. Aynı istekte birden çok satırın oranı geçersizse hepsi tek mesajda listelenir.İ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.
| Alan | Tip | Zorunlu | Açıklama |
|---|---|---|---|
| cart[].lineId | string | – | Kararlı satır kimliği — çağıran taşır, platform korur. 8–64 karakter (⏳ alt sınır 1 → 8'e çıktı), alfanümerik başlar, A-Z a-z 0-9 . _ : - içerir — ⚠️ noktalama yalnız İÇERİDE (pay_01H9ABCD geçer; _pay01H9ABCD ve -pay01H9ABCD 400); saf rakamdan oluşan kimlik reddedilir ("1", "42" → 400). kuver ve new rezervedir (büyük/küçük harf farketmez) → 400 Invalid lineId: kuver. Aynı istekteki liste içinde tekrar edemez → 400 Duplicate lineId: <id>; iptal edilmiş (void) bir satırın kimliğini yeniden beyan etmek → 409 lineId belongs to a cancelled line. Gönderilmeyen satıra platform üretir ve üretilen kimlikler beyan edilenlerle çakışmaz. ⚠️ Kimlik korunması koşulludur: her istekte yeniden beyan edilmelidir (aşağı bkz.). |
| cart[].metadata | array | – | Opak korelasyon alanı — { key, value } dizisi (düz map değil; map gönderen istek 400 metadata must be an array of {key, value} alır). Platform yorumlamaz: saklar ve okuma yanıtında yazar damgasıyla (by) döner. key alfanümerik başlar, A-Za-z0-9_-, ≤64; value string | number | boolean (iç içe obje / dizi / null → 400). Bütçeler: yazar başına ≤10 öğe / satır ve value ≤256 karakter, istek başına ≤20 KB (sepet ve ödeme ayrı), belge geneli birleşme sonrası ≤100 KB. |
(uuid, lineId) çiftini anahtar yapmaktır. uuid (kalıcı satış kimliği) artık her olayda geliyor ve satış bazında kesin ayrık — çift, bu hata sınıfını kuralın da ötesinde kapatır.metadata (başka eklentilerin yazdıkları dahil) onunla birlikte gider. İstek reddedilmez (meşru satır silme de bu yola düşer) ama platform kaybı loglar. Kimliği kendi kaydından türet ve kendi tarafında sakla — doğru/yanlış örneği.metadata'ya PII yazmayın (ad, telefon, e-posta, adres, kart): sözleşme gereği yasaktır. Platform bu alanda desen taraması yapmaz — yanlış pozitif meşru bir mali kaydı reddedip satışı durdururdu; kural sözleşme düzeyindedir, ihlal eklentinin sorumluluğundadır. Müşteri verisi customers:read + rıza üzerinden alınır.orders:read yeterlidir, müşteri-PII rızası gerekmez ve alan push gövdelerinden silinmez. note, paymentNote ve iptal reason bu kapsamda değildir — onlar gerçek kullanıcı girdisi taşır ve rıza kapısına tabi olmaya devam eder.total'i düşürürken diğeri paid'i yükseltirse paid ≤ total invariantı geçici bozulabilir (farklı alanlar yazıldığından çakışma yakalanmaz). Sıralı çağır (önce kalem, sonra ödeme — ya da tersi).