Package Exports

@ribbery009/szamlazz-ts

Readme

szamlazz-ts

TypeScript kliens a Szamlazz.hu számlázó API-hoz.

Az eredeti szamlazz.js csomag TypeScript újraírása, teljes típusbiztonságossággal.

Telepítés

npm install @ribbery009/szamlazz-ts

Használat

Kliens létrehozása

Token alapú autentikáció (ajánlott):

import { Client } from '@ribbery009/szamlazz-ts'

const client = new Client({
  authToken: 'your-szamlazz-agent-key'
})

Felhasználónév/jelszó alapú autentikáció:

const client = new Client({
  user: 'your-username',
  password: 'your-password'
})

Kliens opciók

Opció	Típus	Alapértelmezett	Leírás
`authToken`	`string`	-	Szamlazz.hu Agent kulcs
`user`	`string`	-	Felhasználónév (ha nincs token)
`password`	`string`	-	Jelszó (ha nincs token)
`eInvoice`	`boolean`	`false`	E-számla készítése
`requestInvoiceDownload`	`boolean`	`false`	PDF letöltése a válaszban
`downloadedInvoiceCount`	`number`	`1`	Letöltött példányszám
`responseVersion`	`1 \| 2`	`1`	API válasz verzió
`timeout`	`number`	`0`	Kérés timeout (ms)

Számla kiállítása

import {
  Client,
  Invoice,
  Buyer,
  Item,
  Seller,
  Currencies,
  Languages,
  PaymentMethods,
  TaxSubjects
} from '@ribbery009/szamlazz-ts'

const client = new Client({
  authToken: 'your-agent-key',
  eInvoice: true,
  requestInvoiceDownload: true
})

// Vevő létrehozása
const buyer = new Buyer({
  name: 'Kovács János',
  country: 'Magyarország',
  zip: '1234',
  city: 'Budapest',
  address: 'Példa utca 1.',
  taxSubject: TaxSubjects.NoTaxID,
  email: 'kovacs.janos@example.com',
  sendEmail: true
})

// Tételek létrehozása
const item1 = new Item({
  label: 'Webfejlesztés',
  quantity: 10,
  unit: 'óra',
  vat: 27,
  netUnitPrice: 15000
})

const item2 = new Item({
  label: 'Domain regisztráció',
  quantity: 1,
  unit: 'db',
  vat: 27,
  netUnitPrice: 5000
})

// Számla létrehozása
const invoice = new Invoice({
  paymentMethod: PaymentMethods.BankTransfer,
  currency: Currencies.Ft,
  language: Languages.Hungarian,
  buyer: buyer,
  items: [item1, item2],
  paid: false
})

// Számla kiállítása
const result = await client.issueInvoice(invoice)

console.log('Számla azonosító:', result.invoiceId)
console.log('Nettó összeg:', result.netTotal)
console.log('Bruttó összeg:', result.grossTotal)

// PDF mentése (ha requestInvoiceDownload: true)
if (result.pdf) {
  await fs.promises.writeFile('szamla.pdf', result.pdf)
}

Díjbekérő (proforma számla)

const proformaInvoice = new Invoice({
  buyer: buyer,
  items: [item1],
  proforma: true
})

Díjbekérő → Előlegszámla → Végszámla workflow

// 1. Díjbekérő (proforma) létrehozása
const proforma = new Invoice({
  buyer: buyer,
  items: [item1],
  proforma: true
})
const proformaResult = await client.issueInvoice(proforma)
// proformaResult.invoiceId = "D-2024-123"

// 2. Előlegszámla a díjbekérőre hivatkozva
const prepayment = new Invoice({
  buyer: buyer,
  items: [item1],
  prepaymentInvoice: true,
  proformaInvoiceNumber: 'D-2024-123'  // dijbekeroSzamlaszam
})
const prepaymentResult = await client.issueInvoice(prepayment)
// prepaymentResult.invoiceId = "E-2024-456"

// 3. Végszámla az előlegszámlára hivatkozva
const finalInvoice = new Invoice({
  buyer: buyer,
  items: [remainingItems],
  finalInvoice: true,
  prepaymentInvoiceNumber: 'E-2024-456'  // elolegSzamlaszam
})
const finalResult = await client.issueInvoice(finalInvoice)

Egyszerű előlegszámla (díjbekérő nélkül)

const prepaymentInvoice = new Invoice({
  buyer: buyer,
  items: [item1],
  prepaymentInvoice: true
})

Helyesbítő számla

const adjustmentInvoice = new Invoice({
  buyer: buyer,
  items: [item1],
  adjustmentInvoiceNumber: 'EREDETI-SZAMLA-SZAM'
})

Eladó adatok megadása

const seller = new Seller({
  bank: {
    name: 'OTP Bank',
    accountNumber: '11111111-22222222-33333333'
  },
  email: {
    replyToAddress: 'info@ceg.hu',
    subject: 'Számla',
    message: 'Köszönjük a vásárlást!'
  },
  issuerName: 'Nagy Péter'
})

const invoice = new Invoice({
  seller: seller,
  buyer: buyer,
  items: [item1]
})

Számla sztornózása

const result = await client.reverseInvoice({
  invoiceId: 'E-SZAMLA-2024-123',
  eInvoice: true,
  requestInvoiceDownload: true
})

console.log('Sztornó számla:', result.invoiceId)

Számla lekérdezése

// Számlaszám alapján
const invoiceData = await client.getInvoiceData({
  invoiceId: 'E-SZAMLA-2024-123',
  pdf: false
})

// Rendelésszám alapján
const invoiceData = await client.getInvoiceData({
  orderNumber: 'ORDER-001',
  pdf: true
})

Bejövő számlák fogadása

A Számlázz.hu pénzügyi adatkapcsolat bejövő számla funkciója push alapon működik: a Számlázz.hu XML-t küld a beállított fogadó végpontra, a végpontnak pedig HTTP 200 státusszal egy szamlabevalasz XML-t kell visszaadnia. A válaszban szereplő id értékének egyeznie kell az érkező XML alap.id értékével.

import {
  createIncomingInvoiceResponse,
  parseIncomingInvoiceXml
} from '@ribbery009/szamlazz-ts'

const invoice = await parseIncomingInvoiceXml(rawXmlBody)

console.log('Bejövő számla:', invoice.base.invoiceNumber)
console.log('Szállító:', invoice.supplier.name)
console.log('Bruttó összeg:', invoice.total.gross)

const responseXml = createIncomingInvoiceResponse({
  id: invoice.base.id,
  registrationNumber: 'IKT-2024-001'
})

Next.js Pages Router példa

Fontos, hogy a végpont raw XML body-t olvasson. A Next.js beépített body parserét ehhez ki kell kapcsolni.

import type { NextApiRequest, NextApiResponse } from 'next'
import {
  createIncomingInvoiceResponse,
  parseIncomingInvoiceXml,
  validateIncomingInvoiceKey
} from '@ribbery009/szamlazz-ts'

export const config = {
  api: {
    bodyParser: false
  }
}

async function readBody(req: NextApiRequest): Promise<string> {
  const chunks: Buffer[] = []

  for await (const chunk of req) {
    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk))
  }

  return Buffer.concat(chunks).toString('utf8')
}

export default async function handler(req: NextApiRequest, res: NextApiResponse): Promise<void> {
  if (req.method !== 'POST') {
    res.status(405).end()
    return
  }

  if (!validateIncomingInvoiceKey(req.headers['x-szamlazzhu-key'], process.env.SZAMLAZZ_INCOMING_KEY || '')) {
    res.setHeader('Content-Type', 'application/xml; charset=utf-8')
    res.status(200).send(createIncomingInvoiceResponse({ errorCode: 'KEY_ERR' }))
    return
  }

  const rawXml = await readBody(req)
  const invoice = await parseIncomingInvoiceXml(rawXml)

  const responseXml = createIncomingInvoiceResponse({
    id: invoice.base.id
  })

  res.setHeader('Content-Type', 'application/xml; charset=utf-8')
  res.status(200).send(responseXml)
}

Hibás kulcs esetén a Számlázz.hu által támogatott hibakódos válasz is előállítható:

const responseXml = createIncomingInvoiceResponse({
  errorCode: 'KEY_ERR'
})

A banki tranzakciós adatkapcsolat külön feed; a bejövő számla XML kifizetesek blokkja már tartalmazza az adott bejövő számlához kapcsolódó fizetési állapotot és kifizetési sorokat.

Express példa

import express from 'express'
import {
  createIncomingInvoiceResponse,
  parseIncomingInvoiceXml,
  validateIncomingInvoiceKey
} from '@ribbery009/szamlazz-ts'

const app = express()

app.post('/szamlazz/incoming-invoices', express.text({ type: '*/*' }), async (req, res) => {
  if (!validateIncomingInvoiceKey(req.header('x-szamlazzhu-key'), process.env.SZAMLAZZ_INCOMING_KEY || '')) {
    res.type('application/xml').status(200).send(createIncomingInvoiceResponse({ errorCode: 'KEY_ERR' }))
    return
  }

  const invoice = await parseIncomingInvoiceXml(req.body)
  const responseXml = createIncomingInvoiceResponse({ id: invoice.base.id })

  res.type('application/xml').status(200).send(responseXml)
})

Pénznemek

import { Currencies } from '@ribbery009/szamlazz-ts'

Currencies.Ft   // Magyar Forint (kerekítés: 0 tizedes)
Currencies.HUF  // Magyar Forint
Currencies.EUR  // Euro (kerekítés: 2 tizedes)
Currencies.USD  // US Dollar
Currencies.GBP  // British Pound
// ... és még sok más

Fizetési módok

import { PaymentMethods } from '@ribbery009/szamlazz-ts'

PaymentMethods.Cash         // Készpénz
PaymentMethods.BankTransfer // Átutalás
PaymentMethods.CreditCard   // Bankkártya
PaymentMethods.PayPal       // PayPal

Nyelvek

import { Languages } from '@ribbery009/szamlazz-ts'

Languages.Hungarian // Magyar
Languages.English   // Angol
Languages.German    // Német
Languages.Italian   // Olasz
Languages.Romanian  // Román
Languages.Slovak    // Szlovák

ÁFA alanyiság

import { TaxSubjects } from '@ribbery009/szamlazz-ts'

TaxSubjects.HungarianTaxID // Van magyar adószáma (1)
TaxSubjects.NoTaxID        // Nincs magyar adószáma (-1)
TaxSubjects.EUCompany      // EU-s cég (6)
TaxSubjects.NonEUCompany   // EU-n kívüli cég (7)
TaxSubjects.Unknown        // Ismeretlen (0)

Speciális ÁFA kulcsok

import { SPECIAL_VATS } from '@ribbery009/szamlazz-ts'

// Támogatott speciális ÁFA kulcsok:
// TAM, AAM, EU, EUFAD37, EUK, MAA, ÁKK, TEHK, HO, KBAET

const item = new Item({
  label: 'EU szolgáltatás',
  quantity: 1,
  vat: 'EU',  // Speciális ÁFA kulcs
  netUnitPrice: 10000
})

TypeScript típusok

A csomag exportálja az összes szükséges típust:

import type {
  ClientOptions,
  InvoiceOptions,
  ItemOptions,
  BuyerOptions,
  SellerOptions,
  GetInvoiceDataOptions,
  ReverseInvoiceOptions,
  IssueInvoiceResult,
  ReverseInvoiceResult,
  PostAddress,
  SellerBank,
  SellerEmail,
  SzamlazzError,
  IncomingInvoice,
  IncomingInvoiceBase,
  IncomingInvoiceSupplier,
  IncomingInvoiceCustomer,
  IncomingInvoiceItem,
  IncomingInvoicePayment,
  IncomingInvoiceFinancialItem,
  IncomingInvoiceResponseOptions,
  IncomingInvoiceErrorCode,
  IncomingInvoiceHeaderValue
} from '@ribbery009/szamlazz-ts'

Hibakezelés

try {
  const result = await client.issueInvoice(invoice)
} catch (error) {
  if (error instanceof Error && 'code' in error) {
    console.error('Szamlazz.hu hiba:', error.code, error.message)
  } else {
    console.error('Hiba:', error)
  }
}

API referencia

Invoice opciók

Opció	Típus	Leírás
`issueDate`	`Date`	Számla kelte
`fulfillmentDate`	`Date`	Teljesítés dátuma
`dueDate`	`Date`	Fizetési határidő
`paymentMethod`	`PaymentMethod`	Fizetési mód
`currency`	`Currency`	Pénznem
`language`	`Language`	Számla nyelve
`buyer`	`Buyer`	Vevő adatok (kötelező)
`items`	`Item[]`	Tételek (kötelező)
`seller`	`Seller`	Eladó adatok
`orderNumber`	`string`	Rendelésszám
`proforma`	`boolean`	Díjbekérő
`proformaInvoiceNumber`	`string`	Díjbekérő száma (előlegszámlánál)
`prepaymentInvoice`	`boolean`	Előlegszámla
`prepaymentInvoiceNumber`	`string`	Előlegszámla száma (végszámlánál)
`finalInvoice`	`boolean`	Végszámla
`adjustmentInvoiceNumber`	`string`	Helyesbített számla száma
`paid`	`boolean`	Fizetve
`comment`	`string`	Megjegyzés
`exchangeRate`	`number`	Árfolyam
`exchangeBank`	`string`	Árfolyamot adó bank

Buyer opciók

Opció	Típus	Leírás
`name`	`string`	Név (kötelező)
`zip`	`string`	Irányítószám (kötelező)
`city`	`string`	Város (kötelező)
`address`	`string`	Cím (kötelező)
`country`	`string`	Ország
`email`	`string`	Email cím
`sendEmail`	`boolean`	Számla küldése emailben
`taxSubject`	`TaxSubject`	ÁFA alanyiság
`taxNumber`	`string`	Adószám
`taxNumberEU`	`string`	EU adószám
`postAddress`	`PostAddress`	Postázási cím

Item opciók

Opció	Típus	Leírás
`label`	`string`	Megnevezés (kötelező)
`vat`	`number \| string`	ÁFA kulcs (kötelező)
`netUnitPrice`	`number`	Nettó egységár
`grossUnitPrice`	`number`	Bruttó egységár
`quantity`	`number`	Mennyiség (alapértelmezett: 1)
`unit`	`string`	Mennyiségi egység
`comment`	`string`	Megjegyzés

Tesztek futtatása

npm test

Build

npm run build

Licensz

MIT

Közreműködés

Pull request-eket szívesen fogadunk! Kérjük, a változtatások előtt futtasd le a teszteket.