Ügyfélszámla: egyenleg és hűségpontok

Minden ügyfél (api/v1/customers) két külön, tartós számlát vezet:

• Előre fizetett egyenleg (accountBalance) — valódi pénzből álló egyenleg, amelyet az ügyfél előre befizet, majd vásárláskor fizetőeszközként használ. Kifizethető.
• Hűségpontok / bónusz (loyaltyPoints / bonusBalance) — vásárláskor jóváírt és beváltott pontok/bónusz. Nem fizethető ki (az egyenleg kifizetésekor a bónusz elévül).

Ez az oldal a REST API áttekintés egy korábbi téves adatát javítja: nincs POST /customers/{id}/credit és nincs GET /customers/{id}/transactions — ezek az útvonalak a kódban nem léteznek. A valódi útvonalak alább vannak dokumentálva.

Végpontok

CustomersController — alap: api/v1/customers:

Metódus	Végpont	Cél
GET	/{id}/account-transactions	Egyenleg-/számlamozgások (előre fizetett főkönyv)
GET	/{id}/point-transactions	Hűségpont-mozgások
POST	/{id}/payout	Maradék egyenleg kifizetése (csak accountBalance, bónusz nem)
POST	/{id}/settle	Nyitott egyenleg (pl. diszkó-adóslevél) kiegyenlítése befizetéssel
GET	/card/{cardId}	Ügyfél azonosítása ügyfélkártya alapján
GET	/{id}/invoice-summary	Az ügyfél számla-/előfizetés-áttekintése

Mindkét tranzakciós végpont opcionálisan elfogadja a dateFrom/dateTo lekérdezési paramétert az időszak szűkítésére.

Számlamozgások (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"
    }
  ]
}

A type egy int saját nyilvános enum-séma nélkül; a gyakorlatban megfigyelt értékek: 0 feltöltés/befizetés, 1 felhasználás (fizetés egyenlegből), 2 korrekció (kézi sztornó-helyesbítés), 3 bónusz jóváírása, 4 bónusz felhasználása/elévülése, 5 kifizetés.

Pontmozgások (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 = jóváírva (Earned), 1 = beváltva (Redeemed), 2 = korrekció (Correction).

Kifizetés (payout)

Egyenleget fizet ki az accountBalance értékből (a bónuszból nem — az ekkor elévül).

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 } }

Hibaeset (nincs elég egyenleg) — 400, errorCode: "INSUFFICIENT_BALANCE" értékkel.

Egyenleg kiegyenlítése (settle)

Nyitott (negatív) egyenleg esetén — pl. diszkó-adóslevél (távozáskor fedezetlen maradékösszeg, lásd Diszkó-API) — az ügyfél befizet, és az egyenleg a nulla felé mozdul:

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

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

A method szabadon megadható (alapértelmezés "Bar"), és csak a könyvelés leírásába kerül — nincs kapcsolat fizetési terminállal.

Egyenleg feltöltése — a valódi út

Nincs külön /credit végpont. Az előre fizetett egyenleg feltöltése ehelyett ugyanúgy történik, mint bármely más értékesítés: a szokásos fizetési végpontokon keresztül (POST /api/v1/payments/direct vagy POST /api/v1/payments/table), két feltétellel:

1. Az eladott termék extraOption: 1 (KundenAufladung) értékű — egy „feltöltő termék” (pl. „Egyenleg 50 €”), amelyet a szokásos termék-API-val hoztak létre (POST /api/v1/articles).
2. A fizetés a customerId mezővel az ügyfélhez van kapcsolva.

A termék ára (× mennyiség) ekkor automatikusan jóváírásra kerül az ügyfél accountBalance egyenlegén — a tényleges fizetés lebonyolítása mellett (a vendég a feltöltési összeget a szokásos módon fizeti ki a payments[] segítségével, pl. készpénzzel vagy kártyával). Ha a terméknél feltöltési bónusz van beállítva (cardUploadPercent/cardUploadAmount), automatikusan bónusz is jóváírásra kerül.

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"
}

A feltöltés ezután type: 0 bejegyzésként jelenik meg az account-transactions listában (lásd fent), a receiptId révén összekapcsolva a keletkezett pénztári bizonylattal.

Folyamat

1. Ügyfél felvétele — POST /api/v1/customers (minimum: name/customerNumber).
2. Egyenleg feltöltése — egy KundenAufladung termék értékesítése customerId megadásával (POST /api/v1/payments/direct, lásd fent).
3. Könyvelés a számlára — az ügyfél későbbi vásárlásai payments[].method = "CustomerAccount" értékkel az accountBalance egyenlegből vonódnak le (terhelés, nem feltöltés).
4. Ellenőrzés — a GET /{id}/account-transactions ellenőrzi az előzményeket.
5. Pontok — a szokásos értékesítési folyamatban kerülnek jóváírásra/beváltásra, és a GET /{id}/point-transactions végponton olvashatók.
6. Kifizetés/kiegyenlítés — POST /{id}/payout (maradék egyenleg vissza) vagy POST /{id}/settle (nyitott egyenleg/adóslevél kiegyenlítése).

Elhatárolás: ügyfélszámla-egyenleg ↔ diszkókártya-egyenleg

Két különböző fogalom, amelyeket könnyű összekeverni:

	Ügyfélszámla-egyenleg	Diszkókártya-egyenleg
Végpont	payments/* + customers/*	POST /api/v1/disco/guest/{cardId}/topup
Kötődés	az ügyfél adatrekordjához, tartósan	a fizikai kártyához, egy tartózkodás idejére
Kifizetés	POST /{id}/payout	Maradék egyenleg kiléptetéskor (disco/guest/{cardId}/checkout)

→ Részletek a kártyás változatról: Diszkó-API (készpénzmentes klub).