npm package: @ribbery009/szamlazz-ts
Description: TypeScript kliens a Szamlazz.hu API-hoz - teljes típusbiztonságossággal
Author: ribbery009
Latest version: 1.3.4

# szamlazz-ts

TypeScript kliens a [Szamlazz.hu](https://www.szamlazz.hu) számlázó API-hoz.

Az eredeti [szamlazz.js](https://github.com/ewngs/szamlazz.js/) csomag TypeScript újraírása, teljes típusbiztonságossággal.

## Telepítés

```bash
npm install @ribbery009/szamlazz-ts
```

## Használat

### Kliens létrehozása

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

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

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

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

```typescript
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

```typescript
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)

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

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

```typescript
// 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)

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

### Helyesbítő számla

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

### Eladó adatok megadása

```typescript
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

```typescript
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

```typescript
// 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

```typescript
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

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

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

## Nyelvek

```typescript
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

```typescript
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

```typescript
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:

```typescript
import type {
  ClientOptions,
  InvoiceOptions,
  ItemOptions,
  BuyerOptions,
  SellerOptions,
  GetInvoiceDataOptions,
  ReverseInvoiceOptions,
  IssueInvoiceResult,
  ReverseInvoiceResult,
  PostAddress,
  SellerBank,
  SellerEmail,
  SzamlazzError
} from '@ribbery009/szamlazz-ts'
```

## Hibakezelés

```typescript
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

```bash
npm test
```

## Build

```bash
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.