A NAV Online Szamla v3.0 endpoint 2021 ota minden B2B-szamlanal kotelezo Magyarorszagon, es a kibocsatastol szamitva 5 percen belul fel kell tolteni. Ez nem egy 'ha lehetne' funkcio, hanem alap-megfeleloseg. A Netorigo Finance modulban ez a folyamat ket eve fut eles uzemben, es 2026 majusaban a havi forgalom 14,200 szamla volt, 99.94% elsoreszteges felteltesi sikeraranyal.
Mit ervintunk a NAV oldalrol
A v3.0 spec harom kulcsendpointot definial. Az elso a tokenExchange: minden 5 percenkent egy uj exchange token kerul kibocsatasra a tanusitvanyalapu hitelesitessel, amit a manageInvoice keresekhez hasznalunk. A masodik a manageInvoice maga, ami a szamla XML-t felveszi, sorszammal latja el (tranzakcio-azonosito) es elindul a feldolgozas. A harmadik a queryInvoiceData, amivel pollozzuk a NAV oldali allapotot, amig az DONE vagy ABORTED vegallapotot el nem eri.
Az alap kihivas: a NAV az XML-t aszinkron dolgozza fel. Kuldhetunk egy hibatlan szamlat, ami 4 masodperc mulva visszajon 'PROCESSING' statusszal, majd 30 masodperc mulva 'DONE'. Vagy 6 percig pislogasztal, mert a NAV-fal eppen torlodas van. A Netorigo egy outbox mintat hasznal, amelyik garantalja, hogy egyszer sem vesszuk el a feltoltest, meg ha a NAV API kozben 502-vel valaszol is.
A hat szamla-tipus
A NAV hat fo szamla-tipust kulonboztet meg: INVOICE (alapszamla), MODIFY (modositas, korabban sztorno + uj), BATCH_INVOICE (kotegelt), STORNO (kifejezetten torles), RECEIPT (penztargepi nyugta), OTHER (szakmai). A Netorigo modul mind a hat tipust kezeli; a 'MODIFY' a leggakoribb csapda, mert a hivatkozott eredeti szamla NAV-oldali transactionId-jat kell ismernunk. Egy nav_invoice_link tablat tartunk fenn, ami a belso szamla-PK-t es a NAV transactionId-t kapcsolja ossze.
A harom hibatipus
A NAV API harom kategoriaba sorolja a hibakat:
-
Validacios hiba (
SCHEMA_VALIDATION_ERROR,BUSINESS_VALIDATION_ERROR) — a szamla XML hibas. Ezeket azonnalfailedallapotba allitjuk es konyveloi figyelmet keruek. Pelda: hianyzo SZJ-kod fordított AFA-nal, vagy nem letezo vevoi adoszam. -
Halozati hiba (
502,503,504,TIMEOUT) — a NAV oldal nem elerheto. Ezekre az exponencialis backoff strategianktol foly: 30s, 1m, 2m, 4m, 8m, 16m... egeszen 24 oraig. 24 ora utan ember-flag. -
Ujraprobalas-ervinyes hiba (
INVOICE_NUMBER_NOT_UNIQUE,LOCKED) — atmeneti allapot. Egyszer probaljuk ujra 5 masodperc utan, ha meg mindig hibas, kategoria 1-be tesszuk.
A retry-szabaly
A worker (BullMQ-alapu) minden feltoltest egy job-kent kezel, es a hibakategoria szerint dont a retry stratagrol. A kategoria 1 (validacios) hibanal nincs retry — a konyvelo javit. A kategoria 2 (halozati) hibanal exponencialis backoff 24 oraig. A kategoria 3 (ujraprobalas-ervinyes) hibanal egyszeri 5 masodperces retry, majd kategoria 1.
14,200 majusi szamlabol 9 vegul ember-flag-et kapott (mind kategoria 1, mind valodi adoszam-elgepelaesi vagy hianyzo SZJ-kod miatt). A maradek 14,191 elsore vagy az automatikus retry-ban beerkezett a 'DONE' allapotba.
Mit nem teszunk
A modul nem irja felu a NAV-tol kapott transactionId-t. Soha. Ha a NAV egy szamlat 'DONE' allapotban regisztralt, az a NAV szamara hivatalos, es a Finance modul csak MODIFY vagy STORNO muvelettel valtoztathat rajta. Ez az audit-szabaly olcson eltunteti a 90%-at a megfelelosegi vitaknak.
A NAV integracio nem fizz-and-bang. Lassan, megbizhatoan, audit-szempontu fokusszal kell csinalni, es akkor 18 honapon at zero buntetes erkezik a partnerunkhoz.
A tanusitvany-kezelees
A NAV API tanusitvany-alapu hitelesitest hasznal: minden tenantnak egy sajat .p12 tanusitvanya van, amit a NAV regisztracios feluleten allitanak ki. A tanusitvany 2 evre szol, es a Netorigo modul automatikusan figyelmezteti a partnert 60 nappal a lejarat elott (e-mailben es admin-feluletben), 30 nappal pedig sirgossegi figyelmeztetest kuld. Egy lejart tanusitvany azonnal megaakasztja a NAV-feltoltest, igy a tanusitvany-megujitas tervezesi feladat, nem szukseghelyzeti.
A tanusitvany titkositott formaban tarolodik a tenant.nav_cert_encrypted mezoben, AES-256-GCM-mel, az alkalmazas-szintu kulcs (KMS-bol jovo) szerint. A tanusitvany sose hagyja el a backend folyamatot — a frontend admin felulet csak a metaadatokat (kiadasi datum, lejarat, kibocsato) lattja.
A monitorozas
A NAV-pipeline egy dedikalt Grafana-dashboardon latszik: a percenkenti feltoltes-szam, az atlagos NAV-validalasi latency, a hibakategoria-eloszlasa, a 24-orai retry-queue merete. Ez a dashboardot a SRE-team es a customer-success egyutt nezi, es egy 5%-os hibaarany-emelkedes a Slack-csatornaban automatikus alert-et general.