NAV kliens

A createNavReceiptClient() a NAV nyugta-adatszolgáltatási interfészét hívja (/receipt-if, teszt és éles környezet). Lekérdezi a NAV-nál rögzített napi összesítőket, és ha neked kell beküldeni (például a kézi nyugtatömb nyugtáit), beküldi, javítja vagy érvényteleníti őket. Az SHA-512 jelszó-hasht és az SHA3-512 kérésaláírást maga készíti, függőség nélkül.

Technikai felhasználó#

A géppel történő adatszolgáltatáshoz a NAV Felhasználókezelőjében (UAM) technikai felhasználó kell, nyugta-adatszolgáltatási jogosultsággal és aláírókulccsal. Ennek adatai kellenek a klienshez:

NAV_LOGIN=...
NAV_PASSWORD=...
NAV_SIGNATURE_KEY=...
NAV_TAX_NUMBER=12345676

import { createNavReceiptClient } from 'kassza/nav'

export const nav = createNavReceiptClient({
  environment: 'production',
  login: process.env.NAV_LOGIN!,
  password: process.env.NAV_PASSWORD!,
  signatureKey: process.env.NAV_SIGNATURE_KEY!,
  taxNumber: process.env.NAV_TAX_NUMBER!,
})

A NAV token 5 percig érvényes. A kliens tárolja és újrahasznosítja, lejárat vagy 401 válasz után egyszer újat kér.

Lekérdezés#

const lista = await nav.listAllReports({ from: '2026-09-01', to: '2026-09-30' })

for (const sor of lista) {
  console.log(sor.applicableDate, sor.serialNumber, sor.totalAmount, sor.status, sor.softwareName)
}

const elso = lista[0]
if (elso) console.log(await nav.getReport(elso.id))

A listReports() egy oldalt ad vissza (page, pageSize, rendezés), a listAllReports() végiglapozza az időszakot. Az állapot RECORDED (érvényes) vagy INVALIDATED (érvénytelenített vagy javítással felülírt). A softwareName megmutatja, melyik szoftver küldte be, így látod, mit jelentett a Számlázz.hu.

Beküldés#

Beküldés előtt a kiállító szoftver nevét egyszer rögzíteni kell a NAV-nál, különben EPGP0002 hibát kapsz:

const nav = createNavReceiptClient({
  environment: 'production',
  login: process.env.NAV_LOGIN!,
  password: process.env.NAV_PASSWORD!,
  signatureKey: process.env.NAV_SIGNATURE_KEY!,
  taxNumber: process.env.NAV_TAX_NUMBER!,
  softwareName: 'Kézi tömb',
  allowWrite: true,
})

await nav.registerSoftware()

const eredmeny = await nav.submitReport(jelentes)
console.log(eredmeny.id, eredmeny.created)

A registerSoftware() idempotens: ha a név már rögzítve van, nem küld újra. A submitReport() beküldés előtt ellenőrzi az adatokat (dátum, sorszám, pénznem, árfolyam, kategóriák, összegek és darabszámok), és megnézi, van-e már érvényes adatszolgáltatás ugyanarra a tárgynapra és kezdő sorszámra:

• ha van, és az adatai egyeznek, nem küld újra, hanem created: false eredményt ad,
• ha van, de eltér, conflict hibát dob a meglévő azonosítójával. Ilyenkor a javítás a helyes út, nem az újraküldés.

Javítás és érvénytelenítés#

await nav.modifyReport(id, javitottJelentes)
await nav.invalidateReport(id)

A javítás új rekordot hoz létre, a régi INVALIDATED lesz. A kezdő sorszám nem javítható: ha az hibás, érvénytelenítsd a jelentést, és küldj be újat. Egy rekord csak egyszer javítható (EPGP0051), a további javítás a javítással létrejött új rekordra megy.

Segédlisták#

A vatCategories() a NAV áfakategóriáit adja érvényességi idővel, a currencies() a beküldhető pénznemeket. A kassza/reports napi összesítője ugyanezeket a kategóriákat használja.

Hibák#

Minden hiba NavReceiptError, az isNavReceiptError() típusőrrel szűkítheted.

A NAV EPGP hibakódja a code mezőben van, a magyar javítási tipp a hint mezőben.

Kapcsolódó#