Müşteri Hesabı: Bakiye ve Sadakat Puanları

Her müşteri (api/v1/customers), birbirinden ayrı iki kalıcı hesap yürütür:

• Ön ödemeli bakiye (accountBalance) — müşterinin önceden yatırdığı ve ardından alışverişlerde ödeme aracı olarak kullandığı gerçek para bakiyesi. Çekilebilir.
• Sadakat puanı / Bonus (loyaltyPoints / bonusBalance) — alışverişlerde kazanılan ve kullanılan puanlar/bonus. Çekilemez (bir bakiye ödemesinde bonus geçersiz olur).

Bu sayfa, REST API genel bakışındaki eski bir hatalı bilgiyi düzeltir: POST /customers/{id}/credit yoktur ve GET /customers/{id}/transactions yoktur — bu rotalar kodda mevcut değildir. Gerçek rotalar aşağıda belgelenmiştir.

Uç Noktalar

CustomersController — Temel api/v1/customers:

Yöntem	Uç Nokta	Amaç
GET	/{id}/account-transactions	Bakiye/hesap hareketleri (ön ödeme defteri)
GET	/{id}/point-transactions	Sadakat puanı hareketleri
POST	/{id}/payout	Kalan bakiyeyi öde (yalnızca accountBalance, bonus değil)
POST	/{id}/settle	Açık bakiyeyi (ör. Disko borç senedi) yatırımla kapatma
GET	/card/{cardId}	Müşteriyi müşteri kartı üzerinden çözümleme
GET	/{id}/invoice-summary	Müşterinin fatura/abonelik genel bakışı

Her iki işlem uç noktası da dönemi sınırlamak için isteğe bağlı olarak dateFrom/dateTo sorgu parametrelerini kabul eder.

Hesap hareketleri (account-transactions)

GET /api/v1/customers/cus_a1b2c3/account-transactions?dateFrom=2026-07-01&dateTo=2026-07-31
Authorization: Bearer eyJ...

{
  "success": true,
  "data": [
    {
      "id": "cat_001",
      "customerId": "cus_a1b2c3",
      "customerName": "Max Mustermann",
      "receiptId": "rec_9f8e7d",
      "type": 0,
      "amount": 50.00,
      "balanceAfter": 50.00,
      "bonusBalanceAfter": 2.50,
      "description": "Guthaben-Aufladung: Guthaben 50€ x 1",
      "personalId": "usr_kasse1",
      "transactionDate": "2026-07-05T18:22:00Z"
    }
  ]
}

type, kendi genel enum şeması olmayan bir tam sayıdır; pratikte gözlemlenen değerler: 0 yükleme/yatırma, 1 kullanım (bakiyeyle ödeme), 2 düzeltme (manuel iptal düzeltmesi), 3 bonus tahakkuku, 4 bonus kullanımı/kaybı, 5 ödeme.

Puan hareketleri (point-transactions)

GET /api/v1/customers/cus_a1b2c3/point-transactions
Authorization: Bearer eyJ...

{
  "success": true,
  "data": [
    {
      "id": "cpt_001",
      "customerId": "cus_a1b2c3",
      "customerName": "Max Mustermann",
      "receiptId": "rec_9f8e7d",
      "articleId": "art_cola",
      "articleName": "Cola 0,3l",
      "type": 0,
      "points": 3.5,
      "pointsAfter": 42.5,
      "description": "Punkte für Verkauf",
      "transactionDate": "2026-07-05T18:22:00Z"
    }
  ]
}

type: 0 = kazanılan (Earned), 1 = kullanılan (Redeemed), 2 = düzeltme (Correction).

Ödeme (payout)

accountBalance'tan bakiye öder (bonusdan değil — bu sırada bonus geçersiz olur).

POST /api/v1/customers/cus_a1b2c3/payout
Authorization: Bearer eyJ...
Content-Type: application/json

{ "amount": 20.00 }

{ "success": true, "data": { "success": true, "accountBalance": 30.00, "bonusBalance": 0 } }

Hata durumu (yetersiz bakiye) — errorCode: "INSUFFICIENT_BALANCE" ile 400.

Bakiyeyi kapatma (settle)

Açık (negatif) bir bakiye için — ör. bir Disko borç senedi (çıkışta karşılanmamış kalan tutar, bkz. Disko API'si) — müşteri para yatırır, bakiye sıfıra doğru hareket eder:

POST /api/v1/customers/cus_a1b2c3/settle
Authorization: Bearer eyJ...
Content-Type: application/json

{ "amount": 15.00, "method": "EC" }

method serbestçe belirlenir (varsayılan "Bar") ve yalnızca kaydın açıklamasında yer alır — bir ödeme terminaliyle bağlantı yoktur.

Bakiye Yükleme — Gerçek Yol

Ayrı bir /credit uç noktası yoktur. Bunun yerine bir ön ödemeli bakiye, tıpkı diğer her satış gibi yüklenir: normal ödeme uç noktaları üzerinden (POST /api/v1/payments/direct veya POST /api/v1/payments/table), iki koşulla:

1. Satılan ürünün extraOption: 1 (KundenAufladung) değeri vardır — normal ürün API'si (POST /api/v1/articles) üzerinden oluşturulan bir „yükleme ürünü" (ör. „Guthaben 50 €").
2. Ödeme, customerId ile müşteriye bağlanmıştır.

Ürün fiyatı (× miktar) daha sonra otomatik olarak müşterinin accountBalance'ına yansıtılır — asıl ödeme işlemine ek olarak (misafir, yükleme tutarını payments[] üzerinden tamamen normal şekilde öder, ör. nakit veya kart). Üründe bir yükleme bonusu yapılandırılmışsa (cardUploadPercent/cardUploadAmount), otomatik olarak ek bonus da tahakkuk ettirilir.

POST /api/v1/payments/direct
Authorization: Bearer eyJ...
Idempotency-Key: 6f1c2a9e-3b7d-4e21-9b0a-1f2e3d4c5b6a
Content-Type: application/json

{
  "items": [ { "articleId": "art_aufladung50", "quantity": 1 } ],
  "payments": [ { "method": "Cash", "amount": 50.00 } ],
  "customerId": "cus_a1b2c3"
}

Yükleme, bundan sonra account-transactions içinde (yukarıya bakın) receiptId üzerinden oluşan kasa fişiyle bağlantılı bir type: 0 kaydı olarak görünür.

Akış

1. Müşteri oluşturma — POST /api/v1/customers (asgari: name/customerNumber).
2. Bakiye yükleme — customerId ile bir KundenAufladung ürününün satışı (POST /api/v1/payments/direct, yukarıya bakın).
3. Hesaba kaydetme — müşterinin sonraki alışverişlerinde payments[].method = "CustomerAccount" ile accountBalance'tan düşülür (borçlandırılır, yüklenmez).
4. Kontrol — GET /{id}/account-transactions geçmişi kontrol eder.
5. Puanlar — normal satış sürecinde kazanılır/kullanılır, GET /{id}/point-transactions üzerinden görülebilir.
6. Ödeme/Kapatma — POST /{id}/payout (kalan bakiyeyi geri öde) veya POST /{id}/settle (açık bakiyeyi/borç senedini kapat).

Ayrım: Müşteri Hesabı Bakiyesi ↔ Disko Kart Bakiyesi

Kolayca karıştırılan iki farklı kavram:

	Müşteri Hesabı Bakiyesi	Disko Kart Bakiyesi
Uç Nokta	payments/* + customers/*	POST /api/v1/disco/guest/{cardId}/topup
Bağlılık	müşteri kaydına, kalıcı	fiziksel karta, bir ziyaret için
Ödeme	POST /{id}/payout	çıkışta kalan bakiye (disco/guest/{cardId}/checkout)

→ Kart varyantına ilişkin ayrıntılar: Disko API'si (Nakitsiz Kulüp).