JSPM

  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 368
  • Score
    100M100P100Q74944F
  • License MIT

TypeScript kliens a Szamlazz.hu API-hoz - teljes típusbiztonságossággal

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

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.