NTAK TSS Adatszolgáltatás

Az NTAK (Nemzeti Turisztikai Adatszolgáltató Központ) TSS interfész a turisztikai szolgáltatók napi értékesítési adatainak állami jelentésére szolgál. A Bookinda integrálva van vele, így a megfelelő ügyfeleknek automatikus az adatszolgáltatás.

Kiket érint az adatszolgáltatás?

NTAK Attrakció TSS regisztráció kötelező a következő szolgáltatóknak:

• Fürdők (gyógy- / termál- / élményfürdő)
• Wellness és spa-központok (önálló, nem szállodai)
• Múzeumok, kiállítások, állatkertek
• Sportlétesítmények belépőjegyes szolgáltatása
• Tematikus parkok, attrakciók
• Egyéb belépőjegyes turisztikai szolgáltatások

Nem érintett: szalonok, fodrászatok, kozmetikák, masszázs, szépségápolás. Hotel-spa: a szállodai PMS (pl. Hostware) kezeli az NTAK-jelentést, NEM a Bookinda.

A beállítás két szintje

A Bookinda a beállításokat két szinten tárolja, hogy minden szolgáltatónak csak a saját adatait kelljen megadnia:

Platform-szintű (a Bookinda Super Admin kezeli)

• TSS rendszer NTAK azonosító: BOOKINDA: ezt egyszer kapta meg a Bookinda az NTAK-tól, minden tenantra ugyanaz
• TSS rendszer verziószám: 1.0
• NTAK endpoint URL: teszt (https://tss.tesztntak.hu) vagy éles (https://tss.ntak.hu)
• Tesztkörnyezet kapcsoló: globális teszt/éles váltó

A tenant manager felületén ezek read-only banneren jelennek meg, nem kell módosítani.

Tenant-szintű (a manager kezeli a saját felületén)

• NTAK regisztrációs szám (pl. MK26004239): pontosan 10 karakter
• Cég adószáma (pl. 11223344-1-22): kötőjelek mehetnek, a rendszer automatikusan eltávolítja
• Helyszín neve és irányítószáma
• Tanúsítvány fájlok elérési útja (cert + privát kulcs)

Hogyan állítsd be? (manager szerepkörben)

1. NTAK regisztráció (külső)

1. Lépj be az NTAK portál felületére
2. Add hozzá szolgáltatási helyedet, kapsz egy NTAK regisztrációs számot (pl. MK26004239)
3. Igényelj fejlesztői csatlakozást a TSS interfészhez a info.ntak.hu/szoftvergyartok oldalon
4. NTAK kiállítja a tanúsítványodat, ezt kell hitelesen küldeni az adatokhoz
5. Példa eset (Le Primore Spa): AMSK Global Kft.-ként regisztráltunk, kaptunk MK26004239 szolgáltatási hely-számot, és 2026 májusában érkezett meg a teszt cert.

2. Bookinda beállítás

A Beállítások → NTAK adatszolgáltatás menüpontban:

1. Kapcsold be a "NTAK adatszolgáltatás engedélyezése" toggle-t
2. Add meg az adatokat:
   • NTAK regisztrációs szám
   • Cég adószáma
   • Helyszín neve és irányítószáma
3. Másold a támogatás által küldött tanúsítvány fájlokat a szerverre (cert + private key)
4. Add meg a fájlok elérési útját
5. Kattints a "Tanúsítvány tesztelése" gombra, ha minden OK, megjelenik a zöld pipa

3. NTAK programok létrehozása

A Beállítások → NTAK adatszolgáltatás → Programok oldalon:

1. Hozz létre egy programot minden NTAK-jelentésre köteles szolgáltatáshoz (pl. "Wellness belépő")
2. Válaszd ki a kapcsolódó Bookinda szolgáltatást a dropdown-ból
3. Add meg az NTAK kategóriákat:
   • Főkategória: pl. KOZFURDO, MUZEUM_VAR_KASTELY, KALANDPARK (összesen 9 érték)
   • Alkategória: pl. WELLNESS_PROGRAM, FURDO_PROGRAM, STRAND_PROGRAM (összesen 30 érték)
   • Típus: önálló / kombinált / programsorozat része
   • Gyakoriság: állandó / időszakos / egyszeri

Fontos: csak akkor megy ki NTAK-jelentés, ha a Bookinda szolgáltatás összerendelve van egy NTAK programmal.

4. Validációs tesztek (élesítés előtt)

Mielőtt aktiválod az éles környezetet, le kell futtatnod a 11 NTAK-validációs forgatókönyvet:

1. Menj a NTAK adatszolgáltatás → Validációs tesztek oldalra
2. Válassz egy tesztprogramot
3. Futtasd a teszteket sorban (legalább a "kötelező" jelölésűeket: F_01A, F_01B, F_01C)
4. A futtatott tranzakciók látszanak a Tranzakciók oldalon, kezdetben "Feldolgozás alatt" státuszban
5. ~5 perc múlva a státusz cron lekérdezi az NTAK-tól a feldolgozási eredményt, TELJESEN_SIKERES jelenik meg ha minden OK
6. Mentsd le a feldolgozási azonosítókat az NTAK validációs jegyzőkönyvbe és küldd be élesítési kérelemmel

Bookinda tapasztalat: a v5.04-ben (2026-05-04) mind a 15 validációs teszt zöld: ez a referencia, hogy a rendszer NTAK-konform.

5. Élesítés (Super Admin teendő)

1. NTAK visszaigazolja az élesítési kérelmet
2. A Super Admin a /superadmin/ntak-tss oldalon átállítja az endpoint-ot https://tss.ntak.hu-ra
3. A "Tesztkörnyezet" kapcsolót kikapcsolja
4. Mostantól minden értékesítés az ÉLES NTAK rendszerbe megy

Hogyan működik napi szinten?

Ha minden be van állítva:

1. Az ügyfél vásárol egy NTAK-jelentésköteles szolgáltatást (pl. wellness belépő)
2. A pénztárnál kifizeted (Sale → PAID)
3. A Bookinda automatikusan elküld egy NTAK értékesítési üzenetet a háttérben
4. Az NTAK feldolgozza, visszaad egy feldolgozási azonosítót
5. 5 percenként a státusz cron lekérdezi a feldolgozás eredményét
6. 15 percenként a retry cron újraküldi a hibára futott üzeneteket

A Tranzakciók oldalon mindig látod az aktuális státuszt:

• 🟡 Feldolgozás alatt: elküldve, várjuk az NTAK választ
• 🟢 Elfogadva (TELJESEN_SIKERES): sikeres jelentés
• 🔴 Hiba (TELJESEN_HIBAS): NTAK elutasította (hibaüzenet látszik)
• 🟠 Újraküldésre vár: automatikus retry (max 5x)

Vendég-adatok

Az NTAK megköveteli a vendég lakóhelyét (irányítószám belföldi esetén, ország-kód külföldi esetén). A Bookinda az ügyfél (Customer) profiljából olvassa ki:

• Belföldi vendég: irányítószám
• Külföldi vendég: ország ISO-2 kódja (pl. DE, AT, CA)

Ezeket a foglalásnál vagy a profil-szerkesztőben add meg.

ÁFA, korcsoport, jegytípus mapping

A Bookinda automatikusan átalakítja az NTAK által várt enum-okra:

ÁFA: szolgáltatás VAT-rate → NTAK kategória

• 27% → C_27
• 18% → B_18
• 5% → A_5
• 0% → E_0

Korcsoport: alapértelmezetten FELNOTT: a service-variánsok alapján: GYEREK, DIAK, NYUGDIJAS, IDOS, VEGYES. (Figyelem: NTAK GYEREK, NEM GYERMEK!)

Jegytípus: alapértelmezetten NAPI_JEGY. Egyéb értékek: EGYSZERI, HETI_JEGY, HAVI_JEGY, NEGYEDEVES, FELEVES, EVES, EGYEB.

Fizetési mód: KESZPENZHUF, KESZPENZEUR, BANKKARTYA, SZEPKARTYA, ATUTALAS, VOUCHER, SZOBAHITEL, KEREKITES, EGYEB.

Értékesítési csatorna: ONLINE, AUTOMATA, HELYSZINI, UTAZASI_IRODAN_KERESZTULI.

Hibaelhárítás

"Tanúsítvány nem érvényes": ellenőrizd a fájl elérési utakat és jogosultságokat (chmod 600 *.key). A privát kulcs SOHA ne hagyja el a szervert.

"NTAK rejected request (400)": nézd meg a hibaüzenetet a Tranzakciók oldalon. Tipikus okok:

• Hibás regisztrációs szám: pontosan 10 karakter kell, pl. MK26004239 (8 karakter elutasításra kerül Size hibával)
• Hibás adószám: pontosan 11 számjegy kell, a Bookinda automatikusan eltávolítja a kötőjeleket, így 11223344-1-22 és 11223344122 is rendben van
• utolsoModositasIdeje jövőbeli: az NTAK NEM fogad el jövőbeli időpontot, ne állíts órát előre
• Lejárt tanúsítvány: a teszt cert 2 év érvényességű
• Kötelező mező hiányzik: pl. egyebTetelek-nél hiányzó afaKategoria (a Bookinda C_27-tel pótolja)
• programAlkategoria ENUM hiba: a régi enum-értékeket (pl. WELLNESS) az NTAK 2024 óta nem fogadja, csak a hivatalos OpenAPI spec-ben szereplőeket (WELLNESS_PROGRAM)

Tranzakció PENDING marad túl sokáig: ellenőrizd a státusz polling cron működését, vagy használd a "Re-poll" gombot a tranzakció soron.

Tipp az F_01A teszt során: ha pontosan az NTAK doksiban szereplő 1012 Ft értéket küldöd, "Conflict" hibát kaphatsz a TESZT környezetben (más tesztrekordokkal ütközhet). Használj egy enyhén eltérő összeget (pl. 1015 Ft): éles környezetben ez nem probléma.

Hivatkozások

• NTAK fejlesztői doksi: info.ntak.hu/szoftvergyartok
• TSS specifikáció PDF: TSS_Interfesz_leiras_v104
• OpenAPI spec teszt környezetben: https://tss.tesztntak.hu/v3/api-docs (ennek alapján van minden enum-érték a Bookindában)
• NTAK ügyfélszolgálat: [email protected], +36-1-58-58-326
• Bookinda jegyszám az NTAK-nál: 141109