Z raporu ve kasa Restroid’e nasıl iletilir

Müşteri Z’yi bize nasıl iletir

1. Gün boyunca her kapanan fiş sale-created ile gelir (stok / kasa satırı orada yazılır).
2. Kasiyer sizin POS’unuzda Z alır veya günü kapatır. X (ara rapor) bu API’ye gitmez.
3. Sizin backend, o kapanışın özetini Restroid’e bir kez POST eder. Restroid kaydı Finans → Z Raporları listesine yazar.
4. Webhook açıksa Restroid size cash.shift_closed döner (data.source = z.created). Bu, sizin Z POST’unuzun kopyası değil; Cloud’un günü işlediğinin haberidir.

Canlı adres: POST https://cloud.restroid.com/api/public/partner/v1/hooks/z-report-created

Geliştirme: cloud.restroid.dev. Eşdeğer yollar: /hooks/z-report, /hooks/z.created.

Ne zaman göndermelisiniz

• Gün bitti, kasiyer Z aldı veya «günü kapat» dedi — o anda, bir kez.
• Açık masa, taslak, X raporu veya öğle arası nakit sayımı Z değildir; bunları bu uca atmayın.
• restaurantId GET /restaurants yanıtındaki UUID’dir. Kendi şube kodunuz değildir.
• externalId sizin Z / gün kapanış numaranızdır (ör. Z-20260828-004). Satış fiş numarası buraya konmaz.
• Kapsamda cash işaretli olmalı. sales_inbound Z yazmaz.

İstek gövdesi

Başlıklar

Örnek (curl)

curl -sS -X POST https://cloud.restroid.com/api/public/partner/v1/hooks/z-report-created \
  -H "Api-Key: rkp_..." \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "restaurantId": "3f2a1c0e-1111-4222-a333-444455556666",
    "externalId": "Z-20260828-004",
    "occurredAt": "2026-08-28T23:05:00+03:00",
    "cashierName": "Ayşe",
    "reportNumber": 4,
    "totalSales": 1850.5,
    "cashAmount": 800,
    "discountAmount": 20,
    "canceledAmount": 0,
    "complimentaryAmount": 0,
    "wasteAmount": 0,
    "payments": [
      { "method": "cash", "amount": 800, "count": 10 },
      { "method": "card", "amount": 1050.5, "count": 14 }
    ],
    "countedCash": [
      { "name": "Ana kasa", "expected": 800, "counted": 795 }
    ]
  }'

Tutarlar sayı olmalı (1850.5), "1.850,50" metin değil. Gövde 256 KB üstü 413.

Yanıt

202 — kabul

{
  "accepted": true,
  "event": "z.created",
  "restaurantId": "…",
  "externalId": "Z-20260828-004",
  "sourceEventId": "partner-z:…:Z-20260828-004"
}

202 — aynı externalId tekrar

{
  "accepted": true,
  "duplicate": true,
  "event": "z.created",
  "restaurantId": "…",
  "externalId": "Z-20260828-004"
}

Restroid bunu panele nasıl yazar

• Kayıt Finans → Z Raporları listesine düşer (şube kodu, kasiyer, ciro, iskonto, iptal, ikram, fire).
• İşletme sahibine «Z rapor alındı» bildirimi gidebilir.
• Açık masa silinmez, Restroid POS fişleri kapanmaz. Partner Z, Cloud POS gün kapatmanın yerine geçmez.
• Kasa hesabı bakiyesi Z ile değişmez. Nakit zaten her sale-created satırında yazılmıştır.

X raporu, nakit vardiya, kasa okuma

Restroid Cloud POS’ta gün kapanırsa yön tersidir: Restroid size cash.shift_closed atar. Siz Z aldıysanız siz Restroid’e yazarsınız; sonra aynı olay source: z.created ile size de dönebilir. Ayrıntı: Webhook.

Para girişi / çıkışı

Çekmeceye nakit koyunca veya çekmeceden nakit alınca. Kapsam cash veya accounting. Aynı externalId tekrarında 202 duplicate.

POST /hooks/cash-in
{
  "restaurantId": "…",
  "externalId": "IN-20260828-01",
  "amount": 200,
  "description": "Bozuk para",
  "accountName": "Ana kasa",
  "occurredAt": "2026-08-28T14:10:00+03:00"
}

POST /hooks/cash-out
{
  "restaurantId": "…",
  "externalId": "OUT-20260828-01",
  "amount": 80,
  "description": "Market"
}

accountName paneldeki nakit kasa adı ile eşleşmezse ilk nakit hesap kullanılır. Giriş eşdeğerleri: /hooks/cash.in, /hooks/cash-inflow. Çıkış: /hooks/cash.out, /hooks/cash-outflow.

Nakit vardiya (öğle teslim)

Z değildir. Kasiyer çekmeceyi sayıp teslim edince bir kez. Kapsam cash. Kayıt Finans → Nakit vardiya listesine düşer.

POST /hooks/cash-shift-closed
{
  "restaurantId": "…",
  "externalId": "V-20260828-2",
  "startedAt": "2026-08-28T08:00:00+03:00",
  "occurredAt": "2026-08-28T16:00:00+03:00",
  "countedAmount": 790,
  "expectedAmount": 800,
  "dropAmount": 750,
  "floatLeft": 40
}

varianceAmount yoksa counted − expected yazılır (−10). Eşdeğer: /hooks/shift-closed, /hooks/cash.shift_closed. Webhook açıksa cash.shift_closed (source: partner.shift) döner.

Gider

Kapsam accounting. categoryName Cloud’daki gider türü adı ile birebir (büyük/küçük harf duyarsız) eşleşirse bağlanır; yoksa yalnız açıklamada kalır. Kategori oluşturmaz.

POST /hooks/expense-created
{
  "restaurantId": "…",
  "externalId": "G-20260828-04",
  "amount": 45.5,
  "description": "Su",
  "categoryName": "Mutfak"
}

GET /restaurants/{id}/cash

Kapsam cash. Yalnız type = cash hesaplar (banka / kart tanımı dönmez).

GET /restaurants/{restaurantId}/cash?limit=50&offset=0

{
  "restaurantId": "…",
  "cashAccounts": [
    {
      "id": "…",
      "name": "Ana kasa",
      "type": "cash",
      "currencyCode": "TRY",
      "balance": "1200.00",
      "showOnPos": true
    }
  ]
}

GET /restaurants/{id}/z-reports

Kapsam cash. Son Z’ler, yenisi üstte. ?limit= / ?offset=.

{
  "restaurantId": "…",
  "reports": [
    {
      "id": "…",
      "reportNumber": 4,
      "occurredAt": "2026-08-28T20:05:00.000Z",
      "cashierName": "Ayşe",
      "totalSales": 1850.5,
      "discountAmount": 20,
      "canceledAmount": 0,
      "complimentaryAmount": 0,
      "wasteAmount": 0,
      "branchCode": "BSK"
    }
  ]
}

Vardiyalar

GET /restaurants/{restaurantId}/cash-shifts

{
  "restaurantId": "…",
  "shifts": [
    {
      "id": "…",
      "seq": 2,
      "startedAt": "…",
      "closedAt": "…",
      "countedAmount": 790,
      "dropAmount": 750,
      "floatLeft": 40,
      "varianceAmount": -10,
      "personnelName": null
    }
  ]
}

Sık yapılan hatalar

• Z’yi sale-created ile göndermek. Fiş satırları oraya, gün özeti buraya.
• X raporunu veya öğle sayımını Z sanmak. Öğle teslim cash-shift-closed iledir.
• Gideri cash-out sanmak. Fatura / gider kalemi expense-created ister; description zorunludur.
• Her fiş kapanışında Z atmak. Z günde bir (veya sizin kuralınız kadar) kez.
• restaurantId olarak şube kodu yazmak.
• totalSales’i metin göndermek.
• cash kapsamını istememek — uç 403 döner.