Utalványok és külső rendszerek¶

Ez az útmutató a régi utalványok átvételéhez és egy másik szoftver meglévő utalvány-hozzáférésekhez való csatlakoztatásához nyújt segítséget. A döntő kérdés az, hogy melyik rendszer vezeti a kötelező érvényű maradványértéket. Ezt minden átvétel és minden párhuzamos üzem előtt rögzíteni kell.

Először rendelje hozzá az utalványállományt¶

Állomány	Felelős	Mit jelent ez a csatlakoztatásnál
Helyi DiKAS-utalványok	Egyetlen DiKAS-cég	Helyi fájlimport és helyi utalvány-API
`DCH-` kezdetű láncutalványok	Központi láncadminisztráció	Saját aktiválási, zárolási és elszámolási folyamatok; nincs helyi utalványállomány
Más szolgáltató utalványai	Az egyeztetett vezető rendszer	Az exportot, a biztonságos könyvelési lehetőségeket és a visszatérítéseket a szolgáltatóval kell tisztázni

A helyi utalvány-API nem teszi automatikusan több üzletben is érvényessé az utalványt. Egy közös állományt nem szabad több cégbe átmásolni, majd egymástól függetlenül beváltani.

→ Láncutalványok folyamatai · Helyi utalványok

Nyitott utalványok átvétele egy korábbi rendszerből¶

Cél és fordulónap rögzítése: Váltson-e be a régi rendszer ezután is utalványokat? Ki a kibocsátó, és ki viseli a nyitott értéket? Több üzlet esetén először a közös felelősséget kell tisztázni.
Adatok exportálása: Készítse elő az utalványszámot szövegként, az eredeti összeget, a nyitott maradványértéket, az utalvány fajtáját, egycélú utalványnál az eddigi adókulcsot, a kibocsátás dátumát, az érvényességet és az állapotot. A vezető nullákat és a különleges karaktereket meg kell őrizni. Az egyeztetéshez dokumentálja külön a származást és a kibocsátó üzemet is.
Régi elfogadás lezárása: A végleges export és az átállás között nem keletkezhetnek dokumentálatlan beváltások vagy feltöltések. Ellenkező esetben az átvett maradványérték már elavult.
Előnézet ellenőrzése: Az Ügyfelek → Utalványok → Importálás/exportálás menüpontban használja a sablont és a mezőhozzárendelést. A duplikált számokat, a hiányzó számokat és a valószínűtlen összegeket az átvétel előtt tisztázza. A maradványértékek összegét és a rekordok számát vesse össze az exporttal.
Egyszeri átvétel: Az import nyitott kötelezettségeket vesz át, nem új utalványeladást. A régi kártyák az átvett számukkal használhatók; az élesítés előtt szúrópróbaszerűen be kell olvasni őket.
Utóellenőrzés: Ellenőrizzen egy részben beváltott utalványt, valamint egy lezárt, illetve lejárt utalványt. A maradványértéknek és az érvényességnek egyeznie kell az egyeztetett állománnyal.
A régi rendszer lezárása: Ezt követően nem adhatja ki ugyanazt az értéket önállóan tovább. A régi beváltási előzményeket és az export igazolását őrizze meg.

Példa: A régi rendszerben 100 € értékben adtak ki utalványt, ebből 60 € már elfogyott. Átvételre kerül 100 € eredeti összeg és 40 € maradványérték. Egy 15 €-s beváltás 25 €-ra csökkenti az új maradványértéket. Egy később újra beolvasott, 40 €-t tartalmazó régi export ezt a felhasználást nem csinálhatja vissza.

Az Aktualizálás importbeállítás nem helyettesíti a folyamatos fizetési szinkronizálást. Minden újabb import előtt tisztázza, történtek-e már beváltások a DiKAS-ban az export óta.

→ Importmezők, előnézet és hibaszabályok

Helyi utalványok lekérdezése a REST API-n keresztül¶

Az 1-es verziójú API az adott példány bejelentkezését és egy Bearer-tokent használ. A példányán elérhető teljes sémák az API-referenciában találhatók.

GET /api/v1/vouchers/search/0004711
Authorization: Bearer <accessToken>

Sikeres keresés esetén a válasz a success és a data mezőn belül tartalmaz egy utalványválaszt. A további hívásokhoz a visszaadott dokumentumazonosítót használja; a nyomtatott szám és a dokumentumazonosító két különböző adat.

GET /api/v1/vouchers/<voucherId>
Authorization: Bearer <accessToken>

Ezek a lekérdezések a helyi cégre vonatkoznak. Eladáskor a helyi utalvány a szokásos fizetési hívásban, utalványos fizetési részként kerül be. Így a bizonylat és a fizetés együtt marad. Egy külön állományhívás nem hoz létre pénztári bizonylatot.

→ Bejelentkezés és fizetési végpontok

Meglévő régi (legacy) csatlakozás további használata¶

A legacy interfész három helyi utalványműveletet kínál:

Metódus	Útvonal	Cél
GET	`/rest/extern/voucher/-/{nummerOderId}`	Helyi utalvány lekérdezése szám, másodsorban dokumentumazonosító alapján
POST	`/rest/extern/voucher/-/create`	Helyi utalvány létrehozása
POST	`/rest/extern/voucher/-/redeem`	Helyi maradványérték terhelése

A - helyőrző az útvonal része marad. A Voucher jogosultságú kulcsot a fejlécben adja át:

GET /rest/extern/voucher/-/0004711
X-Api-Key: <voucher-api-key>

Helyi utalvány létrehozása:

POST /rest/extern/voucher/-/create
X-Api-Key: <voucher-api-key>
Content-Type: application/json

{
  "Amount": 50.00,
  "Name": "Geschenkgutschein",
  "Serial": "ALT-0004711",
  "ValidDays": 365,
  "IsTaxOpen": true
}

Az IsTaxOpen: true helyi többcélú/értékutalványt eredményez. A technikai példában szereplő időtartam nem ajánlás egy jogilag megengedett érvényességi időre. Az API-n keresztüli létrehozás állományművelet; nem szed be pénzt, és önmagában nem hoz létre eladási bizonylatot. Részben beváltott régi állományok átvételéhez az eredeti és a maradványösszeget külön kezelő importot használja ahelyett, hogy új eladást színlelne.

Beváltás egy meglévő külső alkalmazáson keresztül:

POST /rest/extern/voucher/-/redeem
X-Api-Key: <voucher-api-key>
Content-Type: application/json

{
  "VoucherId": "<id-aus-der-abfrage>",
  "Amount": 15.00,
  "BonId": "<eindeutige-belegreferenz>"
}

A BonId a terhelést egy bizonylathoz rendeli; nem helyettesíti annak ellenőrzését, hogy egy bizonytalan választ kapott hívás már végrehajtódott-e. A külső alkalmazásnak a saját bizonylat- és fizetési folyamatát kell egyeztetnie. A három legacy művelet nem általános interfész a láncutalványok zárolásához és visszatérítéséhez; erre szolgál a láncutalványok integrációs API-ja.

A válaszok helyes kiértékelése¶

A legacy válasz más mezőket használ, mint az 1-es verziójú API:

{
  "IsOk": true,
  "Message": "",
  "ErrorId": 0,
  "Data": {
    "VoucherId": "<dokument-id>",
    "OpenAmount": 35.00,
    "SerialDisplay": "ALT-0004711"
  }
}

Ezen felül a létrehozás és a módosítás időpontja is szerepelhet benne. Szakmai hibák is visszaérkezhetnek HTTP 200 státusszal. Ezért mindig ellenőrizze az IsOk és az ErrorId mezőt, ne csak a HTTP-státuszt. Az 1-es verziójú API-nál ezzel szemben a success, az errorCode és az errorMessage mezőt értékelje ki.

Egy nem létező utalvány szakmai hibát ad vissza, nem nulla egyenleget. Egy ismeretlen kódot ne hozzon létre automatikusan újként.

Láncutalványok integrációs API-ja¶

→ Lépésről lépésre útmutató példákkal és átvételi teszttel: Külső utalványrendszerek csatlakoztatása

Egy külső pénztár ugyanazzal a pénzkezelési logikával használhatja a láncutalványokat, mint a DiKAS-pénztárak: ellenőrzés, zárolás, a bizonylat bejelentése, megerősítés, feloldás, visszatérítés, kiadás és a változások lekérése. Az átjáró (gateway) maga nem könyvel semmit; a hívásokat a központi folyamatokra fordítja le. A maradványérték vezető rendszere eközben a DiKAS.

Állapot

Az interfész (1-es verzió) akkor áll rendelkezésre, ha a szerver a 2026. októberi szinten fut. A hozzáféréseket a lánctulajdonos a portál-API-n keresztül állítja be (lásd lent).

Hozzáférés beállítása¶

A hozzáférést a lánctulajdonos hozza létre a portálbejelentkezésével. Ő határozza meg, milyen jogosultságokat (voucher:lookup, voucher:redeem, voucher:refund …) és mely üzleteket kapja a hozzáférés:

POST /api/v1/portal/chain/<kettenId>/integration-clients
Content-Type: application/json

{"name":"Fremdkasse","scopes":["voucher:lookup","voucher:redeem","voucher:refund"],"branches":["filiale_b"]}

A válasz a hozzáférési kulcsot (<clientId>.<geheimnis>) pontosan egyszer tartalmazza; a DiKAS csak egy hash-értéket tárol. Megújítás: POST …/integration-clients/<clientId>/rotate-key (a régi kulcs azonnal érvényét veszti, nincs átmeneti időszak). Letiltás: PUT …/integration-clients/<clientId>/blocked a {"blocked":true} tartalommal. A kulcs egy jelszótárba való, soha nem naplóba vagy ügyfélszolgálati e-mailbe.

Az integrációs API hívásai az Authorization: Bearer <schluessel> vagy az X-Api-Key fejlécet használják. Hozzáférésenként percenként 600 hívás engedélyezett (utána 429 és Retry-After). A hozzáférés csak a számára engedélyezett üzleteket látja; idegen üzletek, zárolások vagy folyamatok esetén a válasz „ismeretlen“ (404), nem „tiltott“. Ha egy üzlet kilép a láncból, ez a következő kérésnél érvényesül.

Egy beváltás menete¶

Lépés	Hívás (mind a `/api/v1/integrations/vouchers` alatt)	Cél
1	`POST /lookup`	Utalvány ellenőrzése; a válasz csak maszkolt számot tartalmaz (`***001X`)
2	`POST /reservations`	Összeg zárolása 15 percre (`amountMinor` a legkisebb egységben, `currency`, `branchId`)
3	`POST /reservations/{id}/prepare`	Bizonylat bejelentése (`receiptReference`); innentől a zárolás már nem jár le
4	`POST /reservations/{id}/commit`	Beváltás megerősítése; ugyanazt a bizonylatot kell megneveznie, különben `409 RECEIPT_MISMATCH`
–	`POST /reservations/{id}/release`	Zárolás feloldása, ha a bizonylat sosem jön létre
5	`POST /refunds`	Visszatérítés az `originalTransactionId` alapján, rész- vagy teljes összeggel, kötelező `reason` mezővel
–	`GET /changes?cursor=…`	Változások lekérése; lapozás a `nextCursor` segítségével

Minden író hívás tartalmaz egy Idempotency-Key és egy clientReference értéket. Ugyanaz a kulcs ugyanazzal a tartalommal az első végrehajtás eredményét adja vissza (tíz ismétlés egyszer könyvel); ugyanaz a kulcs eltérő tartalommal 409 IDEMPOTENCY_CONFLICT hibával elutasításra kerül, mielőtt bármi könyvelődne. Ha csak teljes egészében vagy egyáltalán nem szeretne beváltani, állítsa az allowPartial értékét false-ra (különben annyi könyvelődik, amennyi rendelkezésre áll).

Elveszett a válasz? Ha egy hívás válasz nélkül vagy bizonytalan kimenettel ér véget, a DiKAS 202 státusszal, unknown állapottal és egy operationId azonosítóval válaszol. Ilyenkor ne könyveljen újra, hanem kérdezze le a folyamatot: GET /operations/by-reference/{clientReference} vagy GET /operations/{operationId}. A lekérdezés a könyvelési naplóból tisztázza, hogy a könyvelés megtörtént-e, és ugyanazt a tranzakcióazonosítót adja vissza, mint az eredeti válasz.

Nem képes erre a szolgáltató? A GET /programs jelzi a képességeket. Ha hiányzik a zárolás, az idempotens írás vagy a folyamatlekérdezés, ott paidWriteAllowed=false szerepel, és minden író hívás még a végrehajtás előtt 422 PROVIDER_UNSUPPORTED hibával ér véget. A fizetett könyvelések ilyenkor szándékosan le vannak tiltva.

Változások lekérése¶

A GET /changes a származtatott könyveléseket abban a sorrendben adja vissza, ahogyan a DiKAS megerősítette őket (nem időpont szerint), egy kurzorral együtt. Ugyanaz a kurzor mindig ugyanazokat az eseményeket adja; a később származtatott könyvelések a már beolvasott kurzor mögött jelennek meg, tehát nem vesznek el. Ha egy kurzor túl régi, a DiKAS 410 CURSOR_EXPIRED választ ad, és Önnek újra be kell olvasnia az állományt. A zárolások nem jelennek meg a feedben, csak a megerősített könyvelések. Saját webhook még nincs; kérje le rendszeresen a változásokat.

Fontos hibakódok¶

Kód	Jelentés
`INSUFFICIENT_SCOPE` (403)	A hozzáférésnek nincs jogosultsága ehhez a híváshoz
`BRANCH_UNKNOWN`, `PROGRAM_UNKNOWN`, `RESERVATION_UNKNOWN`, `TRANSACTION_UNKNOWN`, `OPERATION_NOT_FOUND` (404)	Nem létezik, vagy ez a hozzáférés nem láthatja
`IDEMPOTENCY_CONFLICT` (409)	Ugyanaz a kulcs eltérő tartalommal
`RECEIPT_MISMATCH` (409)	A commit más bizonylatot nevez meg, mint a prepare
`REFUND_LIMIT_EXCEEDED` (422)	Több lett visszatérítve, mint amennyi be lett váltva
`REDEMPTION_PENDING` (409)	A beváltás még nyitott — előbb tisztázni kell
`VOUCHER_BLOCKED` (409), `VOUCHER_EXPIRED` (422)	Az utalvány érvénytelenítve / lejárt (visszatérítés a láncszabálytól függően)
`VOUCHER_NOT_ACCEPTED` (422)	Egycélú utalvány, ennél a jogalanynál nem váltható be (csak a zárolásnál derül ki, az ellenőrzésnél nem)
`CURRENCY_MISMATCH`	A pénznem eltér; átváltás nem történik
`PROVIDER_UNSUPPORTED` (422)	A szolgáltató nem tudja biztonságosan a funkciót
`RATE_LIMITED` (429), `CLIENT_BLOCKED`, `INVALID_CREDENTIALS` (401)	A hozzáférés korlátozva, letiltva, vagy a kulcs hibás

A géppel olvasható leírás gutschein-gateway-v1.yaml OpenAPI-fájlként áll rendelkezésre; DiKAS-kapcsolattartójától kaphatja meg. Az interfész (még) nem része az általános API-referenciának.

Több szerverpéldány

A mennyiségkorlátozás és a változásfeed szerverfolyamatonként működik. A láncot továbbra is egy szerverrel üzemeltesse; ugyanazon adatbázis több egyidejű példánya nem támogatott.

Párhuzamos üzem előkészítése egy másik szoftverrel¶

Tartós üzemhez nem elég egy közös exportmappa. Mindkét pénztárnak ugyanahhoz a kötelező érvényű állományhoz kell hozzáférnie ugyanarra a kártyára. Egy egyszerű „még 50 €“ lekérdezés, majd egy későbbi „most 20 €“ visszaírás nem akadályozza meg az egyidejű második beváltást.

A beállítás előtt tisztázza a szolgáltatóval:

Melyik rendszer vezeti az egyenleget? Mely üzletek és jogalanyok válthatnak be?
Képes-e a szolgáltató összegeket kötelező érvénnyel zárolni, megerősíteni és megszakítás esetén feloldani?
Felismeri-e ugyanazon folyamatként az azonos folyamathivatkozással ismételt könyvelést?
Lekérdezhető-e egy kapcsolatmegszakadás után, hogy pontosan ez a könyvelés sikeres volt-e?
Hogyan működnek a teljes és a részleges visszatérítések, az elszámolást is beleértve?
Milyen adatok kérhetők le, és hogyan van meghatározva a pénznem, az állapot, a régi számok és az időpontok?

Ha egy szolgáltató csak fájlokat tud exportálni, az átvételre vagy jelentéshez alkalmas. Biztonságos, egyidejű fizetési üzem ebből nem vezethető le. A közös beállításhoz az exportpéldát és a meglévő API leírását az egyeztetett úton bocsássa a DiKAS ügyfélszolgálat rendelkezésére.

Hiba vagy bizonytalan lezárás¶

Még nincs bizonylat: Kapcsolat hiányában válasszon másik fizetési módot.
Bizonylat vagy terhelés esetleg már létezik: Ne indítson új könyvelést új hivatkozással. Előbb ellenőriztesse a bizonylatot és az utalvány állását az adott konkrét folyamat alapján; az aktuális maradványérték önmagában nem bizonyítja, hogy több könyvelés közül melyik hajtódott végre.
Sztornó: DiKAS-pénztárnál a nyugtasztornó automatikusan visszatéríti a megerősített láncutalvány-beváltást (ellenkönyvelés ugyanarra az utalványra, lásd Visszatérítés nyugtasztornónál). Külső rendszer esetén a visszatérítés az integrációs API visszatérítési hívásán keresztül történik, a beváltás tranzakcióazonosítójával; egy érvénytelenítés ezt nem helyettesíti.
Egyeztetés: A darabszámot, a nyitott maradványértékeket és a mozgásokat pénznem és kibocsátó szerint elkülönítve vesse össze. Egy CSV-export nem kifizetés.

A tisztázáshoz elsőként elegendő az üzlet, a folyamat- vagy bizonylathivatkozás, az összeg, az időpont és a maszkolt utalványhivatkozás. A hozzáférési kulcsokat és a teljes kódokat ne küldje el védtelen naplókban vagy nyilvános üzenetekben.