Kérés

kassza.invoices.get(reference: InvoiceReference, query?: { includePdf?: boolean }, options?: { signal?: AbortSignal }): Promise<InvoiceDetails>
kassza.invoices.find(reference: InvoiceReference, query?: { includePdf?: boolean }, options?: { signal?: AbortSignal }): Promise<InvoiceDetails | null>

A kassza xmlszamlaxml XML-t küld az action-szamla_agent_xml form mezőben. A számlát háromféleképpen azonosíthatod:

const szamla = await kassza.invoices.get('WEB-2026-128')
const ugyanaz = await kassza.invoices.get({ invoiceNumber: 'WEB-2026-128' })

const szamla = await kassza.invoices.get({ orderNumber: 'REND-1001' })

const szamla = await kassza.invoices.get({ externalId: 'webshop-8f3a2c' })

Mezők#

A hivatkozásban pontosan egy kulcs szerepeljen. Üres érték, hiányzó vagy egyszerre több kulcs esetén a kassza validation hibát dob, és kérés nem megy ki.

const szamla = await kassza.invoices.get({ orderNumber: 'REND-1001' }, { includePdf: true })
if (szamla.pdf) await writeFile(`szamlak/${szamla.header.number}.pdf`, szamla.pdf)

get vagy find?#

A get() akkor is hibát dob, ha a számla nem létezik: a Számlázz.hu 7-es kódot ad, amelyből not_found kategóriájú SzamlazzError lesz. A find() pontosan ezt az esetet fordítja null-ra, minden más hibát ugyanúgy továbbdob.

const szamla = await kassza.invoices.find({ orderNumber: 'REND-1001' })
if (szamla === null) await kassza.invoices.create({ orderNumber: 'REND-1001', buyer, items })

Ha a számlának biztosan léteznie kell, például egy mentett számlaszám alapján, a get() a jobb választás. Ha a hiánya is normális eset, használd a find()-ot.

Idempotens számlázás#

A find() a dupla számla elleni védekezés alapja. Számlakészítés előtt nézd meg, van-e már számla a rendelésszámhoz, és bizonytalan hiba után is előbb ezt ellenőrizd, mielőtt újra kiállítanád:

import { type CreateInvoiceInput, isSzamlazzError } from 'kassza'

const BIZONYTALAN = ['network', 'timeout', 'partial_success', 'duplicate']

async function szamlaz(orderNumber: string, adatok: CreateInvoiceInput) {
  const meglevo = await kassza.invoices.find({ orderNumber })
  if (meglevo) return meglevo.header.number

  try {
    const szamla = await kassza.invoices.create({ ...adatok, orderNumber })
    return szamla.number
  } catch (error) {
    if (isSzamlazzError(error) && BIZONYTALAN.includes(error.category)) {
      const letrejott = await kassza.invoices.find({ orderNumber })
      if (letrejott) return letrejott.header.number
    }
    throw error
  }
}

A teljes mintát a Hibakezelés és a Rendelésszám oldal részletezi.

Szabályok#

• Csak a Számlázz.hu-ban kiállított kimenő számlák adatai kérhetők le.
• Rendelésszám alapján mindig a legutóbbi bizonylat jön vissza, ha több is tartozik hozzá.
• Külső azonosítóval csak az a számla kérhető le, amelynél kiállításkor megadtad.
• A lekérés semmit nem módosít, ezért a kassza maintenance, network és timeout hibánál magától újrapróbálja, alapból legfeljebb három próbálkozással. Lásd Amit a kassza újrapróbál.