Válasz

A query() egy TaxpayerInfo objektumot ad vissza. A mezők a NAV Online Számla QueryTaxpayerResponse válaszából jönnek, amelyet a Számlázz.hu változatlanul továbbít.

const ceg = await kassza.taxpayer.query('12345676-2-41')

if (ceg.valid && ceg.address) {
  console.log(ceg.name, ceg.taxNumber?.formatted, ceg.address.formatted)
}

TaxpayerInfo#

TaxpayerTaxNumber#

TaxpayerAddress#

A NAV a címeket jellemzően csupa nagybetűvel küldi. Az olvasható formában a kassza szavanként nagy kezdőbetűt ír, a kötőjeles neveket részenként alakítja, a római számot meghagyja: BUDAPEST XI. → Budapest XI., BAJCSY-ZSILINSZKY → Bajcsy-Zsilinszky. A vegyes kis- és nagybetűs értékekhez nem nyúl. A raw mezőben (countryCode, region, postalCode, city, streetName, publicPlaceCategory, number, building, staircase, floor, door, lotNumber) az eredeti értékeket találod.

A formatted sorrendje: irányítószám és település, vessző, közterület, házszám, épület, lépcsőház, emelet, ajtó, vessző, helyrajzi szám, vessző, és a végén az országkód, ha nem HU. A csak számjegyből álló házszám, lépcsőház, emelet és ajtó után pontot tesz:

1111 Budapest XI., Bajcsy-Zsilinszky út 12. B ép. 2. lh. 3. em. 14. ajtó
2000 Szentendre, hrsz. 1234/5

Ha a valid false#

Ha a NAV szerint a törzsszámhoz nem tartozik érvényes adószám, a query() nem dob hibát, hanem ezt adja vissza:

{ valid: false, addresses: [], infoDate: undefined, requestId: '38046_g2z6726bg67ymdt3p56bg6' }

Ilyenkor:

• ne töltsd ki a vevő adatait, és jelezd a felhasználónak, hogy ellenőrizze a beírt számot;
• ne kérdezd le újra ugyanazt a számot, ez nem átmeneti hiba, hanem a NAV válasza;
• ha később vissza kell nézned, mit válaszolt a NAV, naplózd a requestId mezőt.

A vevő kitöltése#

Az űrlapon beírt adószámot a böngésző előbb a kassza/validators modullal ellenőrzi, és csak érvényes formátumnál hívja a szervert. A szerver újra ellenőriz, lekérdezi a NAV-ot, és a válaszból összerakja a számla buyer mezőjét.

'use client'

import type { InvoiceBuyer } from 'kassza'
import { parseHungarianTaxNumber } from 'kassza/validators'
import { useState } from 'react'
import { vevoAdoszambol } from './actions'

export function AdoszamMezo({ onVevo }: { onVevo: (vevo: InvoiceBuyer) => void }) {
  const [hiba, setHiba] = useState<string>()

  async function kitolt(bevitt: string) {
    const adoszam = parseHungarianTaxNumber(bevitt)
    if (!adoszam) {
      setHiba('Hibás adószám. Így add meg: 12345676-2-41')
      return
    }
    const eredmeny = await vevoAdoszambol(adoszam.formatted)
    if (!eredmeny.ok) {
      setHiba(eredmeny.uzenet)
      return
    }
    setHiba(undefined)
    onVevo(eredmeny.vevo)
  }

  return (
    <label>
      Adószám
      <input name="adoszam" onBlur={(event) => kitolt(event.currentTarget.value)} />
      {hiba && <span role="alert">{hiba}</span>}
    </label>
  )
}

'use server'

import { type InvoiceBuyer, isSzamlazzError } from 'kassza'
import { parseHungarianTaxNumber } from 'kassza/validators'
import { kassza } from '@/lib/kassza'

type VevoEredmeny = { ok: true; vevo: InvoiceBuyer } | { ok: false; uzenet: string }

export async function vevoAdoszambol(bevitt: string): Promise<VevoEredmeny> {
  const adoszam = parseHungarianTaxNumber(bevitt)
  if (!adoszam) return { ok: false, uzenet: 'Hibás adószám.' }

  try {
    const ceg = await kassza.taxpayer.query(adoszam.formatted)
    if (!ceg.valid || !ceg.address) {
      return { ok: false, uzenet: 'A NAV nem talált érvényes adószámot. Ellenőrizd a számot.' }
    }
    return {
      ok: true,
      vevo: {
        name: ceg.name ?? '',
        zip: ceg.address.postalCode,
        city: ceg.address.city,
        address: ceg.address.formatted.split(', ').slice(1).join(', '),
        taxNumber: ceg.taxNumber?.formatted ?? adoszam.formatted,
        taxpayerType: 'hungarianTaxNumber',
      },
    }
  } catch (error) {
    if (isSzamlazzError(error) && error.retryable) {
      return { ok: false, uzenet: 'A NAV most nem elérhető. Add meg kézzel a vevő adatait.' }
    }
    throw error
  }
}

• Az address a formatted első vessző utáni része, mert az irányítószám és a település külön mezőbe kerül.
• A taxNumber a NAV válaszából jön, de ha abból hiányzik a megyekód, a beírt és ellenőrzött adószámot használja.
• A retryable hibákat (maintenance, network, timeout) a kassza már újrapróbálta, mire a catch ágba érsz, ezért itt nem kell újra hívnod.

A mezőket a Számla létrehozás kérés oldala írja le.

Hibák#

A NAV hibáját a válasz result eleme jelzi (funcCode értéke ERROR). Számjegyes errorCode esetén a kassza a Számlázz.hu hibakód táblája szerint adja a kategóriát. Az ott nem szereplő és a szöveges kódok unknown kategóriát kapnak. Az összes kódot a Hibakezelés, hibakódok oldal sorolja fel.

Tesztekben a mock kliens taxpayers opciójával adhatsz meg törzsszám szerinti válaszokat. Az ismeretlen törzsszámra a mock { valid: false, addresses: [] } választ ad.