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
})

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
} 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.