NAV Online Számla integráció saját rendszerbe: fejlesztői útmutató

Ha a céged saját rendszerből számláz, például webshopból, vállalatirányítási rendszerből vagy egyedi ügyviteli szoftverből, akkor a számlaadatokat valós időben be kell küldenie a NAV Online Számla rendszerébe. 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, neked legfeljebb az ő API-jukra kell kötnöd a rendszeredet, ami nagyságrendekkel egyszerűbb feladat. Közvetlen NAV-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 NAV a github.com/nav-gov-hu/Online-Invoice repóban publikálja a specifikációt és a változásokat, érdemes követni). 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álunk 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 érdemes végigpróbálni a teljes életciklust: normál számla, módosító számla, sztornó, valamint a hibaágakat is, például érvénytelen adószámmal vagy sémahibás XML-lel.

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.

Hogyan segítünk?

A Milcomp Laravel-alapú rendszerekhez épít 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 cikkünket, a szabályozási képhez pedig az e-számla 2026 útmutatónkat. 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.