REST API

A DiKAS átfogó REST API-t kínál több mint 565 nyilvános végponttal, több mint 60 területen. Ezzel a DiKAS-t beillesztheti meglévő infrastruktúrájába — a pénztárhelytől a diszkón, a szállodán, a foglaláson át egészen a jegyértékesítésig. (A belső és a régi /rest/ végpontok szándékosan nem szerepelnek a nyilvános referenciában — lásd lentebb a külön szakaszt.)

Hitelesítés

Az API JWT Bearer tokent használ a hitelesítéshez.

Token igénylése

POST /api/v1/auth/login
Content-Type: application/json

{
  "username": "admin",
  "password": "admin"
}

Válasz:

{
  "success": true,
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIs...",
    "refreshToken": "dGhpcyBpcyBhIH...",
    "expiresAt": "2026-07-13T22:00:00Z",
    "user": { "id": "usr_...", "name": "Admin", "roles": ["Admin"] }
  }
}

Token használata

Adja meg a tokent az Authorization fejlécben:

GET /api/v1/articles
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Token megújítása

Csak a refreshToken szükséges — belépési adatok nem:

POST /api/v1/auth/refresh
Content-Type: application/json

{
  "refreshToken": "dGhpcyBpcyBh..."
}

Lejárt vagy érvénytelen refresh token esetén a válasz 401 — ilyenkor újra /login szükséges.

API-formátum

Minden válasz ezt a sémát követi:

{
  "success": true,
  "data": { ... }
}

Hiba esetén:

{
  "success": false,
  "errorCode": "NOT_FOUND",
  "errorMessage": "Artikel mit ID 'art_123' existiert nicht"
}

Ellenőrzési hibáknál ezen felül validationErrors is szerepel (field/message elemekből álló lista). Mindig először a success értéket ellenőrizze; a mezőnevek mindenhol camelCase formájúak.

Az Ön rendszerének egyedi száma (ismétlésbiztonság)

Ha az Ön alkalmazása bizonylatokat, készpénzes kiadásokat vagy átutalásokat hoz létre (pl. egy felvásárlást felvásárlási számmal), egy kérés időtúllépés vagy megszakadt kapcsolat miatt bizonytalan eredménnyel végződhet. Hogy egy ismétlés soha ne könyveljen kétszer, adja meg az externalReference mezőben a folyamat egyedi számát (legfeljebb 100 karakter, pl. A-2026-000123). Ez a következőkre vonatkozik:

Végpont	Mire
POST /api/v1/incoming-documents	Bizonylat (pl. felvásárlási bizonylat), a PDF utána a POST /api/v1/incoming-documents/{id}/attachments végponton
POST /api/v1/spendings	Készpénzes kiadás, azonnal könyvelésre kerül
POST /api/v1/saved-transfers	Előjegyzett banki átutalás

Ismétlés esetén a szerver így válaszol:

Kérés	Eredmény
azonos szám, azonos tartalom	a már létrehozott folyamat, második könyvelés nélkül
azonos szám, eltérő tartalom	409 a(z) EXTERNAL_REFERENCE_CONFLICT errorCode értékkel; az első folyamat változatlan marad
egy törölt folyamat száma	409 a(z) EXTERNAL_REFERENCE_DELETED értékkel; a számokat a rendszer soha nem használja újra

A szám kis- és nagybetűi, valamint a szélein álló szóközök nem számítanak. Ehelyett vagy emellett az Idempotency-Key fejléc is hat; ütközés esetén a kód ekkor IDEMPOTENCY_KEY_REUSED. Időtúllépés esetén ugyanazt a kérést ugyanazzal a számmal küldje el újra — soha ne új számmal.

Példa (készpénzes kiadás egy felvásárláshoz, adómentes, 120,00 €):

POST /api/v1/spendings
Authorization: Bearer <token>
Content-Type: application/json

{
  "comment": "Ankauf A-2026-000123",
  "accountMode": 1,
  "accountType": 1,
  "receiptDate": "2026-10-16",
  "amountTaxFree": 120.00,
  "externalReference": "A-2026-000123"
}

A válasz tartalmazza az id, az externalReference és a total mezőt.

Megjegyzés a készpénzes kiadáshoz

A kiadás a létrehozáskor azonnal könyvelésre kerül. Csak akkor hozza létre, amikor a pénz átadása megerősítést nyert. Egy kiadás csak addig törölhető, amíg a nap nincs lezárva, és az időszak nem került átadásra a könyvelésnek.

Csoportos átutalás SEPA-fájlként

Több előjegyzett átutalást egyetlen SEPA-fájlként (pain.001) kérhet le banki programja számára:

POST /api/v1/saved-transfers/sepa-file
Authorization: Bearer <token>
Content-Type: application/json

{ "ids": ["<id-1>", "<id-2>"], "bankAccountId": null, "executionDate": "2026-10-16" }

• Hozzáférés csak rendszergazdai jogosultsággal (Admin szerepkör).
• Csak a nyitott átutalások kerülnek bele. A már végrehajtott vagy éppen folyamatban lévők elutasításra kerülnek.
• Egy fájl összes átutalása egyetlen bankszámlát terhel. bankAccountId nélkül a megbízások közös bankszámlája érvényes, egyébként az alapértelmezett bankszámla.
• Az IBAN-okat a rendszer ellenőrzi, a fájl legfeljebb 500 tételt tartalmaz. A neveket és a közleményt a SEPA-karakterkészletre rövidíti (az umlautokból ae, oe, ue, ss lesz).
• A fájl üzenetazonosítója az átutalásokból és a dátumból adódik. Ugyanaz a fájl ugyanazon a napon ugyanazt az azonosítót kapja, így egy második feltöltés duplikátumként tűnik fel a banknál. Szerepel a válasz X-Sepa-Message-Id fejlécében is (mellette X-Sepa-Count és X-Sepa-Sum).
• Aki az átutalásokat közvetlenül a banknál szeretné benyújtani, a POST /api/v1/saved-transfers/execute-batch végpontot használja ugyanazzal a törzzsel (ids). A válasz megfelel az egyedi végrehajtásénak (success, tan_required vagy vop_confirmation); a TAN után minden átutalást complete (siker) vagy reset hívással zár le.
• A lekérés nem változtat állapotot. A banki végrehajtás után minden átutalást a POST /api/v1/saved-transfers/{id}/complete hívással jelöljön fizetettnek.

Kéréskorlát (HTTP 429)

A korlát kliens-IP-címenként, rögzített egyperces ablakban számol. Túllépés esetén a szerver HTTP 429 választ ad — nincs várakozási sor, a kérés azonnal elutasításra kerül.

Terület	Korlát
Minden végpont (alapvédelem)	1 200 kérés/perc
Bejelentkezés, egyszer használatos kódok és egyes nyilvános írási/lekérdezési műveletek	10 kérés/perc

A szigorú korlát brute-force elleni védelem, és az alapvédelemtől függetlenül érvényes — többek között a bejelentkezést és az OTP-t, valamint olyan nyilvános végpontokat érint, mint a vendégfoglalás és az utalvány-lekérdezés az online fizetési folyamatban.

Integrációkhoz

Kezelje a 429-et átmeneti hibaként: várjon rövid ideig, és próbálja újra (exponenciálisan növekvő várakozási idővel). Egy tömeges importnak blokkokban kell futnia, nem szoros ciklusban.

Végpontok áttekintése

Termékek

Metódus	Végpont	Leírás
GET	/api/v1/articles	Összes termék lekérése
GET	/api/v1/articles/{id}	Egy termék lekérése
POST	/api/v1/articles	Termék létrehozása
PUT	/api/v1/articles/{id}	Termék frissítése
DELETE	/api/v1/articles/{id}	Termék törlése
GET	/api/v1/article-groups	Összes csoport lekérése
POST	/api/v1/article-groups	Csoport létrehozása

Példa: termék létrehozása

POST /api/v1/articles
Authorization: Bearer eyJ...
Content-Type: application/json

{
  "name": "Cola 0,3l",
  "price": 3.50,
  "taxClass": 0,
  "groupId": "artgrp_abc123"
}

Válasz (201 Created):

{
  "success": true,
  "data": {
    "id": "art_def456",
    "name": "Cola 0,3l",
    "price": 3.50,
    "taxClass": 0,
    "groupId": "artgrp_abc123",
    "isActive": true,
    "createdDate": "2026-03-05T18:30:00Z",
    "changedDate": "2026-03-05T18:30:00Z"
  }
}

Ügyfelek

Metódus	Végpont	Leírás
GET	/api/v1/customers	Összes ügyfél
GET	/api/v1/customers/{id}	Egy ügyfél
POST	/api/v1/customers	Ügyfél létrehozása
PUT	/api/v1/customers/{id}	Ügyfél frissítése
DELETE	/api/v1/customers/{id}	Ügyfél törlése
GET	/api/v1/customers/{id}/account-transactions	Egyenleg-/számlamozgások
GET	/api/v1/customers/{id}/point-transactions	Hűségpont-mozgások
POST	/api/v1/customers/{id}/payout	Egyenleg kifizetése
POST	/api/v1/customers/{id}/settle	Nyitott egyenleg (adóslevél) kiegyenlítése
GET	/api/v1/customers/card/{cardId}	Ügyfél azonosítása ügyfélkártya alapján

Nincs POST /customers/{id}/credit — az egyenleg a szokásos fizetési végpontokon keresztül tölthető fel. Részletek, példák és a pontos feltöltési út: → Ügyfélszámla: egyenleg és pontok

Asztalok

Metódus	Végpont	Leírás
GET	/api/v1/tables	Összes asztal
GET	/api/v1/tables/{id}	Egy asztal
POST	/api/v1/tables	Asztal létrehozása
POST	/api/v1/tables/{id}/gang	Fogás váltása
POST	/api/v1/tables/{id}/cleaned	Megjelölés takarítottként

Rendelések és fizetések

Metódus	Végpont	Leírás
POST	/api/v1/open-bons	Rendelés leadása
POST	/api/v1/open-bons/batch	Több rendelés
POST	/api/v1/payments/direct-sale	Közvetlen értékesítés
POST	/api/v1/payments/table	Asztali fizetés
GET	/api/v1/receipts	Nyugták lekérése
POST	/api/v1/receipts/{id}/void	Nyugta sztornózása

Személyzet

Metódus	Végpont	Leírás
GET	/api/v1/staff	Összes munkatárs
POST	/api/v1/staff	Munkatárs létrehozása
POST	/api/v1/staff/switch	Pincérváltás

Napi zárás

Metódus	Végpont	Leírás
POST	/api/v1/day-close	Napi zárás végrehajtása
GET	/api/v1/day-close	Összes napi zárás
GET	/api/v1/day-close/{id}	Egy napi zárás

Jelentések

Metódus	Végpont	Leírás
GET	/api/v1/reports/revenue	Forgalmi jelentés
GET	/api/v1/reports/top-articles	Sikertermékek és gyenge termékek
GET	/api/v1/reports/wgr	Termékcsoportok
GET	/api/v1/reports/weekly	Heti kimutatás

További végpontok

Terület	Előtag	Végpontok
Diszkó	/api/v1/disco	Cashless klub, kártyák, könyvelés, statisztika — lásd Diszkó API
Utalványok	/api/v1/vouchers	Helyi utalványkezelés — elhatárolás a lánctól és példák: Utalványok és külső rendszerek
Banki műveletek	/api/v1/bank-transfers	CRUD, import, FinTS-számlalekérés (/{id}/submit-fints)
Számlák	/api/v1/invoices	CRUD, PDF
Fizetési felszólítások	/api/v1/dunning	Létrehozás, küldés
Kiadások	/api/v1/spendings	CRUD, mellékletek
Munkaidő-nyilvántartás	/api/v1/time-tracking	Blokkolás, jelentések
Műhely	/api/v1/workshop/orders	CRUD, állapot
Szálloda	/api/v1/hotel/*	Szobák, szobatípusok, foglalások, folió, housekeeping — lásd Swagger
Foglalómotor	/api/v1/booking/*	Foglalható csomagok/időpontok (pl. tanfolyamok, rendezvények) — lásd Swagger
Jegyértékesítés	/api/v1/tickets	Online jegyértékesítés — lásd Swagger
Beosztás	/api/v1/shifts, /shift-templates, /shift-positions, /shift-swaps, /absences	Műszaktervezés, csere, távollétek — lásd Swagger
Webáruház	/api/v1/online-menu, /online-shop, /online-checkout, /table-order	Online étlap, fizetési folyamat, asztali önrendelés — lásd Swagger
Raktár/ERP	/api/v1/stocks, /stock-*, /distributors, /haccp	Készlet, áruátvétel/árukiadás, leltár, szállítók, HACCP — lásd Swagger

Moduláris kiegészítő területek (szálloda, foglalómotor, jegyértékesítés)

A szálloda, a foglalómotor és a jegyértékesítés licencenként töltődik be, és egy olyan példány élő /swagger referenciájában jelenik meg, amelyen az adott modul aktiválva van — a fenti statikus referencia-pillanatképben nem szerepelnek.

Modulvégpontok

HACCP (/api/v1/haccp)

Metódus	Végpont	Leírás
GET	/api/v1/haccp/templates	Összes sablon
POST	/api/v1/haccp/templates	Új sablon létrehozása
PUT	/api/v1/haccp/templates/{id}	Sablon frissítése
DELETE	/api/v1/haccp/templates/{id}	Sablon törlése
GET	/api/v1/haccp/logs	Jegyzőkönyvek lekérdezése (szűrőkkel)
GET	/api/v1/haccp/logs/{id}	Egy jegyzőkönyv
POST	/api/v1/haccp/logs	Új jegyzőkönyv indítása
PUT	/api/v1/haccp/logs/{id}/complete	Jegyzőkönyv lezárása
POST	/api/v1/haccp/logs/{id}/photos/{index}	Fénykép feltöltése
GET	/api/v1/haccp/logs/{id}/photos/{name}	Fénykép lekérése

Kiszállítás (/api/v1/delivery)

Metódus	Végpont	Leírás
GET	/api/v1/delivery	Rendelések lekérdezése (szűrőkkel)
GET	/api/v1/delivery/{id}	Egy rendelés
GET	/api/v1/delivery/by-number/{nr}	Rendelés szám alapján
GET	/api/v1/delivery/stats	Statisztikák (darabszám állapotonként)
POST	/api/v1/delivery	Új rendelés létrehozása
PUT	/api/v1/delivery/{id}/status	Állapot frissítése
PUT	/api/v1/delivery/assign	Futár hozzárendelése
POST	/api/v1/delivery/{id}/pay	Rendelés kifizetése
POST	/api/v1/delivery/dispatch	Csoportos kiküldés (dispatch)
POST	/api/v1/delivery/place	Rendelés konyhai blokkokkal
POST	/api/v1/delivery/optimize-route	Útvonal optimalizálása
POST	/api/v1/delivery/send-route	Útvonal üzenetszövegként + térképhivatkozással (nem küld el semmit)
POST	/api/v1/delivery/{id}/load-for-edit	Betöltés szerkesztéshez
POST	/api/v1/delivery/{id}/void-item	Tétel sztornózása
PUT	/api/v1/delivery/{id}/reassign-driver	Futár áthelyezése
DELETE	/api/v1/delivery/{id}	Rendelés sztornózása

Online rendelési portál saját webáruházakhoz (/rest/online/{key}) — az Adminisztráció → Beállítások → API-kulcsok menüből származó API-kulcsot igényel:

Metódus	Végpont	Leírás
GET	/rest/online/{key}/articels	Elérhető termékek csoportokkal
GET	/rest/online/{key}/tables	Asztalcsoportok és asztalok
POST	/rest/online/{key}/order	Rendelés leadása
POST	/rest/online/{key}/open	Rendelés leadása fizetés nélkül
POST	/rest/online/{key}/pay	Már kifizetett rendelés könyvelése nyugtaként

Ismeretlen termékek

Ha a pénztár nem ismeri a rendelés egy termékét (sem azonosító, sem cikkszám, sem név alapján), a DiKAS az order, open és pay hívásnál maga hozza létre – a webáruház nevével és árával, valamint az üzlet általános adókulcsával, termékcsoport nélkül. Név nélkül nem jön létre semmi, egy deaktivált termék elutasítás marad (Article not found), és rendelésenként legfeljebb 20 új termék keletkezik.

Munkaidő-nyilvántartás (/api/v1/time-tracking)

Metódus	Végpont	Leírás
POST	/api/v1/time-tracking/stamp	Blokkolás
GET	/api/v1/time-tracking/status/{userId}	Állapot lekérdezése
GET	/api/v1/time-tracking/active-workers	Aktív munkatársak
GET	/api/v1/time-tracking/sheets/{userId}/{year}/{month}	Havi adatok
GET	/api/v1/time-tracking/report	Munkaidő-jelentés
GET	/api/v1/time-tracking/report/excel	Excel-export
PUT	/api/v1/time-tracking/sheets/{id}/stamps/{index}	Blokkolás szerkesztése
DELETE	/api/v1/time-tracking/sheets/{id}/stamps/{index}	Blokkolás törlése

Régi (legacy) API

A meglévő integrációkkal való kompatibilitás érdekében /rest/ alatt régi (legacy) végpontok is rendelkezésre állnak:

Végpont	Leírás
/rest/cp/add/{key}/{plu}	Termék könyvelése
/rest/extern/customer/{key}/...	Ügyfél-CRUD
/rest/extern/voucher/{key}/...	Helyi utalványok lekérése, létrehozása és beváltása; láncszintű kezelés nincs
/rest/online/{key}/...	Online rendelések
/rest/disco/guest/pay/{key}[/{Karte}]	Diszkókártya kifizetése és kiléptetés (pl. fizetőautomata)

Fizetőautomaták: munkaállomás és nyomtató

A /rest/disco/guest/pay esetén egy API-kulcs több fizetőautomatához is elegendő. A munkaállomás a kulcsból származik (Adminisztráció → Beállítások → API-kulcsok), a hívásban nem kell megadni (WorkplaceId lehet null). A blokknyomtatót minden automata a fizetési megbízás Printer mezőjében adja meg – nyomtatóazonosítóként vagy IP-címként, akár porttal is (192.168.1.52:9100), a kis- és nagybetű mindegy. Ha ismeretlen vagy üres, a blokk a munkaállomás célnyomtatóján, illetve az alapértelmezett nyomtatón készül; a fizetés emiatt nem hiúsul meg.

A régi végpontok JWT token helyett API-kulcsokat használnak. Az új kliensek a kulcsot X-Api-Key vagy Authorization: ApiKey … fejlécben adják át; a továbbra is kötelező {key} útvonalszakaszban ilyenkor - áll. Bizalmas kulcsok nem valók URL-be. Az eltérő válaszmezőkről és az utalványfolyamatokról lásd: Utalványok és külső rendszerek.

SignalR (valós idejű)

Valós idejű frissítésekhez (konyhai kijelző, műhely, asztalállapot):

const connection = new signalR.HubConnectionBuilder()
  .withUrl("/hubs/dikas", {
    accessTokenFactory: () => jwtToken
  })
  .build();

connection.on("OrderCreated", (data) => {
  console.log("Neue Bestellung:", data);
});

connection.on("TableStatusChanged", (data) => {
  console.log("Tisch-Status:", data);
});

await connection.start();

Mi nem része a nyilvános API-nak — és miért

Egy külső fejlesztőnek a DiKAS összes szakmai funkcióját vezérelnie kell tudnia az API-n keresztül — beleértve a pénztárat, a diszkót, a szállodát, a foglalást, a jegyértékesítést, a beosztást és a raktárat. Szándékosan nem része a nyilvános referenciának mindaz, ami magának a DiKAS-példánynak a tiszta üzemeltetése/infrastruktúrája, amit egyetlen külső rendszer sem szólít meg jogosan, vagy ami olyan hardvert feltételez, amely csak az adott eszközön található:

Kategória	Példák	Miért nem nyilvános
Üzemeltetés/infrastruktúra/állapot	Health, Sync, Restore, Reset, Relay, SystemSetup, állapotlekérdezők, naplók	Belső fürt-/példányüzemeltetés, nem szakmai integrációs pont
Önkiszolgáló portál háttérrendszere	Portal-Account/-Auth/-Invoices/-SEPA/-Subscriptions/-Support	Az önkiszolgáló ügyfélportál saját háttérrendszere, nem a POS-integrációs API
Eszközök/hardver/terminálok	Kártyaterminálok (ZVT/SumUp/Stripe), pénztári nyomtatók, készpénzes fizetés, italcsapoló rendszer, hívóazonosító, vevőkijelző, eszközkeresés/-kiépítés	Fizikai eszközöket szólít meg közvetlenül egy pénztárnál — itt nem kapcsolódik be külső rendszer
Migráció/import	Régi rendszer migrációja, CouchDB→SQL migráció	Egyszeri átköltöztető eszközök, nem a folyamatos üzemhez készültek
Számlázás/licenc	A DiKAS üzleti modelljének előfizetés-/licenckezelése	Belső szerződéses viszony a DiKAS és az ügyfél között, nem az ügyfél által végzett integráció
Bejövő webhookok	Kiszállítási platformok csatlakoztatása, Lieferando, Uber Eats, Wolt	Ezeket maguk a platformok hívják meg, nem az Ön integrációja
Belső konfiguráció/segédek	Config (háttér-/előtér-beállítások), e-mail/IMAP-küldés, geokódolás, hibajelentések, Well-Known	Technikai segédszolgáltatások önálló, kívülről hasznosítható szakmai érték nélkül

Azt, hogy egy végpont nyilvános-e, a szerver egy központi lista (InternalApiConvention) alapján dönti el — a fenti táblázat ennek gondozott magyarázata.

MI-integrátoroknak / kódoló ágenseknek

Ez az API szándékosan úgy készült, hogy egy kódoló ágens is emberi visszakérdezés nélkül integrálhassa:

• A swagger.json a géppel olvasható egyetlen hiteles forrás — https://<server>/swagger/v1/swagger.json. Tartalmaz minden nyilvános útvonalat, minden kérés-/válaszsémát és minden <summary>-leírást. Kétség esetén ezzel a dokumentummal vesse össze, ne ezzel a kézikönyvoldallal (ez gondozott, nem teljes).
• Mindig először a success értéket ellenőrizze, mielőtt a data mezőt olvassa. false esetén az errorCode (stabil, erre lehet programozni) és az errorMessage (embereknek szól) szerepel a válaszban.
• Idempotency-Key fejlécet küldjön minden fizetésnél/könyvelésnél (POST/PUT/PATCH/DELETE) — egy órán belül ugyanazzal a kulccsal megismételt kérést a rendszer nem dolgoz fel kétszer. Bizonylatoknál, készpénzes kiadásoknál és átutalásoknál ezen felül adja meg az externalReference mezőben a folyamat egyedi számát — ez tartósan érvényes, nem csak egy óráig (lásd: Az Ön rendszerének egyedi száma).
• Az azonosítók átlátszatlanok (art_a1b2c3, cus_..., rec_...) — ne elemezze őket, ne támaszkodjon a formátumukra, csak egészében adja tovább őket.
• A mezőnevek mindenhol camelCase formájúak, az összegek tizedes számok az üzlet pénznemében, a dátumértékek ISO-8601 formátumúak.
• Tervezzen token-megújítási ciklust: a hozzáférési token lejár (401) → POST /api/v1/auth/refresh a refreshToken értékkel → egyszeri ismétlés. Amíg a refresh token érvényes, nincs szükség belépési adatokkal történő újbóli bejelentkezésre.

Swagger / OpenAPI

A teljes API-referencia mind az 565 nyilvános végponttal (több mint 60 terület) és sémáival:

→ API-referencia (Swagger) — interaktív dokumentáció keresőfunkcióval

Egy futó DiKAS-példányon a Swagger közvetlenül is elérhető: https://<server>/swagger.

---

Következő lépés

→ Biztonsági mentés és visszaállítás — adatmentés