Számlázó NAV bekötés: API-kulcsok és tesztelés egyszerűen

A NAV Online Számla bekötése sok vállalkozásnál azért csúszik el, mert a „beállítás” alatt mindenki mást ért. A könyvelő a jogosultságokra gondol, a fejlesztő az API végpontokra, a vállalkozó pedig arra, hogy „menjen át a számla a NAV-hoz”. Ebben a cikkben kifejezetten az API-kulcsok (technikai felhasználó, aláírókulcs, cserekulcs) és a tesztelés oldaláról mutatom meg, hogyan lehet a számlázó NAV bekötést gyorsan és biztonságosan végigvinni.

Kinek szól ez az útmutató?

• Kisvállalkozóknak, akik számlázóprogramot kötnek be a NAV-hoz, és szeretnék érteni, milyen adatokat kér a rendszer.

• Könyvelőknek, akik több ügyfél NAV bekötését segítik, és standardizálni akarják a folyamatot.

• Fejlesztőknek és integrátoroknak, akik API-szinten tesztelnek, és hibabiztos átadást szeretnének.

Ha a NAV Online Számla alap beállításait és a tipikus hibákat keresed (portál lépések, hibakódok), arra általában külön, részletes beállítási útmutatók valók. Itt most a kulcskezelés, környezetek és tesztelés a fókusz.

Mit jelent a „számlázó NAV bekötés” API-szinten?

A NAV Online Számla adatszolgáltatás lényege, hogy a számlázó (vagy a mögötte futó integráció) gépileg beküldi a számla adatait a NAV rendszerébe. Ehhez a NAV a hozzáférést technikai felhasználóhoz és API-kulcsokhoz köti.

A gyakorlatban az alábbi elemekkel találkozol:

• Felhasználói jogosultságok a NAV Online Számla felületén (ki hozhat létre technikai felhasználót, ki adhat jogot adatszolgáltatásra).

• Technikai felhasználó (nem „emberi” belépésre, hanem API hívásokhoz).

• Kulcsok (aláírás, csere, gyakran külön kezelve a titkos értékeket).

• Környezetek (éles és teszt, eltérő végpontokkal és külön azonosítókkal).

A cél: úgy beállítani mindezt, hogy a számlaadatok beküldése stabil legyen, és a tesztelés során már előjöjjenek a tipikus „élesben fájó” hibák.

0. lépés: döntsd el, milyen bekötési módot használsz

A kulcsok kezelése attól függ, hogyan csatlakozol a NAV-hoz:

• Számlázóprogramon keresztül: a legtöbb kisvállalkozás így csinálja. Ilyenkor a szoftverben adod meg a NAV-os technikai felhasználó adatait és kulcsait, a rendszer pedig intézi a beküldést.

• Saját integrációval (API közvetlen): jellemző webshopoknál, egyedi ERP-nél, vagy ha több rendszerből keletkezik számla.

A cikk mindkét esetben segít, mert a NAV oldali kulcsok ugyanazok, csak a megadás helye más.

1. lépés: a NAV-os szerepkörök és jogosultságok tisztázása

Mielőtt kulcsokat generálsz, érdemes egyértelműsíteni:

• Ki a NAV Online Számla rendszerben a fő admin, aki jogosultságot tud adni.

• Melyik adószámhoz (és esetleg több adószámhoz) kell bekötés.

• Van-e olyan külsős (könyvelő, integrátor), akinek hozzáférés kell, és milyen szinten.

Tipp: ha több cég fut egy fiókban (pl. holding, több Kft.), akkor már itt érdemes leírni egy mini szabályt, például „cégenként külön technikai felhasználó” vagy „egy technikai felhasználó, cégenként külön jogosultság”. Mindkettő működhet, a lényeg a következetesség és a visszakereshetőség.

2. lépés: technikai felhasználó és API-kulcsok, mit jelentenek valójában?

A NAV-nál az API hozzáférés kulcsa a technikai felhasználó, akihez több biztonsági elem tartozik. Ezeket tipikusan a számlázóprogram vagy az integráció kérni fogja.

Az alábbi táblázat segít rendbe tenni a fogalmakat.

Megjegyzés: a NAV pontos mezőnevei és követelményei verziótól és dokumentációtól függhetnek. Ha fejlesztesz, mindig a NAV hivatalos Online Számla technikai dokumentációját használd kiindulópontnak a nav.gov.hu felületén.

3. lépés: kulcskezelés biztonságosan, hogy ne az éles nap legyen a tűzoltás

A NAV kulcsokkal kapcsolatos problémák ritkán „látványosak”, inkább alattomosak: egy félrenyelt szóköz, egy rossz helyre mentett jelszó, egy régi kulcs, és a beküldés elkezd szórványosan hibázni.

A bevált gyakorlatok (akkor is, ha nem fejlesztő vagy):

• Egy helyen tárold a kulcsokat, biztonságosan (jelszókezelő, titkosított vállalati jegyzet, hozzáférés naplózással).

• Ne küldd el e-mailben sima szövegként a teljes kulcskészletet. Ha muszáj átadni, legyen időkorlátos, és utána rotáljátok.

• Ne keverd a teszt és éles adatokat: külön mappa, külön jelölés, külön felelős.

• Rotációs szabály: ha külsős kapott hozzáférést, vagy emberi hiba történt, azonnal kulcscsere.

Ha számlázóprogramot használsz, akkor a legfontosabb, hogy a kulcsokat pontosan másold be, és legyen egy dokumentált folyamat, ki, mikor, milyen céghez állította be.

4. lépés: tesztelés, mit érdemes ellenőrizni az első „sikeres” beküldésen túl?

Sok bekötés ott bukik meg, hogy van egy sikeres próbaküldés, majd élesben jönnek a valós élethez tartozó kivételek: sztornó, helyesbítés, deviza, előleg, több tétel, vevő adószám ellenőrzés, vagy csak egy rossz karakter a névben.

A minimális, de profi tesztcsomag

Ha a cél a stabil működés (nem csak a „zöld pipa”), akkor legalább az alábbi eseteket érdemes lefedni:

• Normál számla belföldi adóalanynak

• Normál számla magánszemélynek (ha releváns)

• Sztornó vagy módosító okirat (ha a folyamatod használja)

• Devizás számla (ha előfordul)

• Több tételes számla, hosszabb megnevezésekkel

Mit nézz a NAV visszajelzésben?

Nem csak az számít, hogy „befogadta”, hanem az is, hogy milyen minőségben:

• Van-e warning (figyelmeztetés), ami később problémát okozhat (adatminőség, kerekítés, partneradat)

• Megjelenik-e a számla a NAV felületen úgy, ahogy várod (dátumok, összegek, adókulcs)

• A számlázódban vagy integrációdban el van-e mentve a NAV válasz azonosítója (tranzakció, request azonosító), hogy visszakereshető legyen

Tesztkörnyezet vagy éles?

Fejlesztői bekötésnél jellemzően van tesztelési lehetőség külön végponttal. Számlázóprogram használatakor sokszor az éles környezetben, de „óvatos” valódi számlákkal tesztelnek (például belső, alacsony értékű tranzakció). Hogy melyik a megfelelő, azt a saját folyamataid és a NAV keretrendszere dönti el.

A lényeg: ne az első éles ügyfélszámla legyen az integráció tesztje.

5. lépés: tipikus API-kulcsos és tesztelési buktatók (és gyors diagnózis)

A következő hibák gyakran nem „NAV leállás” jellegűek, hanem konfigurációs problémák.

Rossz környezet, rossz kulcs

Tünet: egyik nap működik, másnap nem, vagy teszten jó volt, élesen azonnal elhasal.

Gyors ellenőrzés:

• biztosan az éles technikai felhasználó adatai vannak beírva?

• nem keveredett-e be egy régi jelszó?

Kulcs bemásolási hiba

Tünet: állandó hitelesítési hiba, miközben a felhasználónév és jelszó „biztos jó”.

Gyors ellenőrzés:

• nincs-e extra szóköz a kulcs elején vagy végén

• nem cserélted-e fel az aláírókulcsot és cserekulcsot

Időszinkron probléma (integráció esetén)

Tünet: időbélyeghez kötődő hibák, főleg szerveres integrációnál.

Gyors ellenőrzés:

• szerver időszinkron (NTP)

• időzóna beállítás

„Sikeres beküldés”, de a könyvelő mégsem látja rendben

Tünet: technikailag oké, de a NAV felületen a tartalom hiányosnak tűnik, vagy az üzleti logika szerint „nem stimmel”.

Gyors ellenőrzés:

• a beküldött számla adatszerkezete megfelel-e annak, amit ténylegesen kiállítottál

• helyesek-e a dátumok (kiállítás, teljesítés)

Több cég, több felhasználó: így marad átlátható a bekötés

Ha egyszerre több céget kezelsz (például Kontozz jellegű többcéges működésben), az átláthatóság a legnagyobb nyereség. Ilyenkor az API-kulcsokhoz érdemes hozzárendelni:

• cégnév

• adószám

• kulcs létrehozás dátuma

• felelős (ki állította be)

• használt környezet (éles vagy teszt)

Ebből akár egy egyszerű belső nyilvántartás is elég, nem kell túladminisztrálni. A cél, hogy 6 hónap múlva is 2 perc legyen megmondani, mi hova tartozik.

Ha nem saját fejlesztés, hanem számlázóprogram: mit kérj a szolgáltatótól?

Egy online számlázó (például a Kontozz) jellemzően elvégzi helyetted a NAV kommunikáció technikai részét, neked pedig a technikai felhasználó és kulcsok megadása marad. Ilyenkor a bevezetésnél az segít a legtöbbet, ha a szolgáltatótól egyértelmű választ kapsz ezekre:

• pontosan milyen mezőket kell kitölteni (felhasználónév, jelszó, kulcsok)

• van-e beépített státusz vagy visszaigazolás, amiből látszik, hogy a beküldés rendben megtörtént

• hova fordulj, ha a NAV válasz alapján további teendő van

A jó ügyféltámogatás itt nem extra, hanem kockázatcsökkentés, mert egy kulcs hibáját a legtöbb vállalkozó nem szeretné „API logból” kibogarászni.

Kitekintés: ha nem csak NAV, hanem külföldi adóadmin is van

Magyar fókusz mellett előfordul, hogy egy vállalkozás külföldön is érintett speciális bevallásokban. Például az USA-ban bizonyos jövedéki jellegű adókhoz kapcsolódóan léteznek dedikált online megoldások, mint a Form 720 online benyújtására szolgáló IRS-approved szolgáltatás. A tanulság közös: akár NAV, akár külföldi hatóság, a siker kulcsa a hozzáférések, azonosítók és tesztelés fegyelmezett kezelése.

Gyors ellenőrzőlista indulás előtt

Nem „mindenre kiterjedő”, inkább a leggyakoribb csúszások ellen:

• A technikai felhasználóhoz tényleg megvan a szükséges jogosultság az adott adószámhoz

• A kulcsok és jelszó éles vagy teszt környezet szerint helyesen vannak megadva

• Van legalább 2-3 lefuttatott teszteset (nem csak 1 darab minta számla)

• A NAV válasz azonosítók visszakereshetők (tranzakció, státusz)

Gyakran Ismételt Kérdések (FAQ)

Mi az a technikai felhasználó a NAV Online Számla rendszerben? A technikai felhasználó egy olyan hozzáférés, amit nem emberi belépésre, hanem API kommunikációra hozol létre. Ehhez tartoznak az API-kulcsok is.

Kell külön technikai felhasználó minden céghez? Nem mindig kötelező, de sok szervezetnél átláthatóbb és biztonságosabb a cégenkénti szétválasztás. A döntést a belső folyamatok és jogosultságkezelés alapján érdemes meghozni.

Miért nem elég egyetlen sikeres teszt számla? Mert élesben jönnek a kivételek (módosítás, deviza, több tétel, speciális adatok). A stabil integrációhoz több, valós helyzetet modellező teszteset kell.

Mit tegyek, ha a NAV hibát jelez, de a számlázóban „kiment” a számla? Kérd el vagy keresd meg a NAV válasz azonosítóit (tranzakció, request azonosító), majd ellenőrizd a NAV felületen a státuszt. Ha kell, vond be a könyvelőt vagy a számlázó supportját.

Biztonságos e-mailben elküldeni a NAV API-kulcsokat a fejlesztőnek? Nem ideális. Jobb jelszókezelőt vagy titkosított megosztást használni, és átadás után kulcsrotációt bevezetni, ha külsős is hozzáfért.

Következő lépés: egyszerűbb NAV bekötés kevesebb hibával

Ha a célod az, hogy a NAV adatszolgáltatás ne egy egyszeri projekt legyen, hanem stabil, napi szinten megbízható folyamat, akkor érdemes olyan számlázót választani, ahol a több cég kezelése, a csapatjogok, az automatizmusok és a riportok egy helyen elérhetők.

A Kontozz kisvállalkozásoknak készült online számlázó és üzletmenedzsment platform, ahol egy felhasználóbarát fiókból kezelheted a cégeidet, a csapatod jogosultságait és a számlázási adminisztrációt. Nézd meg a lehetőségeket a Kontozz oldalán, és ha elakadsz a NAV kulcsokkal vagy teszteléssel, kérj segítséget a támogatástól, hogy a bekötés gyorsan és tisztán menjen végig.