SÚGÓ › Számlázás

NAV Online Számla — automatikus integráció

Minden Stripe-on rendezett számla automatikusan beküldődik a NAV Online Számla-rendszerébe. Nincs Számlázz.hu / Billingo díj.

A magyar adóhatóság (NAV) kötelezővé teszi, hogy minden számlát beküldj az Online Számla (onlineszamla.nav.gov.hu) rendszerébe — 24 órán belül. Ezt eddig vagy manuálisan csináltad, vagy egy fizetős szolgáltatáson keresztül (Számlázz.hu ~5.000 Ft/hó, Billingo ~7.000 Ft/hó).

A PromNET ezt automatikusan elvégzi — beépítve, minden csomagban, plusz költség nélkül.

Hogyan működik

1. Stripe-on (vagy Barion-on) rendezel egy számlát
2. A PromNET a webhook-ra reagálva:
   • Eltárolja a számlát a saját rendszerében
   • 1 másodpercen belül felépíti az XML-formátumot a NAV-séma szerint
   • SHA3-512 aláírással beküldi a NAV-API-ra
   • Eltárolja a NAV-tranzakció-ID-t
3. Pár másodperc múlva a NAV státusz megjelenik az admin-dashboardon

Mit kell beállítanod

Egyszer kell:

1. NAV Online Számla felületén (online.nav.gov.hu) technikai felhasználó létrehozása
2. 5 érték CF Pages secret-be:
   • NAV_LOGIN
   • NAV_PASSWORD
   • NAV_SIGNATURE_KEY
   • NAV_EXCHANGE_KEY
   • NAV_TAX_NUMBER (8 jegyű)
3. NAV_BASE_URL — test (próba-fázisban) vagy prod (élesben)

Onnantól minden számla automatikusan megy a NAV-ra.

NAV-státuszok

Hibakezelés

Ha a NAV elutasítja a számlát (pl. hibás adóigazgatási szám, formátumi probléma):

• A státusz error-ra vált
• A nav_last_error mezőben látod a NAV-üzenetet
• Az admin-dashboardon Retry gombbal újraindítható

A Stripe-számlázás nem áll meg NAV-hibára — a két rendszer független, csak a beküldés-ütemezés veszít időt.

Aláírás-flow (technikai részlet)

1. tokenExchange — a NAV-szerver visszaad egy 16-byte AES-128-titkosított exchange-tokent. Visszafejtjük az NAV_EXCHANGE_KEY AES-128-ECB-vel.
2. manageInvoice — a számla XML-be base64-encoded; aláírjuk SHA3-512-vel (requestId + timestamp + signatureKey + SHA3-512('CREATE' + invoice_b64))
3. queryTransactionStatus — folyamatosan poll-oljuk a státuszt a transactionId-vel.

Adatbiztonság

• A NAV_SIGNATURE_KEY és NAV_EXCHANGE_KEY Cloudflare-secret-ekben encrypted formában van; a kódban sehol nem látszik clear-text-ben
• A NAV-felé menő XML log-ja nincs (csak a hibák kerülnek a nav_invoice_log-ba)
• A naponkénti minimum 1×, maximum 100× hívás (24 órás határidő miatt rate-limit nem szükséges)

Test-környezet

A NAV_BASE_URL=test beállítással a api-test.onlineszamla.nav.gov.hu endpoint-ot használjuk — ide külön technikai felhasználót kell csinálni a NAV test-felületén. Ajánlott először itt tesztelni, csak utána prod-ra váltani.

Kompatibilitás

• NAV API verzió: 3.0
• Számla-séma: NORMAL (modified, storno is támogatható későbbi sprintben)
• Pénznem: HUF (alap), EUR (USD-támogatás később)
• Áfa: alanyi mentes (egyéni vállalkozó 12 millió Ft alatt) — alap. ÁFA-köteles számlákhoz egy bővítés szükséges (vatRate megadás).

Költségek

A NAV maga ingyenes (államigazgatási szolgáltatás), és az integrációért sincs külön díj. Csak a Stripe-tranzakció-fee marad.