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-tsHaszná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ásFizetési módok
import { PaymentMethods } from '@ribbery009/szamlazz-ts'
PaymentMethods.Cash // Készpénz
PaymentMethods.BankTransfer // Átutalás
PaymentMethods.CreditCard // Bankkártya
PaymentMethods.PayPal // PayPalNyelvek
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 testBuild
npm run buildLicensz
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.