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: '[email protected]',
  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: '[email protected]',
    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.