Az elmúlt években több rendszert kötöttem be a NAV Online Számla API-jára, webshopot és vállalatirányítási rendszert is, és minden alkalommal ugyanazokon a pontokon ment el a legtöbb idő. Ez az útmutató azt mutatja meg, mit jelent ez az integráció a gyakorlatban: mire számíts fejlesztőként, és mit kérdezz meg megrendelőként, mielőtt belevágsz.

Először: biztos, hogy neked kell integrálnod?

Ha kész számlázó szolgáltatást használsz (Számlázz.hu, Billingo és társaik), az adatszolgáltatást ők intézik, és a közvetlen NAV-integrációt megfizetni nem éri meg: neked legfeljebb az ő API-jukra kell kötnöd a rendszeredet, ami nagyságrendekkel egyszerűbb feladat. Közvetlen integrációra akkor van szükséged, ha a számlát ténylegesen a saját szoftvered állítja ki. Ilyenkor a felelősség is a tiéd: a hiányzó vagy hibás adatszolgáltatás számlánként akár 1 millió forintos mulasztási bírságot hozhat, ezért ezt a modult nem "majd egyszer letudjuk" alapon érdemes megírni.

Az API dióhéjban

Az aktuális interfész a 3.0-s séma. A specifikációt és a változásokat a NAV a nav-gov-hu/Online-Invoice GitHub-repóban publikálja; ezt én bekötöttem a saját értesítéseim közé, és neked is ezt javaslom, mert a változások onnan tudhatók meg először. A működés lényege:

  • A cég adószámához a NAV Online Számla felületén technikai felhasználót hozol létre, ehhez tartozik egy aláírókulcs és egy cserekulcs.
  • Minden kérést kriptográfiai aláírással hitelesítesz, és munkamenetenként tokent cserélsz, amelyet a cserekulccsal fejtesz vissza.
  • A számlaadatot a séma szerinti XML-ben, base64-ben csomagolva küldöd be a manageInvoice művelettel.
  • A feldolgozás aszinkron: a beküldésre tranzakcióazonosítót kapsz, majd külön kérdezed le, hogy a NAV elfogadta-e (queryTransactionStatus), és az esetleges figyelmeztetéseket is ott kapod vissza.

Architektúra, ami éles üzemben is megállja a helyét

A leggyakoribb tervezési hiba, hogy a beküldés szinkron módon, a számlakiállítás folyamatába ékelve történik. A NAV rendszere időnként lassú vagy karbantartás alatt áll, és ilyenkor nem eshet szét a saját számlázásod. Ami nálam éles rendszerekben bevált:

  • Sorba állítás (queue): a számla kiállítása azonnal lezárul, az adatszolgáltatás háttérfolyamatként, automatikus újrapróbálkozással fut.
  • Állapotgép számlánként: beküldve, feldolgozás alatt, elfogadva, figyelmeztetéssel elfogadva, hibás; minden átmenet naplózva.
  • Idempotencia: egy számla soha nem mehet be kétszer, újrapróbálkozásnál sem.
  • Riasztás: ha egy számla státusza adott időn belül nem jut elfogadott állapotba, arról a fejlesztő és az ügyvitel is értesül, még a határidőn belül.

Tesztelés

A NAV külön tesztkörnyezetet ad (api-test), ahová teszt technikai felhasználóval küldhetsz be adatot éles következmények nélkül. Éles indulás előtt próbáld végig a teljes életciklust: normál számla, módosító számla, sztornó, és a hibaágakat is, például érvénytelen adószámmal vagy sémahibás XML-lel. Én egy dolgot tanultam meg a saját káromon: a tesztkörnyezet elfogad olyan eseteket is, amiket az éles validáció már figyelmeztetéssel jelez, ezért az első éles hetekben a figyelmeztetéseket is nézni kell, nem csak a hibákat.

Gyakori buktatók

  • Időkezelés: az API UTC-ben gondolkodik, a magyar helyi idővel keverve klasszikus hibaforrás.
  • Módosító és sztornó láncok: a módosító számlának pontosan hivatkoznia kell az eredetire; ha a rendszered a számlaláncot nem modellezi rendesen, itt fog kiderülni.
  • Kerekítések: az áfa-összegek tételenkénti és összesítő szintű egyezését a NAV ellenőrzi, a lebegőpontos kerekítési hibák figyelmeztetésként jönnek vissza.
  • Verziókövetés: a séma és a validációk időről időre változnak; az integráció nem "kész és felejtsd el" típusú modul, karbantartani kell.

Mennyi munka ez valójában?

Őszintén: egy egyszerű, csak kimenő számlás integráció kész könyvtárakra építve néhány fejlesztői hét. A teljes kép, tehát módosító és sztornó láncok, riportok, riasztások és üzemeltetési felület, ennek a többszöröse. PHP/Laravel környezetben léteznek jó nyílt forráskódú kliensek, amelyek az aláírás- és tokenkezelést leveszik a válladról; ezekre építeni szinte mindig jobb döntés, mint nulláról írni a kriptográfiai réteget. Árat itt szándékosan nem írok, mert a valós munkaigényt a számlázási folyamatod dönti el, nem az API.

Hogyan segítek?

Egyedi rendszerekhez építünk NAV-integrációt és teljes számlázási automatizálást, a német entsorgo platformon pedig a bejövő oldalt is automatizáltuk: ott mesterséges intelligencia dolgozza fel a partnerszámlákat. Ha a kimenő adatszolgáltatás és a bejövő számlák feldolgozása is témád, olvasd el az AI számlafeldolgozás cikkemet, a szabályozási képhez pedig az e-számla 2026 útmutatót. Konkrét projekthez kérj ajánlatot: első lépésként felmérjük, kész könyvtárral vagy egyedi modullal jársz-e jobban. :)