# Bizonylat Publikus API (v1)

A Bizonylat magyar, NAV-kompatibilis számlázó platform. Ezzel az API-val egy
külső rendszer (webshop, foglalási rendszer, belső eszköz) egyetlen HTTP
hívással valódi, NAV-nak jelentett számlát állíthat ki.

- **Alap URL:** `https://api.bizonylat.hu`
- **Hitelesítés:** minden kéréshez szükséges az `Authorization: Bearer <API_KULCS>`
  fejléc (a kulcsok `bz_live_…` formátumúak, a Bizonylat felületén az API
  menüben hozhatók létre; egy kulcs egy céghez tartozik)
- **Tartalomtípus:** `Content-Type: application/json`
- **Pénznem:** alapértelmezés `HUF`. `EUR`, `USD`, `RON`, `RSD`, `UAH`, `JPY`, `TRY`, `BGN`, `ISK`, `GBP`, `CHF`, `PLN` és `CZK` is elfogadott.
- **EU-s és külföldi vevők:** egy hívás `client.euVatId` (`kozossegiAdoszam`) mezővel — lásd az *EU-s és külföldi vevők* fejezetet közvetlenül a gyorsindítás után.
- **Választható értékek:** minden elfogadott érték (pénznemek, országok, ÁFA-kategóriák, fizetési módok, nyelvek, mennyiségi egységek…) a `GET /public/v1/reference` végponton — lásd *Választható értékek*.
- **Postman:** kész gyűjtemény az összes `/public/v1` hívással, az OpenAPI-specifikációból generálva: https://bizonylat.hu/downloads/bizonylat-public-api.postman_collection.json (környezet a `baseUrl` és `apiKey` változóval: https://bizonylat.hu/downloads/bizonylat-public-api.postman_environment.json). Az `apiKey` értékébe illessze be a saját kulcsát; a letöltött érték csak helykitöltő.
- **Változások:** a bővítések előzetes értesítés nélkül érkeznek; a törő változásokat és a végpontok megszüntetését legalább 90 nappal előre bejelentjük — lásd az *API-változási szabály* fejezetet a végén.
- **Az árak nettó** egységárak. Az ÁFÁ-t és a bruttó összegeket a Bizonylat
  számítja ki szerveroldalon, 2 tizedesre kerekítve.
- **Most kezdi?** Olvassa el közvetlenül alatta az *Első lépések
  integrátoroknak* fejezetet: tesztcég, NAV technikai felhasználó (az API-kulcs
  önmagában nem állít ki számlát), kulcs, keretek, a minimális folyamat és a
  gyakori hibakódok.

## Első lépések integrátoroknak

Ez a fejezet a fiók létrehozásától az első kiállított számla PDF-jéig vezet,
abban a sorrendben, ahogy a lépések egymásra épülnek. A részletek a
hivatkozott fejezetekben találhatók.

### 1. Fiók és e-mail-megerősítés

- Regisztráljon a Bizonylatba. A megerősítő levelet a **fiók belépési
  e-mail-címére** küldjük — arra, amellyel regisztrált és belép —, nem a
  cégadatoknál megadott vagy egy kollégája címére.
- Amíg a cím nincs megerősítve, új fiókban nem hozható létre API-kulcs,
  ügyfél, termék és bizonylat (`403 EMAIL_NOT_CONFIRMED`). A címzett címét és a
  „Megerősítő levél újraküldése” gombot a felület tetején megjelenő
  figyelmeztető sáv mutatja; nézze meg a levélszemét mappát is.

### 2. Tesztcég létrehozása

- A bal oldali menü tetején, a cég nevére kattintva nyíló cégváltóban:
  **Cég hozzáadása** → jelölje be: **„Tesztcég (NAV tesztkörnyezet)”** →
  **Cég létrehozása**.
- A tesztcég a NAV **tesztrendszerébe** állít ki: a PDF-eken „TESZT”
  jelölés, az e-mailek tárgyában `[TESZT]` előtag szerepel. Benne minden
  funkció díjmentes (Növekedés csomagnak megfelelő), az API-számlák nem
  számítanak bele a havi keretbe.
- A tesztcég végleges (nem alakítható valódi céggé), és a létrehozása után 30
  nappal minden adatával együtt törlődik; a cégen belül 7 nappal
  meghosszabbítható, akár többször is. Részletek: *Tesztelés — tesztcéggel*.

### 3. NAV technikai felhasználó — az API-kulcs önmagában nem elég

Számla és díjbekérő csak **ellenőrzött NAV-kapcsolattal** állítható ki; enélkül
a kiállítás `409 NAV_CREDENTIALS_NOT_VERIFIED` hibát ad (az árajánlat és a
díjbekérő létrehozása `409 NAV_CONNECTION_REQUIRED` hibát). Tesztcégben a NAV
**tesztkörnyezeti** technikai felhasználója kell:

- Jelentkezzen be a NAV tesztfelületére (onlineszamla-test.nav.gov.hu), és
  regisztrálja a céget a **valódi adószámával**. A teszt- és az éles
  NAV-rendszer külön működik: az élesben meglévő regisztráció ott nem érvényes.
- Ugyanott hozzon létre technikai felhasználót a „Számlák kezelése” és a
  „Számlák lekérdezése” jogosultsággal, és másolja ki az XML aláírókulcsot és
  a cserekulcsot.
- A tesztcégben a **Beállítások → Céges profil** oldalon adja meg ugyanezt az
  adószámot, majd a **Beállítások → NAV kapcsolat** oldalon a technikai
  felhasználó adatait, és indítsa el az ellenőrzést.
- **NOT_REGISTERED_CUSTOMER** (az ellenőrzés eredménye „Nincs regisztrálva”):
  a NAV tesztrendszere nem ismeri az adószámot, vagy a technikai felhasználó
  nem ehhez az adószámhoz tartozik. Kitalált adószámmal (pl. 12345678-1-42) a
  kapcsolat nem jöhet létre; regisztráljon a valódi adószámmal, és ellenőrizze
  újra. A felület ugyanott leírja a lépéseket.
- **FORBIDDEN** (az ellenőrzés eredménye „Hiányzó NAV-jogosultság”, a NAV
  válasza „Jogosultság szükséges”): a NAV ismeri a technikai felhasználót, de
  nincs „Számlák kezelése” és „Számlák lekérdezése” jogosultsága, vagy másik
  cég (adószám) alatt jött létre. Kapcsolja be a két jogosultságot a NAV
  felület Felhasználók menüpontjában, vagy hozzon létre új technikai
  felhasználót ennek a cégnek a nevében, majd ellenőrizze újra.
- Valódi cégnél ugyanez az éles felülettel (onlineszamla.nav.gov.hu) és éles
  technikai felhasználóval. A technikai felhasználóról bővebben:
  https://bizonylat.hu/fogalomtar/technikai-felhasznalo

### 4. API-kulcs — cégenként

- A tesztcégben nyissa meg az **API** menüpontot → **Kulcsok** → adjon nevet a
  kulcsnak → **Új kulcs létrehozása**. A kulcs (`bz_live_…`) csak most
  látszik egyszer; tárolja biztonságos helyen. Kulcsot a cég Tulajdonosa vagy
  Adminja hozhat létre.
- Egy kulcs **egy céghez** tartozik: tesztcég kulcsa csak a tesztcégbe,
  valódi cég kulcsa csak a valódi cégbe állít ki. Élesítéskor hozzon létre
  kulcsot a valódi cégben, és cserélje le.
- Ellenőrzés: a `GET /public/v1/me` visszaadja a cég nevét, a csomagot és azt,
  hogy tesztcég-e (`company.sandbox`), anélkül hogy bármit létrehozna.

```bash
curl "https://api.bizonylat.hu/public/v1/me" -H "Authorization: Bearer $BIZONYLAT_API_KEY"
```

### 5. Csomagok és API-keret

Az API minden csomagban elérhető, az Ingyenesben is. Az API-n kiállított
számlák havi kerete: **Ingyenes 50, Induló 300, Növekedés 1000, Vállalat
korlátlan**; a tesztcég API-számlái nem számítanak bele, a felületen
kiállított számla minden csomagban korlátlan. A keret elérése után az API még
72 óráig kiállít, utána `402 API_INVOICE_LIMIT_REACHED`. Az e havi felhasználás:
`GET /public/v1/usage`. Részletek: *Havi API-számlakeret*.

### 6. A minimális folyamat: létrehozás → kiállítás → állapot → PDF

Egy hívással (létrehozás és kiállítás egyben):

```bash
curl -X POST "https://api.bizonylat.hu/public/v1/invoices" \
  -H "Authorization: Bearer $BIZONYLAT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1001-invoice" \
  -d '{ "client": { "name": "Kiss Anna", "email": "anna@example.com" },
        "lines": [ { "name": "Bérleti díj", "quantity": 1, "unitPrice": 10000, "vatRate": 27 } ] }'
```

Vagy két lépésben: `"draft": true` piszkozatot hoz létre, a
`POST /public/v1/invoices/:id/issue` állítja ki. A válaszban kapott `id`-vel:

- `GET /public/v1/invoices/:id` — `status`, `navStatus`, `paymentStatus`,
  összegek, `publicUrl`.
- `GET /public/v1/invoices/:id/nav` — a NAV-beküldések története; hiba esetén a
  `submissions[].errorCode` és `errorMessage` mondja meg az okot.
- `GET /public/v1/invoices/:id/pdf` — a számla PDF-je.

A `navStatus` `PENDING` állapotból indul (a beküldés a háttérben fut), és
`DONE` lesz, ha a NAV befogadta; `REJECTED` vagy `ABORTED` esetén nézze meg a
`/nav` választ vagy a felület NAV menüpontját.

### 7. Webhook — nem kötelező

Az állapot lekérdezéssel (polling) is követhető a fenti végpontokkal, több
számlánál a `GET /public/v1/invoices?updatedSince=…` listával. Webhook akkor
hasznos, ha nem szeretne lekérdezni: a Bizonylat ilyenkor aláírt eseményt küld
(pl. `invoice.nav_accepted`, `invoice.paid`). Beállítás: **API** menüpont →
**Webhookok**, vagy `POST /public/v1/webhooks`. Részletek: *Webhookok*.

### 8. Gyakori hibakódok és teendők

A programot a `code` (vagy `error.code`) értékére építse, ne az üzenet
szövegére. `?lang=hu` vagy `Accept-Language: hu` esetén az üzenet magyarul
érkezik, és megnevezi a teendőt (lásd *Magyar hibaüzenetek*). Minden hívás a
kódjával együtt látszik az API naplóban (**API** menüpont → **API-napló**).

- **401** `API_KEY_MISSING` — Mikor: nincs `Authorization` fejléc. Teendő: küldje az `Authorization: Bearer <API-kulcs>` fejlécet.
- **401** `API_KEY_INVALID` — Mikor: ismeretlen, csonka vagy visszavont kulcs. Teendő: ellenőrizze a teljes `bz_live_…` kulcsot; szükség esetén hozzon létre újat (API → Kulcsok).
- **403** `API_ACCESS_DISABLED` — Mikor: a cégnél egyedi beállítás kikapcsolta az API-t. Teendő: írjon nekünk az office@verdeholding.hu címre; csomagváltás nem kell, az API minden csomagban elérhető.
- **403** `EMAIL_NOT_CONFIRMED` — Mikor: kulcs létrehozása a felületen, megerősítetlen e-mail-címmel. Teendő: kattintson a fiók e-mail-címére küldött megerősítő levélben lévő hivatkozásra.
- **409** `NAV_CREDENTIALS_NOT_VERIFIED` — Mikor: kiállítás ellenőrzött NAV technikai felhasználó nélkül. Teendő: Beállítások → NAV kapcsolat; tesztcégben NAV tesztkörnyezeti technikai felhasználóval (3. lépés).
- **409** `NAV_CONNECTION_REQUIRED` — Mikor: árajánlat vagy díjbekérő ellenőrzött NAV-kapcsolat előtt. Teendő: mint fent.
- **NAV-ellenőrzés: NOT_REGISTERED_CUSTOMER** — Mikor: a Beállítások → NAV kapcsolat oldalon az ellenőrzés „Nincs regisztrálva”. Teendő: regisztrálja a céget a valódi adószámával a megfelelő NAV-felületen (3. lépés).
- **402** `API_INVOICE_LIMIT_REACHED` — Mikor: elfogyott a havi API-számlakeret, a 72 órás türelmi idő is. Teendő: nagyobb csomag (Beállítások → Előfizetés), vagy várjon a következő hónapig.
- **400** `FST_ERR_VALIDATION` — Mikor: a kérés nem felel meg a sémának. Teendő: az üzenet megnevezi a mezőt.
- **409** `INVOICE_NOT_DRAFT` — Mikor: `/issue` vagy módosítás nem piszkozaton. Teendő: a számla már ki van állítva; kérdezze le a `GET /public/v1/invoices/:id` végponttal.

A teljes lista: *Hibák*.

## Gyorsindítás — számla kiállítása fizetéskor

```bash
curl -X POST "https://api.bizonylat.hu/public/v1/invoices" \
  -H "Authorization: Bearer $BIZONYLAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ugyfel": {
      "nev": "Kiss Anna",
      "email": "anna@example.com",
      "cim": "Fő utca 1.",
      "varos": "Budapest",
      "iranyitoszam": "1011",
      "orszag": "HU"
    },
    "tetelek": [
      { "nev": "Hidratáló arckrém 50ml", "mennyiseg": 2, "egysegar": 4990, "afaKulcs": 27 },
      { "nev": "Szállítási díj", "mennyiseg": 1, "egysegar": 1490, "afaKulcs": 27 }
    ],
    "fizetesiMod": "ATUTALAS",
    "emailKuldes": true
  }'
```

Ez az egy hívás: létrehozza (vagy újrahasznosítja) az ügyfelet, kiállítja a
számlát valódi, folytonos sorszámmal, a háttérben beküldi a NAV-nak,
eltárolja a PDF-et, és — az `emailKuldes: true` miatt — e-mailben elküldi a
számla PDF-jét a vevőnek.

**Magyar vagy angol mezőnevek — mindkettő működik.** A fenti kérés angol
nevekkel (`client.name`, `client.address`, `lines[].unitPrice`,
`"paymentMethod": "BANK_TRANSFER"`, `sendEmail` …) pontosan ugyanazt a
számlát állítja ki. A referencia táblázatai az angol (kanonikus) neveket
mutatják; mindegyik magyar megfelelője a *Magyar mezőnevek* fejezetben
található. A válasz mezői mindig angolok.

## EU-s és külföldi vevők

Egyetlen `POST /public/v1/invoices` hívás létrehozza a külföldi vevőt és
kiállítja a számlát — nem kell előtte `POST /public/v1/clients` hívás. Ugyanez
a beágyazott `client` (`ugyfel`) objektum működik piszkozatnál
(`"draft": true`), díjbekérőnél (`"invoiceType": "PROFORMA"`), árajánlatnál
és előfizetésnél is.

### Példa — EU-s céges vevő, szolgáltatás, EUR (egy hívás)

```bash
curl -X POST "https://api.bizonylat.hu/public/v1/invoices" \
  -H "Authorization: Bearer $BIZONYLAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ugyfel": {
      "nev": "Beispiel GmbH",
      "kozossegiAdoszam": "DE123456789",
      "orszag": "DE",
      "cim": "Hauptstraße 1",
      "varos": "Berlin",
      "iranyitoszam": "10115",
      "email": "billing@beispiel.de",
      "nyelv": "en"
    },
    "tetelek": [
      { "nev": "Szoftverfejlesztés", "mennyiseg": 10, "egyseg": "óra", "egysegar": 120, "afaKategoria": "FORDITOTT_ADOZAS" }
    ],
    "penznem": "EUR",
    "fizetesiMod": "ATUTALAS",
    "emailKuldes": true
  }'
```

Itt nem kell `vatRate` (`afaKulcs`) és `exchangeRate` (`arfolyam`): a
`FORDITOTT_ADOZAS` (`EU_REVERSE_CHARGE`) tétel ÁFA-kulcs nélkül 0%-ot kap, az
EUR árfolyama pedig a teljesítés napjának MNB-árfolyama (kivéve, ha a cég a
saját bankja vagy az EKB árfolyamát alkalmazza — lásd lent). A számla a
NAV-hoz úgy megy, hogy a vevő `OTHER` státuszú, közösségi adószáma
`DE123456789`.

### Példa — EU-s céges vevő, termékértékesítés

```json
{
  "client": {
    "name": "Exemple SARL",
    "euVatId": "FR12345678901",
    "country": "FR",
    "address": "1 rue de la Paix",
    "city": "Paris",
    "postalCode": "75002"
  },
  "lines": [
    { "name": "Hidratáló arckrém 50ml", "quantity": 200, "unitPrice": 9.5, "vatRate": 0, "vatCategory": "EU_GOODS_SUPPLY" },
    { "name": "Szállítás", "quantity": 1, "unitPrice": 80, "vatRate": 0, "vatCategory": "EU_GOODS_SUPPLY" }
  ],
  "currency": "EUR",
  "exchangeRate": "392,55",
  "performanceDate": "2026-09-28"
}
```

### Példa — ugyanez angol mezőnevekkel

```json
{
  "client": {
    "name": "Beispiel GmbH",
    "euVatId": "DE123456789",
    "country": "DE",
    "address": "Hauptstraße 1",
    "city": "Berlin",
    "postalCode": "10115",
    "emailLocale": "en"
  },
  "lines": [
    { "name": "Software development", "quantity": 10, "unit": "óra", "unitPrice": 120, "vatCategory": "EU_REVERSE_CHARGE" }
  ],
  "currency": "EUR",
  "paymentMethod": "BANK_TRANSFER"
}
```

### Vevőazonosítók és a NAV-adat

Négy nem kötelező mező mondja meg, ki a vevő. A vevőhöz illőt küldje; a
**tételek ÁFA-kategóriáját továbbra is Ön választja** — ezek a mezők soha nem
változtatják meg.

| Mező | Magyar mezőnév | Kinek | Ellenőrzés (csak formai — nincs VIES- vagy nyilvántartás-lekérdezés) |
|---|---|---|---|
| `client.taxNumber` | `adoszam` | magyar adóalany (`country` `HU` vagy nincs megadva) | `NNNNNNNN-N-NN`, áfakód 1–5, megyekód 01–99 (beágyazott ügyfélnél a 8 jegyű törzsszám is elfogadott). Más `country` mellett (magyar áfaalanyként nyilvántartott külföldi cég) csak `NNNNNNNN-N-NN` alakban, érvényes ellenőrző számjeggyel; puszta számsor vagy hibás ellenőrző számjegy → `400 INVALID_TAX_NUMBER`: a külföldi azonosító a `thirdStateTaxId` vagy az `euVatId` mezőbe való. Ide küldött, betűvel kezdődő EU-n kívüli azonosító (`GB123456789`, `CHE-123.456.789`) EU-n kívüli `country` mellett a `thirdStateTaxId` mezőbe kerül, különben `400 INVALID_TAX_NUMBER`. |
| `client.groupMemberTaxNumber` | `csoporttagAdoszam` | magyar áfacsoport tagja | A csoporttag saját adószáma, `NNNNNNNN-4-NN` (áfakód 4); csak ha a `taxNumber` a csoportazonosító szám (áfakód — 9. számjegy — 5). Különben `400 INVALID_GROUP_MEMBER_TAX_NUMBER`. |
| `client.euVatId` | `kozossegiAdoszam` | EU-tagállambeli vállalkozás | Tagállami áfa-előtag + 2–12 betű/számjegy (Görögországé `EL`; a `GB`, `XI`, `CH` nem tagállam). Magyar (`HU` + 8 számjegy) csak a teljes `taxNumber` mellett. Különben `400 INVALID_EU_VAT_ID`. |
| `client.thirdStateTaxId` | `harmadikOrszagbeliAdoazonosito` | EU-n kívüli vállalkozás (pl. szerb PIB, emírségekbeli TRN, japán cégszám, svájci UID, brit VAT, amerikai EIN) | 1–50 karakter: betű, számjegy, szóköz, `-` `.` `/`; levágott szóközökkel, nagybetűsen tároljuk. EU-n kívüli `country` kell hozzá. Közösségi adószám, magyar adószám (`NNNNNNNN-N-NN`), hiányzó, `HU` vagy EU-s `country` → `400 INVALID_THIRD_STATE_TAX_ID`. |

**NAV-megfeleltetés** (az Online Számla 3.0 számlaadat `customerInfo`
része; az első illeszkedő sor dönt):

| Az ügyfélnek van | `customerVatStatus` | `customerVatData` | Név és cím |
|---|---|---|---|
| magyar `taxNumber` (`HU`-tól eltérő `country` mellett: `NNNNNNNN-N-NN`, érvényes ellenőrző számjeggyel) | `DOMESTIC` | `customerTaxNumber` (`taxpayerId`, `vatCode`, `countyCode`) | megy |
| áfacsoport-azonosító a `taxNumber`-ben + `groupMemberTaxNumber` | `DOMESTIC` | `customerTaxNumber` a csoportazonosítóval, a tag a `customerTaxNumber/groupMemberTaxNumber` elemben | megy |
| `euVatId` | `OTHER` | `communityVatNumber` | megy |
| `thirdStateTaxId` | `OTHER` | `thirdStateTaxId` | megy |
| egyik sem | `PRIVATE_PERSON` | — | nem megy (magánszemélynél a NAV nem fogadja) |

Akinek a `country` mezője nem `HU`, azt csak `NNNNNNNN-N-NN` alakú, érvényes
ellenőrző számjegyű magyar adószámmal jelentjük `DOMESTIC` vevőként
(magyar áfaalanyként nyilvántartott külföldi cég); más számsorral soha. A számla PDF-je és a nyilvános számlaoldal a vevő blokkjában
feltünteti az azonosítókat (a `thirdStateTaxId` címkéje a dokumentum nyelvén
„Külföldi adóazonosító” / „Tax ID”).

**A meglévő ügyfél felismerése**: magyar `taxNumber` esetén csak az számít
(`groupMemberTaxNumber` mellett annak a csoporttagnak a rekordja: a tagok
osztoznak a csoportazonosítón); nélküle előbb az `euVatId`, aztán a
`thirdStateTaxId`, végül az e-mail/név szabályok — ezek ilyenkor csak olyan
ügyfelet vesznek át, akinek a három azonosító közül egyik sincs. A megtalált
ügyfél, ha nincs még közösségi adószáma / külföldi adóazonosítója /
csoporttag-adószáma, megkapja a küldöttet; a tárolt eltérőt megtartja
(módosítás: `PATCH /public/v1/clients/:id`).

#### Magyar cég

```json
{
  "ugyfel": { "nev": "Minta Kft.", "adoszam": "12345678-2-41", "orszag": "HU", "iranyitoszam": "1051", "varos": "Budapest", "cim": "Váci utca 1." },
  "tetelek": [ { "nev": "Tanácsadás", "mennyiseg": 1, "egysegar": 100000, "afaKulcs": 27 } ],
  "emailKuldes": false
}
```

#### Magyar áfacsoport tagja

```json
{
  "ugyfel": {
    "nev": "Csoporttag Zrt.",
    "adoszam": "17781234-5-44",
    "csoporttagAdoszam": "12345676-4-41",
    "iranyitoszam": "1117", "varos": "Budapest", "cim": "Október huszonharmadika utca 8."
  },
  "tetelek": [ { "nev": "Tanácsadás", "mennyiseg": 1, "egysegar": 100000, "afaKulcs": 27 } ],
  "emailKuldes": false
}
```

#### EU-s cég (szolgáltatás, fordított adózás)

```json
{
  "ugyfel": { "nev": "Beispiel GmbH", "kozossegiAdoszam": "DE123456789", "orszag": "DE", "iranyitoszam": "10115", "varos": "Berlin", "cim": "Hauptstraße 1" },
  "tetelek": [ { "nev": "Szoftverfejlesztés", "mennyiseg": 10, "egyseg": "óra", "egysegar": 120, "afaKategoria": "FORDITOTT_ADOZAS" } ],
  "penznem": "EUR",
  "emailKuldes": false
}
```

#### EU-n kívüli cég (Japán)

```bash
curl -X POST "https://api.bizonylat.hu/public/v1/invoices" \
  -H "Authorization: Bearer $BIZONYLAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ugyfel": {
      "nev": "Example K.K.",
      "harmadikOrszagbeliAdoazonosito": "1234567890123",
      "orszag": "JP",
      "iranyitoszam": "100-0005",
      "varos": "Tokyo",
      "cim": "1-1 Marunouchi, Chiyoda-ku",
      "nyelv": "ja"
    },
    "tetelek": [
      { "nev": "Tanácsadás", "mennyiseg": 1, "egysegar": 100000, "afaKategoria": "HARMADIK_ORSZAG" }
    ],
    "emailKuldes": false
  }'
```

A NAV-hoz `<customerVatStatus>OTHER</customerVatStatus>`,
`<customerVatData><thirdStateTaxId>1234567890123</thirdStateTaxId></customerVatData>`,
a név és a cím megy, `JP` országkóddal. Angol mezőnevekkel:
`"client": { "name": "Example K.K.", "thirdStateTaxId": "1234567890123", "country": "JP" }`,
a tétel kategóriája `THIRD_COUNTRY_SUPPLY`.

#### Magánszemély

```json
{
  "ugyfel": { "nev": "Kiss Anna", "email": "anna@example.com", "orszag": "HU" },
  "tetelek": [ { "nev": "Termék", "mennyiseg": 1, "egysegar": 5000, "afaKulcs": 27 } ],
  "emailKuldes": false
}
```

### Mit csinál ezzel az API

- **`client.euVatId`** (magyar mezőnév: `kozossegiAdoszam`) a vevő közösségi
  adószáma. Nagybetűsen, szóközök nélkül tároljuk, ellenőrzése pontosan
  ugyanaz, mint a `POST /public/v1/clients` hívásnál (tagállami áfa-előtag —
  Görögországé `EL` — + 2–12 betű/számjegy; magyar esetén `HU` + 8
  számjegy, és mellé a teljes `taxNumber` is kell). Hibás formátumra
  `400 INVALID_EU_VAT_ID` a válasz, és semmi nem jön létre. A Bizonylat csak
  a formátumot ellenőrzi: a VIES-t nem kérdezi le, így egy VIES-kiesés soha
  nem állítja meg a számlázást.
- **`client.thirdStateTaxId`** (magyar mezőnév:
  `harmadikOrszagbeliAdoazonosito`) az EU-n kívüli vevő adóazonosítója; a
  NAV-hoz `thirdStateTaxId`-ként megy (lásd a fenti táblázatot). Ennél is
  csak formai ellenőrzés van.
- **Közösségi adószám a `client.taxNumber` mezőben** — egy másik tagállam
  érvényes formátumú közösségi adószáma, pl. `"DE123456789"` vagy
  `"ATU12345678"` — `euVatId`-ként tárolódik: a magyar adószám csak
  számjegyekből áll, így ez egyértelmű. Ha a `taxNumber` és az `euVatId` két
  különböző közösségi adószámot tartalmaz, a kérés `400 INVALID_EU_VAT_ID`
  hibát kap.
- **A meglévő ügyfél felismerése**: ha magyar `taxNumber` érkezik, továbbra
  is csak az számít. Egyébként először az `euVatId`, majd a
  `thirdStateTaxId` alapján keresünk; ha nincs ilyen ügyfél, az e-mail/név
  szabályok jönnek, de csak olyan ügyfelekre, akiknek sem adószáma, sem
  közösségi adószáma, sem külföldi adóazonosítója nincs. A
  megtalált ügyfél, ha még nincs közösségi adószáma, megkapja a küldöttet;
  ha már más van neki, azt megtartja — mint a megtalált ügyfél minden más
  adatánál, a tárolt adat az irányadó (módosítás:
  `PATCH /public/v1/clients/:id`).
- **`client.country`** (`orszag`): kétbetűs ISO 3166-1 kód, kis- vagy
  nagybetűvel (a `de` `DE`-ként tárolódik); minden másra
  `400 INVALID_COUNTRY` a válasz. Alapértelmezés: `HU`, ezért külföldi
  vevőnél küldje el: ez az ország szerepel a számlán és a NAV-adatban. Lista:
  `GET /public/v1/reference/countries`.
- **NAV-adatszolgáltatás**: a közösségi adószámmal rendelkező, magyar adószám
  nélküli vevő `OTHER` státusszal, a közösségi adószámmal
  (`communityVatNumber`), névvel és címmel kerül a NAV-hoz; az EU-n kívüli
  adóazonosítóval rendelkező `OTHER` státusszal és `thirdStateTaxId`
  elemmel. Ha az ügyfél adószáma nem `HU`, hanem más betűkkel kezdődik, azt
  soha nem jelentjük magyar (belföldi) adószámként; ha a vevő `country`
  mezője nem `HU`, csak az `NNNNNNNN-N-NN` alakú, érvényes ellenőrző
  számjegyű adószámot.
- **EU-n kívüli adóazonosító a `client.taxNumber` mezőben** — betűvel
  kezdődő, nem közösségi adószám, pl. `"GB123456789"` vagy
  `"CHE-123.456.789"` — EU-n kívüli `client.country` mellett
  `thirdStateTaxId`-ként tárolódik, ahogy a közösségi adószám az `euVatId`
  mezőbe kerül; ha a kérés ettől eltérő `thirdStateTaxId`-t is küld,
  `400 INVALID_THIRD_STATE_TAX_ID`. EU-s, `HU` vagy hiányzó ország mellett
  `400 INVALID_TAX_NUMBER` a válasz. Adószámként soha nem tároljuk.
- **ÁFA-kategóriák külföldi értékesítéshez**: `EU_REVERSE_CHARGE`,
  `EU_GOODS_SUPPLY`, `EXPORT_GOODS`, `THIRD_COUNTRY_SUPPLY`, `OUT_OF_SCOPE` —
  ugyanazok, mint az irányítópulton, ugyanazokkal a NAV-kódokkal (EUFAD37,
  KBAET, EAM, HO, ATK). Minden tételes végponton elfogadottak: számla,
  piszkozat, díjbekérő, piszkozat tételeinek módosítása, árajánlat,
  előfizetés, termék és termékszinkron. `vatRate` nélkül az ilyen kategóriájú
  tétel vagy termék 0%-ot kap (az irányítópult is így párosítja őket); velük
  küldött `vatRate` csak 0 lehet (a NAV-nak magyar ÁFA nélkül jelentjük),
  különben `400 VAT_RATE_CATEGORY_MISMATCH`. Magyar értékek:
  `FORDITOTT_ADOZAS` / `EUFAD37`, `KOZOSSEGEN_BELULI` / `KBAET`,
  `TERMEKEXPORT` / `EAM`, `HARMADIK_ORSZAG` / `HO`,
  `TARGYI_HATALYON_KIVULI` / `ATK`.
- **Kategóriánkénti vevő-ellenőrzés nincs**: az irányítópulthoz hasonlóan az
  API sem utasítja el pl. az `EU_REVERSE_CHARGE` tételt közösségi adószám
  nélküli vevőnél. Hogy melyik kategória alkalmazandó és mit kell a számlán
  feltüntetni, a számlakibocsátó döntése; a szabályokról:
  [bizonylat.hu/eu-s-szamla](https://bizonylat.hu/eu-s-szamla) és
  [bizonylat.hu/forditott-adozas](https://bizonylat.hu/forditott-adozas).
- **Csak magyar ÁFA-kulcsok** (27%, 18%, 5%, 0% és a fenti kategóriák)
  érhetők el. Más tagállam ÁFA-kulcsának felszámítása az ottani
  magánszemélyeknek (OSS) nem támogatott.
- **Pénznem**: 14 pénznem (`GET /public/v1/reference/currencies`). Az
  `exchangeRate` nem kötelező: nélküle a kiállítás a teljesítés napjának
  (ennek hiányában a kiállítás napjának) MNB-árfolyamát veszi — ugyanaz a
  szabály, mint az irányítópulton —, kivéve, ha a cég a saját bankja vagy az
  EKB árfolyamát választotta; akkor kötelező megadni. Lásd lent: *Devizás
  számlák*.
- **Nyelv**: a számla PDF-je a vevő nyelvén készül — `client.emailLocale`
  (`nyelv`), amelyet az ügyfélnél tárolunk; ennek hiányában a cég
  dokumentumnyelvén (Beállítások), végül magyarul. 26 nyelv:
  `hu`, `en`, `de`, `ro`, `sr`, `lv`, `uk`, `bg`, `bs`, `da`, `el`, `et`, `fi`, `fr`, `hr`, `is`, `ja`, `lt`, `mk`, `nl`, `sk`, `sl`, `sq`, `sv`, `tr`, `ar`
  (az arab jobbról balra szedve). Az ÁFA-jelölések magyarul maradnak — ennek
  van jogi súlya —, mögöttük zárójelben a vevő nyelvén: „Fordított adózás
  (Btw verlegd)”. A kísérő e-mail a hívás felső szintű `emailLocale`
  mezőjének nyelvén, ennek hiányában az ügyfélnél tárolt nyelven megy, és a
  benne lévő link ezen a nyelven nyitja meg a nyilvános számlaoldalt. Ahol
  egy szöveg hiányzik, ott angol a tartalék; a magyartól, angoltól és
  némettől eltérő nyelvű e-mailek rövidek és sablonosak. A válaszban kapott
  `publicUrl` magyarul nyílik meg; a vevő nyelvéhez fűzze hozzá pl. a
  `?lang=en` paramétert (vagy a fenti kódok egyikét).

## Tesztelés — tesztcéggel

A valódi cég kulcsai élesek: minden sikeres `POST /public/v1/invoices` hívás
**valódi számlát** állít ki a sorozat következő sorszámával, és beküldi a NAV
**éles** Online Számla rendszerébe.

Az integráció valódi számla nélküli, teljes kipróbálásához hozzon létre egy
**tesztcéget** (cégváltó → Cég hozzáadása → „Tesztcég (NAV tesztkörnyezet)”):
- A NAV **tesztkörnyezetéhez** csatlakozik: az onlineszamla-test.nav.gov.hu
  felületen létrehozott technikai felhasználót a Beállítások → NAV kapcsolat
  oldalon adja meg, és indítsa el az ellenőrzést — amíg nem sikeres, a
  kiállítás `409 NAV_CREDENTIALS_NOT_VERIFIED` hibát ad. A cégnek a NAV
  tesztrendszerében is regisztrálva kell lennie a valódi adószámával; kitalált
  adószámmal az ellenőrzés NOT_REGISTERED_CUSTOMER hibával meghiúsul (lásd
  *Első lépések integrátoroknak*, 3. lépés). (Tesztkörnyezeti felhasználó
  valódi céghez nem használható, éles felhasználó tesztcéghez sem.)
- A tesztcégben létrehozott API-kulcsok csak a NAV tesztrendszerébe állítanak
  ki. Minden PDF-en „TESZT — nem valódi számla” jelölés, minden e-mail
  tárgyában `[TESZT]` előtag szerepel.
- A tesztcégben minden funkció, az API és a tömeges import is díjmentes.
- Egy tesztcég összesen legfeljebb **100 számlát** állíthat ki (a piszkozat és
  a díjbekérő nem számít bele, a sztornó és a helyesbítő igen). Utána minden
  kiállító hívás — létrehozás `draft: true` nélkül, `/issue`, `/convert`, sztornó,
  helyesbítés, ismétlődő számla — `409 SANDBOX_INVOICE_LIMIT_REACHED` hibát ad
  (`error.limit`, `error.used`), és nem jön létre bizonylat; piszkozat továbbra
  is létrehozható és szerkeszthető. Ha a teszteléshez több kell, írjon nekünk.
  A tulajdonosok 80 és 100 számlánál e-mailt kapnak.
- A tesztcég végleges: nem alakítható valódi céggé. Élesítéskor a valódi
  cégben hozzon létre API-kulcsot, és cserélje le a kulcsot.
- Az integráció minden hívása megjelenik az **API naplóban** (irányítópult →
  API oldal → API napló, vagy `GET /public/v1/logs`) a státusz- és
  hibakóddal együtt, így egy sikertelen teszthívás oka találgatás nélkül
  kideríthető. Csak metaadatot őrzünk, 30 napig; lásd lent: „Hívásnapló”.

## POST /public/v1/invoices

Számla létrehozása **és kiállítása** egyetlen hívással.

Küldjön `Idempotency-Key` fejlécet (UUID-t vagy a rendelés azonosítóját),
hogy az időtúllépés utáni újrapróbálás az első választ adja vissza, ne állítson
ki második számlát — lásd lent: *Idempotency-Key*.

### A kérés törzse

| Mező | Típus | Kötelező | Alapértelmezés | Megjegyzés |
|---|---|---|---|---|
| `clientId` | string (UUID) | **igen, ha nem küld `client`-et** | — | A vállalkozás egy meglévő ügyfelének azonosítója (`GET /public/v1/clients`, vagy egy korábbi számla `clientId` mezője). Az ügyfél tárolt nevét, címét, adószámát és nyelvét változatlanul használjuk — semmit nem egyeztetünk és nem írunk felül. **Vagy** a `clientId`, **vagy** a `client` mezőt küldje: mindkettő → `400 CLIENT_AND_CLIENT_ID`, egyik sem → `400 CLIENT_REQUIRED`, ismeretlen, archivált vagy másik vállalkozáshoz tartozó azonosító → `404`. Magyar mezőnév: `ugyfelId`. |
| `client` | objektum | **igen, ha nem küld `clientId`-t** | — | A vevő adatai: meglévő ügyfélhez társítjuk (lásd lent), vagy új ügyfelet hozunk létre. |
| `client.name` | string | **igen** (`client` esetén) | — | Vevő neve (magánszemély vagy cég) |
| `client.taxNumber` | string | nem | — | Magyar adószám; céges (B2B) vevőnél küldje. Meglévő ügyfelek felismerésére is szolgál. Ha más tagállam közösségi adószámát küldi ebben (pl. `"DE123456789"`), azt `client.euVatId`-ként tároljuk. A (csak számjegyekből álló) magyar adószám 8 számjegy vagy `NNNNNNNN-N-NN` legyen (tetszőleges tagolással), 1–5 közötti áfakóddal és területi kóddal, különben `400 INVALID_TAX_NUMBER` — a NAV elutasítaná a számlát. `HU`-tól eltérő `client.country` mellett (magyar áfaalanyként nyilvántartott külföldi cég) csak `NNNNNNNN-N-NN` alakban, érvényes ellenőrző számjeggyel fogadjuk; más számsorra `400 INVALID_TAX_NUMBER`: a külföldi adóazonosító a `client.thirdStateTaxId` (EU-n kívül) vagy a `client.euVatId` (EU) mezőbe való. Ide küldött, betűvel kezdődő EU-n kívüli azonosítót (`"GB123456789"`) EU-n kívüli ország mellett `client.thirdStateTaxId`-ként tárolunk, különben `400 INVALID_TAX_NUMBER`. |
| `client.euVatId` | string | nem | — | A vevő közösségi adószáma, pl. `"DE123456789"` (magyar mezőnév: `kozossegiAdoszam`). Ellenőrzése és tárolása ugyanaz, mint a `POST /public/v1/clients` hívásnál (csak formai, VIES nélkül: tagállami áfa-előtag, Görögországé `EL`; magyar csak a teljes `taxNumber` mellett; különben `400 INVALID_EU_VAT_ID`); `taxNumber` nélkül a meglévő ügyfél felismerésére is szolgál. EU-s számlázás: [bizonylat.hu/eu-s-szamla](https://bizonylat.hu/eu-s-szamla). |
| `client.thirdStateTaxId` | string | nem | — | EU-n kívüli vevő adóazonosítója, pl. japán cégszám, szerb PIB vagy svájci UID (magyar mezőnév: `harmadikOrszagbeliAdoazonosito`). 1–50 betű, számjegy, szóköz, `-` `.` `/`; EU-n kívüli `client.country` kell hozzá. Közösségi adószám, magyar adószám, hiányzó / `HU` / EU-s ország → `400 INVALID_THIRD_STATE_TAX_ID`. A NAV-hoz `OTHER` + `thirdStateTaxId`-ként megy; a számlán is szerepel. Lásd: *Vevőazonosítók és a NAV-adat*. |
| `client.groupMemberTaxNumber` | string | nem | — | Magyar áfacsoport tagjának saját adószáma (`NNNNNNNN-4-NN`, magyar mezőnév: `csoporttagAdoszam`), ha a `client.taxNumber` a csoportazonosító szám (áfakód 5); különben `400 INVALID_GROUP_MEMBER_TAX_NUMBER`. A NAV-hoz a `customerTaxNumber/groupMemberTaxNumber` elemben megy; a számlán is szerepel. |
| `client.email` | string | nem | — | A `sendEmail`-hez szükséges |
| `client.address` | string | nem | — | Utca, házszám. Ha megvan, küldje a teljes címet — lásd a bevált gyakorlatokat lent. |
| `client.city` | string | nem | — | Az `address` + `postalCode` mezőkkel együtt küldje |
| `client.postalCode` | string | nem | — | |
| `client.country` | string | nem | `"HU"` | Kétbetűs ISO 3166-1 kód, kis- vagy nagybetűvel (`GET /public/v1/reference/countries`); a gyakori hárombetűs kódokat (`HUN`, `DEU`) és a magyar/angol országneveket (`Magyarország`, `Germany`) átalakítjuk; minden másra `400 INVALID_COUNTRY`. Külföldi vevőnél küldje el. |
| `client.emailLocale` | `hu en de ro sr lv uk bg bs da el et fi fr hr is ja lt mk nl sk sl sq sv tr ar` | nem | — | A vevő nyelve, az ügyfélnél tároljuk: a számla PDF-je, a nyilvános számlaoldal és a vevőnek szóló e-mailek ezen a nyelven készülnek (ha nincs: a cég dokumentumnyelvén, végül magyarul). Más kódot elutasítunk (`400`); ahol egy szöveg hiányzik, ott angolul. Lásd: *EU-s és külföldi vevők*. |
| `lines[]` | tömb | **igen** (1–100) | — | Tétel-formátumok lent |
| `currency` | `"HUF"` vagy `EUR USD RON RSD UAH JPY TRY BGN ISK GBP CHF PLN CZK` egyike | nem | `"HUF"` | Nem HUF pénznem esetén megadott árfolyam vagy automatikus MNB-lekérés — lásd lent |
| `exchangeRate` | string | nem; BANK/EKB esetén kötelező | — | 1 egység `currency` hány forint, pl. `"392,55"`. `.` és `,` is elfogadott |
| `paymentMethod` | `"BANK_TRANSFER" \| "CASH" \| "CARD" \| "VOUCHER" \| "COD" \| "OTHER"` | nem | `"BANK_TRANSFER"` | Kártyás fizetésnél `"CARD"`, utánvétnél `"COD"` |
| `issueDate` | dátum (`YYYY-MM-DD`) | nem | ma | Kiállítás dátuma. Nem lehet a mai napnál (budapesti idő) későbbi — `400 ISSUE_DATE_IN_FUTURE`; piszkozat hordozhat későbbit, azt a `/issue` ellenőrzi. Egyik dátum sem lehet 2010-01-01 előtti, ennél korábbit a NAV nem fogad el — `400 DATE_TOO_EARLY` |
| `performanceDate` | dátum | nem | issueDate | Teljesítés dátuma. Nem lehet 2010-01-01 előtti (`400 DATE_TOO_EARLY`) |
| `dueDate` | dátum | nem | issueDate + az ügyfél fizetési határideje, ha nincs, a cég alapértelmezett fizetési határideje (Beállítások), ha az sincs, 8 nap (naptári nap) | Fizetési határidő. Ha `paymentStatus` `"PAID"` és nincs megadva, akkor a kiállítás dátuma — kiegyenlített számlán nincs jövőbeli határidő. Nem lehet 2010-01-01 előtti (`400 DATE_TOO_EARLY`) |
| `notes` | string | nem | — | Megjelenik a számlán |
| `sendEmail` | boolean | nem | cégbeállítás (be) | A számla PDF elküldése a `client.email` címre (aszinkron, nem lassítja a választ). Ha nem adja meg, a cég *Automatikus számla e-mail* beállítása dönt, amely bekapcsolt, hacsak a cég ki nem kapcsolta. `false` esetén nem küldünk e-mailt. |
| `pricesIncludeVat` | boolean | nem | `false` | Ha `true`, minden tétel `unitPrice` értéke **bruttó** (ÁFÁ-val növelt) fogyasztói árként értelmeződik, a nettó + ÁFA visszaszámolásra kerül — így a számla végösszege megegyezik a vevő által látott árral. Lásd „Nettó vs. bruttó árak" lent. |
| `invoicePrefix` | string | nem | a cég beállított előtagja, annak hiányában `SZ` | Számlatömb (sorszám-előtag), 1–10 betű/szám. Minden különböző előtag saját, kihagyásmentes éves sorszámozást kap — pl. `"WS1"` → `WS1-2026-000001`. A futó sorszám 6 számjegyű, kivéve, ha a vállalkozás az adott tömbhöz 3–8 számjegyet választott a vezérlőpulton (Beállítások → Számlatömbök), pl. 4 jegynél `WS1-2026-0001` — a számlaszámot ne rögzített hosszúságúként dolgozza fel. Webshoponként / értékesítési csatornánként külön előtagot használva a sorszámozás elkülöníthető egy fiókon belül. A sztornószámla automatikusan az eredeti számla tömbjében marad. A díjbekérők (`PROFORMA`) mindig saját `DB` sorozatban kapnak sorszámot; az előtag megmarad a belőlük később készülő számlához; a `DB` előtag számlához nem használható (`RESERVED_SERIES_PREFIX`). Másik programból hoz át tömböt? A folytatást (és a számjegyek számát) egyszer, a vezérlőpulton állítsa be (Beállítások → Számlatömbök, vagy számla űrlap → Számlatömb → Új tömb → folytatás másik programból); az ezzel az előtaggal itt kiállított számlák onnan folytatódnak. |
| `paymentStatus` | `"UNPAID" \| "PAID"` | nem | `"UNPAID"` | A számla kiegyenlítettként való létrehozása. **Kártyás/online fizetésnél küldjön `"PAID"` értéket** (Stripe, SimplePay, Barion…), amikor a pénz már megérkezett. Ekkor a számla soha nem jelenik meg kintlévőségként, nem készül rá fizetési emlékeztető, a vevőnek küldött e-mail pedig visszaigazolás lesz fizetési felszólítás helyett. Figyelem: a `paymentMethod: "CARD"` csak azt rögzíti, *hogyan* fizetnek, nem azt, hogy *ki van fizetve*. |
| `emailLocale` | `hu en de ro sr lv uk bg bs da el et fi fr hr is ja lt mk nl sk sl sq sv tr ar` | nem | az ügyfélnél tárolt nyelv, végül `"hu"` | Ennek az egy e-mailnek a nyelve. A PDF nyelvét nem változtatja — azt a `client.emailLocale` adja. |
| `invoiceType` | `"STANDARD" \| "PROFORMA" \| "PREPAYMENT"` | nem | `"STANDARD"` | `"PROFORMA"` számla helyett díjbekérőt állít ki: `DB` sorszámozás, NAV-jelentés nélkül. Lásd lent: *Díjbekérő és piszkozat*. `"PREPAYMENT"` egy hívással előlegszámlát állít ki — a számlatömbben kap sorszámot, a NAV-nak minden tétele előlegtételként megy, ugyanaz a bizonylat, mint a `/convert` `"to": "PREPAYMENT"` eredménye. Minden más mező úgy működik, mint számlánál (`paymentMethod: "CASH"`, `paymentStatus`, `paidAmount`, `draft`…); a `performanceDate` alapértéke a kiállítás dátuma. Lásd lent: *Előleg és végszámla*. Magyar érték: `ELOLEGSZAMLA`. |
| `draft` | boolean | nem | `false` | `true` esetén csak piszkozat készül — sorszám, NAV és e-mail nélkül. Kiállítás: `POST /public/v1/invoices/:id/issue`. |
| `advanceDeductions[]` | tömb (1–20) | nem | — | **Csak végszámlán** (`invoiceType` `STANDARD`, nem `draft: true` mellett és nem gyűjtőszámlán): ugyanannak az ügyfélnek, ugyanabban a pénznemben kiállított előlegszámlái, amelyeket be kell számítani, `[{ "invoiceId": "…", "amount": "5000" }]`. Mindegyikhez a szerver hozzáfűzi a felület által is írt beszámító tételt (tételeket) — `"Előleg beszámítása — <előlegszámla sorszáma>"`, mennyiség −1, az előlegszámla minden ÁFA-kategóriájához és -kulcsához egy-egy tétel —, amelyek a NAV-hoz előlegtételként mennek. Az `amount` (bruttó, opcionális) ennyit számít be belőle; ha nincs megadva: mindazt, ami hátravan (`advanceRemaining`). A válaszban ilyenkor `advanceDeductions` is szerepel a hozzáadott tételekkel. Lásd lent: *Előleg és végszámla*. Magyarul: `eloleglevonasok` (`szamlaId`, `osszeg`). |
| `invoiceCategory` | `"NORMAL" \| "AGGREGATE"` | nem | `"NORMAL"` | `"AGGREGATE"` **gyűjtőszámlát** állít ki (NAV `invoiceCategory` AGGREGATE): több, eltérő napon történt teljesítés egy számlán, minden tételnél saját `lines[].performanceDate`. Minden tételnél kötelező (`422 AGGREGATE_LINE_DATE_REQUIRED`); a számla `performanceDate` mezője ekkor a tételek legkésőbbi dátuma lesz, ahogy a NAV előírja (a küldött értéket figyelmen kívül hagyjuk). Csak `STANDARD` és `PROFORMA` (`422 AGGREGATE_INVOICE_TYPE_NOT_ALLOWED`). Sztornója és helyesbítője is gyűjtőszámla, a tételek megtartják dátumukat. Időszak-korlátot nem alkalmazunk — hogy a gyűjtőszámla alkalmazható-e, és milyen időszakra, azt a könyvelő tudja megítélni. Magyar név: `szamlaKategoria`, érték: `GYUJTOSZAMLA`. A számla erőforrásban visszakapja (`GET /public/v1/invoices/:id`), a tételek dátumát a `GET …/lines` adja. |
| `lines[].performanceDate` | dátum (`YYYY-MM-DD`) | gyűjtőszámlán **igen** | — | A tétel teljesítési dátuma (magyar név: `teljesitesDatuma`). `NORMAL` számlán figyelmen kívül marad. A `PATCH /public/v1/invoices/:id` és a `POST …/correct` tételeiben is megadható; helyesbítésnél a dátum nélkül küldött tétel az azonos eredeti tétel dátumát kapja. |
| `conventionalInfo` | objektum | nem | — | NAV *conventionalInvoiceInfo* (egyezményes adatok): a PDF-en a NAV saját megnevezésével feltüntetjük, és a NAV-nak is jelentjük. Kulcsok, mindegyik szöveglista (egyetlen szöveg egyelemű listának számít): `orderNumbers` (Megrendelésszám), `deliveryNotes` (Szállítólevél szám), `contractNumbers` (Szerződésszám), `projectNumbers` (Projektszám), valamint `shippingDates`, `supplierCompanyCodes`, `customerCompanyCodes`, `dealerCodes`, `costCenters`, `generalLedgerAccountNumbers`, `glnNumbersSupplier`, `glnNumbersCustomer`, `materialNumbers`, `itemNumbers`. Értékenként legfeljebb 100 karakter (a NAV korlátja), kulcsonként legfeljebb 20 érték; az üres értékeket elhagyjuk. Ismeretlen kulcs vagy hosszabb érték → `400 INVALID_CONVENTIONAL_INFO`. A `PATCH /public/v1/invoices/:id` is fogadja (`null` törli). Sztornó és helyesbítés az eredetiét viszi tovább. Magyar név: `egyezmenyesAdatok`. A számla erőforrásban visszakapja. Példa: `{ "orderNumbers": ["WEB-1001"], "deliveryNotes": ["SZL-55"] }` |
| `lines[].productCodes` | tömb | nem | a SKU / `productId` termékéé | NAV *productCodes*: `[{ "category": "VTSZ", "value": "84713000" }]`. `category`: `VTSZ`, `SZJ`, `KN`, `AHK`, `CSK`, `KT`, `EJ`, `TESZOR`, `OWN` (a vállalkozás saját kódja), `OTHER`. `value`: `OWN` esetén bármilyen szöveg 255 karakterig, a többinél 2–30 nagybetű vagy számjegy (a szóközöket, pontokat és kötőjeleket elhagyjuk, a betűket nagybetűsítjük: `"8471 30 00"` → `84713000`). Legfeljebb 10. Hibás → `400 INVALID_PRODUCT_CODE`. Sosem kötelező — hogy egy termékhez melyik kód kell, azt a könyvelő tudja megítélni. Magyar név: `termekkodok` (`termekkodFajta`, `termekkodErtek`). |
| `lines[].lineNature` | `"PRODUCT" \| "SERVICE" \| "OTHER"` | nem | a termékéé, különben nincs megadva | NAV *lineNatureIndicator* (Termékértékesítés / Szolgáltatás nyújtás / Egyéb, nem besorolható). Megadás nélkül (`null`) nem jelentjük. Magyar név: `tetelJelleg`. |
| `lines[].intermediatedService` | logikai | nem | a termékéé, különben `false` | NAV *intermediatedService*: `true` esetén a tétel közvetített szolgáltatásként szerepel (Számviteli tv. 3. § (4) 1.); csak `true` értéket jelentünk. Magyar név: `kozvetitettSzolgaltatas`. |
| `lines[].dataErasureCodes` | szöveglista | nem | — | **Adattörlő kódok** (726/2020. (XII. 31.) Korm. rendelet), amelyeket a tételen adnak át a fogyasztónak — például használt telefon vagy számítógép eladásakor. Minden kódot egy-egy *additionalLineData* elemként jelentünk a NAV-nak, `A10000_VEGLEGES_ADATTORLO_KOD` adatnévvel (NAV közlemény, 2024.10.15), és a PDF-en a tétel alatt is feltüntetjük. Formátum: 16 karakter (nagybetű vagy számjegy), négyesével kötőjellel tagolva (`UH59-7VGH-G3UE-ITA6`; a szóközt, a kisbetűt és a hiányzó kötőjelet rendbe tesszük). A NAV ellenőrző számjegyével (CDV) ellenőrizzük: elírt vagy egy tételen ismétlődő kód → `400 INVALID_DATA_ERASURE_CODE`. Csak a tételről vesszük (termékről soha); a sztornó nem ismétli meg a kódokat; díjbekérőből készült számla megtartja őket. A `GET …/lines` visszaadja. Magyar név: `adattorloKodok`. |
| `deliveryPeriodStart`, `deliveryPeriodEnd` | dátum | nem | — | Elszámolási időszak: a számlával érintett időszak első és utolsó napja, együtt vagy egyik sem (`400 DATE_RANGE_INVALID`). A `performanceDate`-et nem változtatja meg. Lásd: *NAV-jelölések*. |
| `periodicalSettlement` | boolean | nem | `false` | Időszakos elszámolás, a NAV-nak jelentve. Lásd: *NAV-jelölések*. |
| `bankAccountId` | uuid | nem | a számla pénznemének alapértelmezett bankszámlája | A cég egyik bankszámlája (azonosítók: `GET /public/v1/company` → `bankAccounts`). A PDF-en ez szerepel, és ez kerül a NAV-nak küldött számlaadatokba eladói bankszámlaszámként. Megadás nélkül a számla pénznemében alapértelmezettnek jelölt számla, ennek hiányában a bármely pénznemre alapértelmezett számla. Más cég számlája → `404 BANK_ACCOUNT_NOT_FOUND`. Magyar név: `bankszamlaId`. |

### Tétel-formátumok

**Beágyazott (elsődleges forma — küldje a saját kosáradatait változtatás nélkül):**

```json
{ "nev": "Termék neve", "mennyiseg": 2, "egysegar": 4990, "afaKulcs": 27, "egyseg": "db" }
```

(Angolul: `{ "name": …, "quantity": …, "unitPrice": …, "vatRate": …, "unit": … }`.)

| Mező | Kötelező | Alapértelmezés | Megjegyzés |
|---|---|---|---|
| `name` | igen (kivéve, ha `sku` meg van adva) | — | |
| `quantity` | **igen** | — | nullától eltérő szám (levonásnál negatív), legfeljebb 4 tizedesjeggyel (`400 INVALID_NUMBER`). A számok JSON-számként vagy tizedes szövegként küldhetők; üres szöveg vagy `"0x10"` nem. 9 999 999 999 999,99 feletti összeg (tételen vagy végösszegben) → `400 AMOUNT_OUT_OF_RANGE` |
| `unitPrice` | igen (kivéve, ha a SKU-termékhez tartozik alapár) | — | egységár; alapból **nettó**, `pricesIncludeVat` esetén **bruttó** |
| `vatRate` | nem | a kategória kulcsa, különben a cég beállított alapértelmezése (lásd lent) | százalék: 27, 18, 5 vagy 0 — ezekkel a kulcsokkal jelentjük a kategóriákat a NAV-nak. `vatCategory`-val együtt a kategória kulcsa kell legyen; egyedül küldve a tétel az ehhez a kulcshoz tartozó kategóriát kapja (27 STANDARD, 18 REDUCED, 5 REDUCED_MORE), a 0-hoz pedig `vatCategory` is kell, hacsak az alapértelmezett kategória nem 0%-os. Különben `400 VAT_RATE_CATEGORY_MISMATCH` |
| `unit` | nem | `"db"` | pl. db, óra, kg |
| `description` | nem | — | A név alatti kiegészítő szöveg (változat, méret, időszak…). A PDF-en a név alatt jelenik meg, a NAV-hoz pedig **a névvel együtt**, `név – leírás` formában kerül (a NAV 512 karakteres korlátjára vágva). A 2026 októbere előtt kiállított számlák NAV-szövege nem változik: azokon a leírás a név helyett szerepelt. |
| `vatCategory` | nem | a cég beállított alapértelmezése | `STANDARD`, `REDUCED`, `REDUCED_MORE`, `ZERO`, `AAM`, `TAM`, `EU_REVERSE_CHARGE` (EU-s B2B szolgáltatás, NAV EUFAD37), `EU_GOODS_SUPPLY` (Közösségen belüli termékértékesítés, KBAET), `EXPORT_GOODS` (termékexport, EAM), `THIRD_COUNTRY_SUPPLY` (EU-n kívül teljesített ügylet, HO), `OUT_OF_SCOPE` (ÁFA hatályán kívül, ATK), `DOMESTIC_REVERSE_CHARGE` (belföldi fordított adózás; a vevőnek magyar adószám kell, különben `422 DOMESTIC_REVERSE_CHARGE_BUYER` — lásd: *NAV-jelölések*), valamint a különbözet szerinti szabályozás: `MARGIN_TRAVEL_AGENCY` (Utazási irodák), `MARGIN_SECOND_HAND` (Használt cikkek), `MARGIN_ARTWORK` (Műalkotások), `MARGIN_ANTIQUES` (Gyűjteménydarabok és régiségek) egyike — ez utóbbiakat a NAV-nak *marginSchemeIndicator* jelöléssel, a tételen áfaösszeg nélkül jelentjük. `vatRate` nélkül a tétel a kategória saját kulcsát kapja (STANDARD 27, REDUCED 18, REDUCED_MORE 5, a többi 0%) — a NAV-nak ezt jelentjük, bármit mond a tétel, ezért eltérő `vatRate` nem küldhető (`VAT_RATE_CATEGORY_MISMATCH`). Az `EXEMPT` megszűnt: a NAV-nál nincs rá kód, ezért kiállításkor `LEGACY_VAT_CATEGORY` hibát ad |

### ÁFA-alapértelmezések (fontos)

Ha egy tételnél nincs `vatRate`/`vatCategory`, a **cég beállított
alapértelmezett ÁFÁ-ja** érvényesül (egyszer állítandó be a Bizonylatban a
Beállítások → céges profil alatt). Így egy alanyi adómentes (AAM/0%)
vállalkozás akkor is helyes 0%-os számlákat kap, ha Ön sosem küld
ÁFA-mezőket — nem kell ismernie vagy követnie az egyes cégek adóstátuszát.
Csak akkor küldjön `vatRate`/`vatCategory` értéket, ha tételenként felül
akarja bírálni. A beépített végső alapértelmezés (ha a cég semmit sem
állított be): 27% STANDARD.

### Devizás számlák (fontos)

Bármely nem forintos pénznemnél megadható az `exchangeRate`:
1 egység adott pénznem hány forintot ér, pl. EUR esetén `"392,55"`.
Tizedesjelként a `,` és a `.` is elfogadott.

Ha nincs megadva, a kiállítás a teljesítési dátumhoz (ennek hiányában a
kiállítás dátumához) tartozó vagy azt megelőző MNB-árfolyamot kéri le.
BANK/EKB beállítás esetén saját árfolyam szükséges. A kiállításkor mentett
árfolyam újrapróbáláskor sem változik mai árfolyamra. Sikertelen lekérés vagy
érvénytelen árfolyam esetén a kiállítás sorszámfoglalás előtt leáll:
**422**, `INVOICE_EXCHANGE_RATE_UNAVAILABLE`:

```json
{
  "error": {
    "code": "INVOICE_EXCHANGE_RATE_UNAVAILABLE",
    "message": "The EUR/HUF exchange rate is outside NAV limits"
  }
}
```

**Hogy melyik árfolyamot kell küldeni, az a vállalkozás döntése, nem az
integrátoré.** Az Áfa tv. 80. §/80/A. §-a szerint a számlavezető bank eladási
árfolyama, az MNB vagy az EKB árfolyama használható — az utóbbi kettőhöz
előzetes bejelentés kell a NAV felé. Ha másik cég nevében integrál, kérdezze
meg tőlük (vagy a könyvelőjüktől), melyiket használják, ne válasszon helyettük.
HUF számlánál semmit nem kell küldeni, az árfolyam mindig 1.

### Fizetési módok

A `paymentMethod` a NAV saját készletére képződik le. A `"COD"` (utánvét)
a NAV felé `OTHER` értékkel kerül be, mert a NAV-nak nincs utánvét kódja —
a számlázáskor még nem tudható, hogy a futár készpénzt vagy kártyát fogad-e.

### Nettó vs. bruttó árak

Alapértelmezetten a `unitPrice` **nettó** (az ÁFA rákerül), tehát 27%-os
cégnél a 10000-es `unitPrice` 12700-as bruttót eredményez. Ha az árai a
vevő által elfogadott végösszegek (webshopos fizetésnél tipikus), küldje a
`"pricesIncludeVat": true` mezőt a kérés tetején — ekkor a Bizonylat minden
`unitPrice`-t bruttóként kezel és visszaszámolja a nettót + ÁFÁ-t, így a
számla végösszege bármilyen ÁFA-kulcs mellett megegyezik a megjelenített
árral. 0%-nál (AAM) nettó = bruttó, ott a kapcsolónak nincs hatása.

**SKU alapján (opcionális — előzetes katalógus-szinkront igényel, lásd lent):**

```json
{ "cikkszam": "SKU-123", "mennyiseg": 2 }
```

A név, egységár, ÁFA-kulcs/kategória és egység a szinkronizált termékből
töltődik; bármely beágyazott mező tételenként továbbra is felülírja őket.

### Válasz — 201

```json
{
  "data": {
    "id": "9c0e…",
    "invoiceNumber": "2026-00042",
    "status": "ISSUED",
    "navStatus": "PENDING",
    "currency": "HUF",
    "netTotal": "11470.00",
    "vatTotal": "3096.90",
    "grossTotal": "14566.90",
    "issueDate": "2026-07-21T00:00:00.000Z",
    "dueDate": "2026-07-29T00:00:00.000Z",
    "clientId": "5b1a…",
    "publicUrl": "https://app.bizonylat.hu/i/7f3d…",
    "publicPdfUrl": "https://api.bizonylat.hu/api/v1/public/invoices/7f3d…/pdf"
  }
}
```

- **A `publicUrl` a vevőnek szánt számlaoldal** (belépés nélkül elérhető):
  márkázott összegzés, tételek, fizetési tudnivalók és PDF-letöltés gomb.
  **Fizetés után irányítsa ide a vevőt** — ez a szándék szerinti „íme a
  számlája" céloldal.
- A `publicPdfUrl` közvetlenül letölti a PDF-et (Content-Disposition:
  attachment), ha inkább saját visszaigazoló oldalt használ letöltő linkkel.
- `cashRounding` (a `/issue` és a `/convert` válaszában is): `null`, vagy
  `CASH` fizetési módú, `HUF` pénznemű számlán, ha a bruttó végösszeg nem
  0-ra vagy 5-re végződik, az 5 forintos készpénzes kerekítés:
  `{ "roundingAmount": "-2.34", "payableAmount": "1575.00" }`. Automatikus; a
  végösszegek és a NAV-adatok nem változnak. Lásd a számla objektumnál:
  *Készpénzes kerekítés*.

A NAV-beküldés aszinkron: a `navStatus` `PENDING`-ként indul, és
`DONE` (a NAV befogadta) vagy `ABORTED` / `REJECTED` lesz — ha követnie kell, kérdezze le a
`GET /public/v1/invoices/:id` végpontot. A számla jogilag azonnal kiállítottnak
minősül.

## GET /public/v1/invoices/:id

Visszaadja egy számla `id`, `invoiceNumber`, `status`, `navStatus`,
`paymentStatus` mezőit, összegeit, dátumait és `publicUrl`-jét. A
NAV-folyamat követésére használható.

A `subscriptionId` mezőben az az előfizetés szerepel, amelyből a számla
készült — egyszeri számlánál `null`. Az `invoiceType` a bizonylat típusa
(`STANDARD`, `PROFORMA`, `PREPAYMENT`, …), a `sourceProformaId` pedig
annak a díjbekérőnek az azonosítója, amelyből az átalakított bizonylat
készült. Emellett a `clientId`, `clientName`, `createdAt`, `updatedAt` és
`paidAt` mezőt is tartalmazza — a teljes mezőlista lent, *A számla objektum*
résznél található.

**Dátumok a válaszokban:** a csak dátumot tartalmazó mezők (`issueDate`,
`dueDate`, …) UTC éjféli ISO időbélyegként érkeznek, pl.
`"2026-07-21T00:00:00.000Z"`; a naptári dátum az első 10 karakter. A
kérésekben egyszerű `ÉÉÉÉ-HH-NN` formátumot fogadunk.

## PATCH /public/v1/invoices/:id/payment-status

Számla fizetettre állítása (vagy vissza fizetetlenre) — pl. amikor az Ön
rendszerében megerősítik a banki átutalás beérkezését. A Bizonylat felülete
automatikusan szinkronban marad.

Előfizetéses számlánál az azonosítót előbb a
`GET /public/v1/subscriptions/:id/invoices` végponttal kérdezze le.

**Kártyás fizetésnél egy hívás elég.** A `POST /public/v1/invoices` ugyanazt
a `paidAmount` / `paidAt` / `paymentReference` hármast fogadja, így a
fizetéskor kiegyenlített számla egyetlen kérésben létrehozható, kiállítható
és rendezhető — a tranzakcióazonosítóval együtt. Ezt a végpontot akkor
használja, ha a fizetés a számla kiállítása **után** érkezik.

```json
{
  "paymentStatus": "PAID",
  "paidAmount": 49000,
  "paidAt": "2026-08-21T10:30:00Z",
  "reference": "pi_3QabcdEfGh",
  "paymentMethod": "CARD"
}
```

| Mező | Kötelező | Megjegyzés |
|---|---|---|
| `paymentStatus` | igen | `"UNPAID"`, `"PARTIAL"` vagy `"PAID"`. |
| `paidAmount` | nem | Valódi fizetési tételt rögzít a számlához. Enélkül csak az állapot változik — összeg és dátum nélkül, így nincs mihez egyeztetni. Szám vagy (nem üres) tizedes szöveg; legfeljebb 9 999 999 999 999,99 (`400 AMOUNT_OUT_OF_RANGE`). A `POST /public/v1/invoices` hívásban a kiállítás előtt ellenőrizzük, és nem lehet 0 (`400 INVALID_NUMBER`). |
| `paidAt` | nem | ISO 8601. Alapértelmezés: most. Nem lehet jövőbeli nap (budapesti idő), és nem lehet 90 napnál korábbi a számla keltéhez képest — különben 422 `PAID_AT_IN_FUTURE` / `PAID_AT_TOO_EARLY`. |
| `reference` | nem | Az Ön oldali fizetésazonosító — Stripe `pi_…`, banki tranzakcióazonosító. Ez teremti meg a kapcsolatot a Bizonylat-számla és az azt kiegyenlítő fizetés között. |
| `paymentMethod` | nem | Alapértelmezés `"CARD"`. |

Válasz: `{ "data": { "id", "invoiceNumber", "paymentStatus", "paymentId" } }` —
a `paymentId` `null`, ha nem küldött `paidAmount` mezőt.

A `paidAmount` és `"PAID"` együtt elküldi a vevőnek a „fizetés
beérkezett” visszaigazoló e-mailt is, ha a felhasználó ezt bekapcsolta a
Beállításokban (alapértelmezés: kikapcsolva). A csak állapotot küldő hívások
változatlanul működnek.

```json
{ "paymentStatus": "PAID" }
```

Elfogadott értékek: `UNPAID`, `PARTIAL`, `PAID`. Válasz:
`{ "data": { "id", "invoiceNumber", "paymentStatus" } }`.

## Díjbekérő és piszkozat

A `POST /public/v1/invoices` két további, opcionális mezőt fogad. Aki egyiket
sem küldi, pontosan a fent leírt működést kapja.

- **`"invoiceType": "PROFORMA"`** számla helyett **díjbekérőt** készít. Ez
  saját `DB` sorozatban kap sorszámot (`DB-2026-000001`), a NAV-nak **nem**
  jelentjük (a `navStatus` `null` marad), és a PDF-en szerepel, hogy nem
  számla. Ettől még kiállított bizonylat, és `sendEmail: true` mellett
  e-mailben is elmegy — így kérhet banki átutalást. A számlához hasonlóan
  **ellenőrzött NAV-kapcsolat** kell hozzá (a felületen Beállítások → NAV;
  tesztcégnél ellenőrzött *teszt* hitelesítő adatok): enélkül a válasz
  `409 NAV_CONNECTION_REQUIRED`. A vele küldött
  `invoicePrefix` megmarad, és a belőle később készülő számla abban a
  tömbben kap sorszámot. Alapértelmezés: `"STANDARD"` (normál számla).
- **`"draft": true`** csak piszkozatot ment: nincs sorszám, nincs NAV,
  nincs e-mail, nincs nyilvános link. A válaszban `"status": "DRAFT"`,
  `"invoiceNumber": null` és `"publicUrl": null` szerepel. Később a
  `POST /public/v1/invoices/:id/issue` végponttal állítható ki; addig a
  felületen szerkeszthető vagy törölhető. Piszkozathoz `paidAmount` nem
  küldhető (400). Alapértelmezés: `false`.

A kettő együtt is használható: `{ "invoiceType": "PROFORMA", "draft": true }`
egy piszkozat díjbekérő.

## POST /public/v1/invoices/:id/issue

Kiállít egy piszkozatot — ugyanaz a lépés, ugyanazokkal az ellenőrzésekkel
és hibákkal, mint a felület Kiállítás gombja: sorszámot kap, a NAV-nak
beküldjük (kivéve, ha díjbekérő), és a PDF eltárolódik.

```json
{ "sendEmail": true }
```

| Mező | Kötelező | Megjegyzés |
|---|---|---|
| `sendEmail` | nem | A PDF elküldése az ügyfél eltárolt e-mail-címére. Ha nem adja meg: a cégbeállítás (alapból bekapcsolt). |
| `emailLocale` | nem | Az e-mail nyelve. Alapértelmezés az ügyfélnél eltárolt nyelv, annak hiányában magyar. |

Válasz — **200**: ugyanaz a formátum, mint a létrehozásnál (`id`,
`invoiceNumber`, `status`, `navStatus`, összegek, dátumok, `publicUrl`,
`publicPdfUrl`), kiegészítve az `invoiceType`, `paymentStatus` és
`sourceProformaId` mezőkkel.

Ami nem piszkozat (már kiállított, sztornózott), azt **409**
`INVOICE_NOT_DRAFT` hibával utasítjuk el. Egy bizonylat soha nem kap két
sorszámot, így a hívás biztonságosan megismételhető.

## POST /public/v1/invoices/:id/convert

Ha a díjbekérőre beérkezett a pénz: egy **kiállított díjbekérőből**
elkészíti a valódi bizonylatot, kiállítja (a NAV-nak ugyanúgy jelentjük,
mint bármely számlát), és kérésre e-mailben elküldi. Maga a díjbekérő nem
változik; az új bizonylat hivatkozik rá (`sourceProformaId`).

```json
{ "to": "INVOICE", "sendEmail": true, "markSourcePaid": true }
```

Az előleg november 3-án érkezett, az előlegszámla ma készül:

```json
{ "to": "PREPAYMENT", "markSourcePaid": true, "performanceDate": "2026-11-03" }
```

| Mező | Kötelező | Megjegyzés |
|---|---|---|
| `to` | **igen** | `"INVOICE"` — számla a díjbekérő ügyfelével, tételeivel, pénznemével és fizetési módjával. `"PREPAYMENT"` — előlegszámla: ugyanaz az átalakítás, mint a felület „Előlegszámla készítése” gombja, de azonnal kiállítva. |
| `sendEmail` | nem | A kiállított bizonylat elküldése az ügyfélnek. Ha nem adja meg: a cégbeállítás (alapból bekapcsolt). |
| `markSourcePaid` | nem | A díjbekérő fizetettre állítása ugyanebben a hívásban. Ha a díjbekérő fizetett (vagy azzá válik), az új bizonylat is fizetettként készül: soha nem jelenik meg kintlévőségként, nem kap fizetési emlékeztetőt, és az e-mail nyugtázó, nem fizetési felszólítás. Alapértelmezés `false`. |
| `exchangeRate` | nem | Csak devizás `INVOICE` esetén: 1 egység forintban, ha a cég a saját bankja vagy az EKB árfolyamát alkalmazza. Enélkül az árfolyam az új számla dátumára kerül meghatározásra, mint létrehozáskor. |
| `emailLocale` | nem | Mint az `/issue` végpontnál. |
| `performanceDate` | nem | Az új bizonylat teljesítési dátuma, `ÉÉÉÉ-HH-NN` — előlegszámlánál **az előleg beérkezésének napja**. Nem lehet a mai napnál (budapesti idő) későbbi és egy évnél régebbi, különben **422** `PERFORMANCE_DATE_INVALID` (`error.reason`: `IN_FUTURE`, `TOO_EARLY`, `INVALID_DATE`; `AGGREGATE_INVOICE` gyűjtőszámla-díjbekérőből készülő számlánál, amelynek dátuma a tételeiből adódik). A kiállítás dátuma a mai nap marad. `markSourcePaid: true` mellett a fizetést is rögzítjük az új bizonylaton, erre a napra (`paidAt`). Ha nincs megadva: a mai nap, mint eddig. Magyarul: `teljesitesDatuma`. |

Az új bizonylatot ma állítjuk ki, és ha a díjbekérő `invoicePrefix`
megadásával készült, abban a tömbben kap sorszámot. A teljesítés dátuma a
mai nap, vagy a megadott `performanceDate`. Devizás számla `exchangeRate`
nélkül a teljesítési dátumának árfolyamát kapja, mint létrehozáskor; az
előlegszámla a díjbekérő árfolyamát viszi tovább.

**Előlegszámla vagy számla?** Ez a cégtől és az ügylettől függ (például
attól, hogy a pénz beérkezésekor a termék vagy szolgáltatás teljesült-e
már). Adózási kérdés, amelyet a Bizonylat nem dönt el helyettük, ezért
mindkettőt felkínáljuk — **a `to` kiválasztása előtt kérdezze meg a cég
könyvelőjét, melyik vonatkozik rá.**

Válasz — **201**: ugyanaz a formátum, mint az `/issue` végpontnál.

**Idempotens.** Egy díjbekérőből pontosan egy bizonylat készül. Az ismételt
hívás — webhook-újrapróbálás, dupla kattintás — nem hoz létre semmit, hanem
**409** `PROFORMA_ALREADY_CONVERTED` választ ad, a `data` mezőben az első
hívás által létrehozott bizonylattal (ugyanabban a formátumban, mint a 201),
az `error.invoiceId` mezőben pedig annak azonosítójával. Kezelje sikerként,
és tárolja el a `data.id` értéket. Az egyidejű hívások sorban futnak, így két
párhuzamos újrapróbálás is csak egy bizonylatot eredményez.

További hibák: **422** `PERFORMANCE_DATE_INVALID` (lásd `performanceDate`),
**409** `NOT_A_PROFORMA` (az azonosító nem díjbekérő),
**409** `PROFORMA_NOT_ISSUED` (még piszkozat — előbb állítsa ki), **404**
(ismeretlen azonosító vagy másik cég bizonylata), valamint ugyanazok a
kiállítási hibák, mint létrehozáskor (`PLAN_LIMIT_REACHED`,
`INVOICE_EXCHANGE_RATE_UNAVAILABLE`, nem ellenőrzött NAV hitelesítő adatok).
Az elutasított átalakítás semmit nem hagy maga után, így az ok elhárítása
után egyszerűen újra hívható.

## Recept — előreutalás WooCommerce-ben

Olyan webshopoknak, ahol a vevő a kiszállítás előtt banki átutalással fizet
(WooCommerce „Közvetlen banki átutalás” / BACS). Két rendelési esemény, két
hívás:

**1. Leadott rendelés** (a BACS-rendelés „Várakozik” / on-hold állapotban
indul) — díjbekérő küldése:

```bash
curl -X POST "https://api.bizonylat.hu/public/v1/invoices" \
  -H "Authorization: Bearer $BIZONYLAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "invoiceType": "PROFORMA",
    "sendEmail": true,
    "client": { "name": "Kiss Anna", "email": "anna@example.com" },
    "lines": [
      { "name": "Hidratáló arckrém 50ml", "quantity": 2, "unitPrice": 4990 }
    ],
    "pricesIncludeVat": true,
    "paymentMethod": "BANK_TRANSFER",
    "notes": "Közlemény: #1234"
  }'
```

Tárolja el a kapott `id` értéket a rendelésen (pl. `_bizonylat_proforma_id`
rendelés-metaadatként). A vevő megkapja a díjbekérőt a bankszámla
adatokkal; a NAV-nak semmi nem megy.

**2. Beérkezett a fizetés** — a rendelés „Feldolgozás alatt” / processing
állapotba kerül — számla készítése és küldése:

```bash
curl -X POST "https://api.bizonylat.hu/public/v1/invoices/$PROFORMA_ID/convert" \
  -H "Authorization: Bearer $BIZONYLAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "to": "INVOICE", "sendEmail": true, "markSourcePaid": true }'
```

Tárolja el a `data.id` / `data.invoiceNumber` értéket a rendelésen. Ha a cég
könyvelője szerint a befizetésről előlegszámla jár, küldjön helyette
`"to": "PREPAYMENT"` értéket (a végszámla ilyenkor később készül — a
felületen, vagy az API-n `advanceDeductions` mezővel, lásd lent: *Előleg és
végszámla*).

- **A 2. lépés idempotens**: a WooCommerce és a legtöbb webhook-küldő
  újrapróbálkozik, és az újrapróbálás **409** `PROFORMA_ALREADY_CONVERTED`
  választ kap ugyanazzal a számlával a `data` mezőben — kezelje pontosan úgy,
  mint egy 201-et.
- **Az 1. lépés önmagában nem az**: küldjön `Idempotency-Key` kulcsot (pl.
  `order-1234-proforma`), hogy az újrapróbálás az első választ adja vissza,
  és tárolja el a kapott azonosítót a rendelésen (lásd lent: *Idempotency-Key*).
- Fizetés előtt lemondott rendelés: a díjbekérő nem számla, így a NAV-nál
  nincs mit sztornózni. Ha a Bizonylatban is le szeretné zárni — ne kapjon
  emlékeztetőt, ne ajánlja fel a banki egyeztetés, érvénytelenítettként
  jelenjen meg —, hívja meg a `POST /public/v1/invoices/:id/void` végpontot
  (csak amíg kifizetetlen és nincs átalakítva; az ismételt hívás
  `409 PROFORMA_VOIDED` választ ad a díjbekérővel).

## Előleg és végszámla

Foglaló, előleg, részfizetés: a vevő a szolgáltatás vagy a termék előtt
fizeti meg az ár egy részét. A Bizonylat három építőelemet kínál; **hogy egy
előleg után kell-e előlegszámla, és mikor, azt a cég (és a könyvelője)
dönti el** — az API azt teszi, amit kérnek tőle.

**1. Készpénz vagy kártya a pultnál → előlegszámla egy hívással.** A pénz
már megvan, ezért közvetlenül az előlegszámla készül:

```bash
curl -X POST "https://api.bizonylat.hu/public/v1/invoices" \
  -H "Authorization: Bearer $BIZONYLAT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: booking-1234-advance" \
  -d '{
    "invoiceType": "PREPAYMENT",
    "client": { "name": "Kiss Anna", "email": "anna@example.com" },
    "lines": [{ "name": "Foglaló — esküvői fotózás 2027-05-15", "quantity": 1, "unitPrice": 50000, "vatRate": 27 }],
    "paymentMethod": "CASH",
    "paymentStatus": "PAID",
    "paidAmount": "63500",
    "sendEmail": true
  }'
```

A számlatömbben (vagy az `invoicePrefix` tömbjében) kap sorszámot, a NAV-nak
minden tétele előlegtételként megy, a PDF címe *Előlegszámla*. A
`performanceDate` alapértéke a kiállítás dátuma — a pénz beérkezésének
napja. A `paidAmount` a fizetést a dátumával (`paidAt`, alapból most) együtt
rögzíti; a végszámla később ezt jelenti a NAV-nak az előleg fizetési
dátumaként.

**2. Banki átutalás → előbb díjbekérő, a pénz beérkezésekor előlegszámla.**
Készítsen díjbekérőt (`"invoiceType": "PROFORMA"`, lásd fent). Amikor az
utalás megjelenik — akár napokkal később —, alakítsa át, a beérkezés
napjával:

```bash
curl -X POST "https://api.bizonylat.hu/public/v1/invoices/$PROFORMA_ID/convert" \
  -H "Authorization: Bearer $BIZONYLAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "to": "PREPAYMENT", "markSourcePaid": true, "performanceDate": "2026-11-03" }'
```

Kiállítás ma, teljesítés november 3., a fizetés is erre a napra rögzítve.
`performanceDate` nélkül minden a mai napra szól, pontosan mint eddig.

**3. A végszámla → `advanceDeductions`.** Állítsa ki a számlát a teljes
szolgáltatásról, és nevezze meg a beszámítandó előlegszámlákat:

```bash
curl -X POST "https://api.bizonylat.hu/public/v1/invoices" \
  -H "Authorization: Bearer $BIZONYLAT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: booking-1234-final" \
  -d '{
    "clientId": "5b1a…",
    "lines": [{ "name": "Esküvői fotózás 2027-05-15", "quantity": 1, "unitPrice": 200000, "vatRate": 27 }],
    "advanceDeductions": [{ "invoiceId": "<előlegszámla azonosítója>" }],
    "paymentMethod": "BANK_TRANSFER"
  }'
```

A szerver az előlegszámla minden ÁFA-kategóriájához és -kulcsához egy-egy
negatív tételt fűz hozzá — `Előleg beszámítása — SZ-2026-000123` néven, ahogy
a felület is —, így a végösszeg az, ami még fizetendő (itt 254 000 − 63 500 =
190 500). A NAV ezeket előlegtételként kapja (`advanceIndicator`), az
előlegszámla sorszámával, fizetési dátumával és árfolyamával
(`advancePaymentData`), ha az előlegszámlán pontosan egy napra szól a
rögzített fizetés. A 201-es válasz a szokásos mezőkön felül tartalmazza:

```json
"advanceDeductions": [{
  "invoiceId": "…", "invoiceNumber": "SZ-2026-000123",
  "amount": "63500.00", "remainingAfter": "0.00",
  "lines": [{ "name": "Előleg beszámítása — SZ-2026-000123", "quantity": "-1", "unit": "db",
              "unitPrice": "50000.00", "netAmount": "-50000.00", "vatRate": 27,
              "vatCategory": "STANDARD", "vatAmount": "-13500.00", "grossAmount": "-63500.00" }]
}]
```

- **Részleges beszámítás:** `{ "invoiceId": "…", "amount": "20000" }` ennyi
  bruttó összeget számít be. Több ÁFA-kulcsos előlegszámlánál az összeg a
  kulcsonként hátralévő részek arányában oszlik meg, fillérre pontosan; a
  maradék későbbi beszámítása minden kulcsot pontosan lezár.
- **Mennyi van még hátra:** minden előlegszámla a `GET /public/v1/invoices/:id`
  válaszban és a listában `advanceRemaining` mezőt kap (bruttó; teljes
  beszámítás után `"0.00"`; minden más bizonylaton `null`). Egy ügyfél nyitott
  előlegei: `GET /public/v1/invoices?invoiceType=PREPAYMENT&status=ISSUED&clientId=…`.
  A felületen kézzel írt (a sorszámot megnevező) beszámító tételek is
  számítanak; a sztornózott végszámla beszámítása visszajár.
- **Elutasítás, semmi nem íródik:**

| Státusz | Kód | Mikor |
|---|---|---|
| 404 | `ADVANCE_INVOICE_NOT_FOUND` | az `invoiceId` nem ennek a cégnek a bizonylata |
| 422 | `ADVANCE_INVOICE_NOT_DEDUCTIBLE` | `error.reason`: `NOT_PREPAYMENT`, `NOT_ISSUED`, `STORNOED`, `CLIENT_MISMATCH` (másik vevőé), `CURRENCY_MISMATCH` |
| 422 | `ADVANCE_DEDUCTION_EXCEEDS_REMAINING` | több, mint ami hátravan (`error.remaining`), vagy már teljesen beszámították — akkor is, ha egy másik végszámla egy pillanattal korábban vitte el |
| 422 | `ADVANCE_DEDUCTION_EXCEEDS_TOTAL` | a végszámla negatív lenne (0 végösszeg megengedett) |
| 400 | `ADVANCE_DEDUCTION_NOT_ALLOWED` | `error.reason`: `INVOICE_TYPE` (nem `STANDARD`), `DRAFT`, `AGGREGATE`, `DUPLICATE` (ugyanaz az előlegszámla kétszer) |
| 400 | `INVALID_NUMBER` | az `amount` nem pozitív, legfeljebb 2 tizedesjegyű összeg |

## POST /public/v1/products/sync  (opcionális)

Töltse fel a terméklistáját egyszer (vagy éjszakánként); ezután a
számlatételek lehetnek pusztán `{ "sku", "quantity" }` alakúak.

```json
{
  "products": [
    { "sku": "SKU-123", "name": "Hidratáló arckrém 50ml", "unitPrice": 4990, "vatRate": 27, "unit": "db" }
  ],
  "deactivateMissing": false
}
```

- `sku` szerint frissít/beszúr (hívásonként max. 500). A `unitPrice`/`vatRate`
  lesz a SKU-tételek alapértelmezése.
- Termékenként opcionális NAV-alapértékek, amelyeket a termék tételei
  kapnak, ha nem küldenek sajátot: `productCodes`, `lineNature`,
  `intermediatedService` (a számlatételekkel azonos szabályokkal).
  Elhagyva a tároltak megmaradnak.
- `deactivateMissing: true` esetén a korábban szinkronizált, de a mostani
  küldeményből hiányzó SKU-jú termékek inaktívvá válnak (teljes katalógus
  szinkron szemantika).
- Válasz: `{ "data": { "created": n, "updated": n, "deactivated": n } }`

## GET /public/v1/products

A katalógus listája: `id`, `sku`, `name`, `description`, `unit`,
`unitPrice`, `vatRate` (százalék), `vatCategory`, `isActive`, `productCodes`,
`lineNature`, `intermediatedService` — az
inaktivált termékekkel együtt.

| Paraméter | Alapértelmezés | Megjegyzés |
|---|---|---|
| `includeWithoutSku` | `false` | `true` esetén a **cikkszám nélküli** termékek is szerepelnek (az irányítópulton, vagy `sku` nélkül a `POST /public/v1/products` hívással létrehozottak); ezeknél a `sku` értéke `null`, az `id` alapján hivatkozhat rájuk (árajánlat- és piszkozattételen `productId`). Magyar név: `cikkszamNelkulIs` |
| `search` | — | A név vagy a cikkszám része, kis- és nagybetűtől függetlenül |
| `page` | `1` | A `page` vagy a `limit` megadása bekapcsolja a lapozást |
| `limit` | lapozáskor `20` | 1–100 |

Válasz: `{ "data": [termék…], "pagination": { "page", "limit", "total", "totalPages" } }`,
név szerint rendezve.

**A szinkronizáló kliensek kedvéért megtartott alapértelmezések.**
`includeWithoutSku` nélkül a lista csak a cikkszámmal rendelkező termékeket
tartalmazza — azokat, amelyeket a `POST /public/v1/products/sync` kezel (a
`deactivateMissing` cikkszám nélküli terméket soha nem érint), és amelyekre
számlatétel `sku` alapján hivatkozhat —, így a saját katalógusát ezzel
összevető kliens nem kap `null` cikkszámot. `page` és `limit` nélkül a
**teljes** lista egyetlen válaszban érkezik, ahogyan eddig is (ilyenkor a
`pagination` ezt az egyetlen oldalt írja le). Új integrációk használjanak
lapozást.

## Előfizetések — ismétlődő számlák

Mindenhez, amit a vevő ütemezetten fizet (havi/éves csomagok, tagságok,
átalánydíjak). Az előfizetést **egyszer** hozza létre; ezután a Bizonylat
minden számlázási napon automatikusan kiállítja — és kérésre e-mailben el is
küldi — az új számlát. Az Ön oldalán nincs szükség cronra.

**Az EUR/USD előfizetések minden számlázási naphoz MNB-árfolyamot kérnek le.**
Minden új számla a saját árfolyamát menti. Sikertelen lekéréskor a generálás
leáll; nem használ 1-es vagy korábbi számláról átvett árfolyamot. BANK/EKB
beállítás mellett állítson ki egyedi számlákat a megfelelő `exchangeRate`
értékkel. Az automatikus devizás számlázás előtt ellenőrizze, hogy a
vállalkozás MNB-árfolyamot alkalmaz.

### POST /public/v1/subscriptions

Ugyanaz a `client` + `lines` szerkezet, mint a számlánál (SKU-k,
ÁFA-alapértelmezések és `pricesIncludeVat` azonosan működnek), kiegészítve
az ütemezéssel:

```json
{
  "client": { "name": "Kovács Anna", "email": "anna@example.com" },
  "lines": [
    { "name": "Idopontok Pro — éves", "quantity": 1, "unitPrice": 39900, "pricesIncludeVat": false }
  ],
  "billingCycle": "ANNUAL",
  "startDate": "2026-08-01",
  "currency": "HUF",
  "paymentMethod": "BANK_TRANSFER",
  "sendInvoice": true
}
```

| Mező | Kötelező | Megjegyzés |
|---|---|---|
| `billingCycle` | igen | `"MONTHLY"` vagy `"ANNUAL"`. A megújítási időközt vezérli. |
| `startDate` | nem | `YYYY-MM-DD`. Alapértelmezés: ma. |
| `nextInvoiceDate` | nem | Az **első** számla `YYYY-MM-DD` dátuma. Alapértelmezés: `startDate`. Jövőbeli dátummal előre ütemezhet; mai dátummal a következő futáskor azonnal számláz. |
| `endDate` | nem | `YYYY-MM-DD`. E dátum után nem készül számla. Nyílt végű előfizetésnél hagyja el. Nem lehet a `startDate` előtti (`400 DATE_RANGE_INVALID`). |
| `sendInvoice` | nem | Minden elkészült számla e-mailben a `client.email` címre (alapértelmezés `true`). |
| `paymentMethod` | nem | Alapértelmezés `BANK_TRANSFER`. |
| `status` | nem | `"ACTIVE"` (alapértelmezés) vagy `"PAUSED"`. Ha a megrendelést még jóvá kell hagyni, hozza létre szüneteltetve, majd jóváhagyáskor `PATCH`-csel állítsa `"ACTIVE"`-ra — addig biztosan nem megy ki számla. |
| `invoicePeriod` | nem | Elszámolási időszak a generált számlákon: `"NONE"` (alapértelmezés), `"CURRENT"` (aktuális) vagy `"PREVIOUS"` (előző) számlázási időszak. Lásd: *NAV-jelölések*. |
| `periodicalSettlement` | nem | Időszakos elszámolás a generált számlákon (alapértelmezés `false`). |

Válasz — **201**: `{ "data": { "id", "status": "ACTIVE", "billingCycle", "startDate", "nextInvoiceDate", "endDate", "currency", "clientId", "invoicePeriod", "periodicalSettlement" } }`

Tárolja el az `id`-t a megrendelésén — a későbbi szüneteltetéshez vagy
lemondáshoz szükség lesz rá.

### GET /public/v1/subscriptions/:id

Válasz: `{ "data": { "id", "status", "billingCycle", "startDate", "nextInvoiceDate", "endDate", "currency" } }`.
A `nextInvoiceDate` minden számla után automatikusan előrelép — ezt lekérdezve
látható, mikor esedékes a következő számla.

### GET /public/v1/subscriptions/:id/invoices

Az előfizetésből készült összes számla, a legújabbal kezdve (max. 100):

```json
{
  "data": [
    {
      "id": "…",
      "invoiceNumber": "SZ-2026-000034",
      "status": "ISSUED",
      "paymentStatus": "UNPAID",
      "currency": "HUF",
      "grossTotal": "49000.00",
      "issueDate": "2026-08-21T00:00:00.000Z",
      "dueDate": "2026-09-20T00:00:00.000Z",
      "publicUrl": "https://app.bizonylat.hu/i/…"
    }
  ]
}
```

A megújítási számlát a napi ütemező **aszinkron** állítja ki, ezért a
`POST /public/v1/subscriptions` nem adhat vissza számlaazonosítót — abban a
pillanatban még nincs számla. Ezzel a végponttal jut el a tárolt előfizetés-
azonosítótól a keresett számláig, például hogy fizetettre állítsa. Ismeretlen
előfizetés-azonosítóra **404** a válasz, így az üres `data` tömb mindig azt
jelenti, hogy „még nincs számla”, nem pedig azt, hogy rossz az azonosító.

### PATCH /public/v1/subscriptions/:id

Szüneteltetés, folytatás vagy lemondás:

```json
{ "status": "PAUSED" }
```

- `"PAUSED"` — a számlakiállítás leáll; `"ACTIVE"`-val folytatható.
- `"CANCELLED"` — végleges leállítás.
- `"ACTIVE"` — szüneteltetett előfizetés folytatása.
- `endDate` — `YYYY-MM-DD` a lejárat ütemezéséhez, `null`/`""` a törléséhez.
- `invoicePeriod`, `periodicalSettlement` — a következő generált számlák elszámolási időszaka és időszakos elszámolása (lásd: *NAV-jelölések*).

Válasz: `{ "data": { "id", "status", "nextInvoiceDate", "endDate", "invoicePeriod", "periodicalSettlement" } }`.

**Hogyan működik a megújítás:** a Bizonylat ütemezője naponta fut, megkeresi
az összes `ACTIVE` előfizetést, amelynek elérkezett a `nextInvoiceDate`
dátuma, kiállítja a számlát (NAV-nak jelentve, mint bármely másikat),
e-mailben elküldi, ha a `sendInvoice` be volt kapcsolva, és a
`nextInvoiceDate`-et egy `billingCycle`-lel előre lépteti. A megújításhoz
soha nem kell semmit hívnia — csak mondja le, ha a vevő lemorzsolódik.

## Számlák — lista, szerkesztés, kézbesítés, sztornó, fizetés

Minden kéréshez szükséges az `Authorization: Bearer <API_KULCS>` fejléc. A
számlák a kulcs cégéhez tartoznak; más cég számlájának azonosítójára `404` a
válasz. Tesztcég kulcsa ugyanígy működik, a NAV tesztkörnyezetével.

Ezek a végpontok ugyanazokat a szabályokat alkalmazzák, mint a Bizonylat
felülete: amit a felület elutasít, azt az API is elutasítja, ugyanazzal a
hibakóddal.

### A számla objektum

Minden alábbi végpont, amely számlát ad vissza, a
`GET /public/v1/invoices/:id` formáját adja:

```json
{
  "id": "…",
  "invoiceNumber": "SZ-2026-000042",
  "status": "ISSUED",
  "navStatus": "DONE",
  "paymentStatus": "UNPAID",
  "invoiceType": "STANDARD",
  "sourceProformaId": null,
  "currency": "HUF",
  "netTotal": "10000.00",
  "vatTotal": "2700.00",
  "grossTotal": "12700.00",
  "issueDate": "2026-09-29T00:00:00.000Z",
  "dueDate": "2026-10-07T00:00:00.000Z",
  "subscriptionId": null,
  "publicUrl": "https://app.bizonylat.hu/i/…",
  "publicPdfUrl": "https://api.bizonylat.hu/api/v1/public/invoices/…/pdf",
  "clientId": "5b1a…",
  "clientName": "Kiss Anna",
  "createdAt": "2026-09-29T08:14:03.512Z",
  "updatedAt": "2026-09-30T10:02:47.118Z",
  "paidAt": null,
  "voidedAt": null
}
```

- `clientId`, `clientName`: a vevő. A `clientName` az ügyfél **jelenlegi**
  tárolt neve (egy `PATCH /public/v1/clients/:id` után az új név jelenik
  meg); a kiállított PDF a kiállításkori nevet őrzi.
- `createdAt`, `updatedAt`: ISO 8601 időbélyeg (UTC). Az `updatedAt` a
  számla **minden** változásakor frissül — kiállítás, NAV-állapot, fizetési
  állapot, tárolt PDF, archiválás —, ezért lekérdezéses szinkronizáláshoz az
  `updatedSince` paraméterrel (lent) használja.
- `paidAt`: mikor lett a számla teljesen kifizetve — a legutóbb rögzített
  fizetés `paidAt` értéke —, amíg a `paymentStatus` `PAID`. `null`, ha nem
  `PAID`, és akkor is, ha rögzített fizetés nélkül jelölték `PAID`-nek
  (`PATCH …/payment-status` `paidAmount` nélkül, vagy létrehozáskor
  `paymentStatus: "PAID"` `paidAmount` nélkül): ilyenkor nincs megadható dátum.
- **A csak dátumot tartalmazó mezők** (`issueDate`, `dueDate`, és az API
  minden más ilyen mezője) UTC éjféli ISO időbélyegként érkeznek:
  `"2026-09-29T00:00:00.000Z"` — mindig is így adtuk vissza őket. A naptári
  dátum az első 10 karakter; ne alakítsa helyi időzónára (Budapesten ez
  ugyanaz a nap maradna, de UTC-től nyugatra az előző nap lenne). A kérésekben
  egyszerű `ÉÉÉÉ-HH-NN` formátumot fogadunk.
- `voidedAt`: a díjbekérő érvénytelenítésének időpontja (`status: "VOIDED"`,
  lásd `POST /public/v1/invoices/:id/void`); egyébként `null`. A `DRAFT` és az
  `ISSUED` mellett a `VOIDED` az egyetlen további `status` érték, és csak az
  ezzel a hívással érvénytelenített díjbekérő kaphatja meg.
- Ezt a hat mezőt később vezettük be; ebbe az objektumba mezők csak
  bekerülnek, meglévőt soha nem változtatunk meg és nem távolítunk el.
- A `performanceDate` (teljesítés dátuma, egyszerű `ÉÉÉÉ-HH-NN`; dátum nélküli
  piszkozaton `null`) és az `advanceRemaining` a végén szerepel (2026-11-06).
  `advanceRemaining`: kiállított előlegszámlán (`invoiceType` `PREPAYMENT`) az
  a bruttó összeg, amely még beszámítható belőle egy végszámlán (a
  `POST /public/v1/invoices` `advanceDeductions` mezőjével) — a végösszege
  (saját helyesbítése vagy sztornója után) mínusz a vevő kiállított
  bizonylatain a sorszámát megnevező beszámító tételek; teljes beszámítás után
  `"0.00"`. Minden más bizonylaton `null`.
- Az `originalInvoiceId` a legutolsó mező (2026-11-09): sztornó
  (`invoiceType` `STORNO`) vagy helyesbítő számla (`CORRECTION`) esetén
  annak az eredeti számlának az azonosítója, amelyet módosít; minden más
  bizonylaton `null`. Így a listát lekérdezéssel szinkronizáló rendszer
  webhook nélkül is az eredeti számlához kötheti a sztornót és a helyesbítést.
- A `cashRounding` a legutolsó mező (2026-11-16): a bizonylat készpénzes
  kerekítése, vagy `null`. Lásd lent: *Készpénzes kerekítés*.

#### Készpénzes kerekítés

A forintban, készpénzben teljesített fizetést 5 forintra kell kerekíteni
(2008. évi III. törvény). A Bizonylat ezt **automatikusan** alkalmazza minden
bizonylaton, amelynek `paymentMethod` értéke `CASH`, a `currency` `HUF`, és a
`grossTotal` nem 0-ra vagy 5-re végződik — kérésmező nem tartozik hozzá:

```json
"grossTotal": "1577.34",
"cashRounding": { "roundingAmount": "-2.34", "payableAmount": "1575.00" }
```

- `payableAmount`: a készpénzben fizetendő összeg — a `grossTotal` a
  legközelebbi 5 forintra kerekítve. A 0,01–2,49 végződés lefelé 0-ra, a
  2,50–4,99 felfelé 5-re, az 5,01–7,49 lefelé 5-re, a 7,50–9,99 felfelé a
  következő 0-ra kerekül (`1577.50` → `1580.00`). Negatív végösszeg
  (készpénzben visszafizetett sztornó) az abszolút értéke szerint kerekül,
  előjele megmarad.
- `roundingAmount`: `payableAmount − grossTotal`, előjellel (a kerekítési
  különbözet). Mindkettő kéttizedes pénzösszeg-szöveg, mint a végösszegek.
- `null` minden más fizetési módnál (a bankkártyát is beleértve), minden más
  pénznemnél, és ha a végösszeg már 0-ra vagy 5-re végződik.
- Csak tájékoztató adat: a `netTotal`, a `vatTotal`, a `grossTotal`, a
  tételek és a NAV Online Számlának küldött adatok **nem változnak**. A törvény
  adózási következményt nem fűz hozzá; a PDF, a nyilvános számlaoldal és az
  e-mail a bruttó végösszeg alatt *Kerekítés* és *Fizetendő (készpénz)* sort
  mutat.
- A `payableAmount` megfizetése a számlát teljesen kiegyenlíti: ennek (vagy a
  bruttó végösszegnek, ha az a kisebb) a rögzítése után a `paymentStatus`
  `PAID` lesz.
- A `grossTotal`, a `paymentMethod` és a `currency` alapján számoljuk, amelyek
  kiállítás után nem változnak; minden válaszban ugyanaz, amely a számlát
  visszaadja (lista, lekérdezés, létrehozás, kiállítás, átalakítás, sztornó,
  helyesbítés, a fizetések összesítője, a megosztott számlaoldal
  `GET /api/v1/public/invoices/:token`).

### GET /public/v1/invoices

A számlák listája, a legújabb kiállítási dátummal kezdve (a dátum nélküli
piszkozatok a végén).

| Paraméter | Alapérték | Megjegyzés |
|---|---|---|
| `page` | `1` | |
| `limit` | `20` | 1–100; nagyobb érték `400` |
| `status` | — | `DRAFT`, `ISSUED` vagy `VOIDED` (érvénytelenített díjbekérő, lásd lent: *void*) |
| `invoiceType` | — | `STANDARD`, `PROFORMA`, `PREPAYMENT`, `STORNO`, `CORRECTION` |
| `paymentStatus` | — | `UNPAID`, `PARTIAL`, `PAID`, `OVERDUE`, `REFUNDED` — egy érték, vagy több vesszővel elválasztva: `UNPAID,PARTIAL,OVERDUE` (minden még nyitott számla) |
| `navStatus` | — | `PENDING`, `SUBMITTED`, `RECEIVED`, `PROCESSING`, `DONE`, `ABORTED`, `REJECTED` |
| `clientId` | — | egy ügyfél számlái |
| `issueDateFrom`, `issueDateTo` | — | `ÉÉÉÉ-HH-NN`, mindkettő zárt határ |
| `search` | — | a sorszám vagy az ügyfél nevének része |
| `updatedSince` | — | ISO 8601 időpont (`2026-10-05T08:00:00Z`; egy puszta `ÉÉÉÉ-HH-NN` UTC éjfélt jelent): csak azok a számlák, amelyek `updatedAt` értéke ennél nem korábbi. Magyar név: `modositvaOta` |

Válasz: `{ "data": [számla…], "pagination": { "page", "limit", "total", "totalPages" } }`.
Az archivált számlák is szerepelnek.

Egy ügyfél előlegszámlái, mindegyiknél a még beszámítható összeggel
(`advanceRemaining`):
`GET /public/v1/invoices?invoiceType=PREPAYMENT&status=ISSUED&clientId=…`.

**Változások lekérdezése.** Jegyezze fel minden lekérdezés kezdetének
időpontját; a következő alkalommal az `updatedSince` értéke ez az időpont
**mínusz néhány perc** legyen, és lapozzon végig az eredményen. Az átfedés
lefedi az előző lekérdezés közben véglegesített változásokat; az ismétlődéseket
az `id` + `updatedAt` páros alapján szűrje. A lekérdezés helyett
webhookokat (lent) is használhat.

### PATCH /public/v1/invoices/:id — piszkozat szerkesztése

Csak **piszkozat** szerkeszthető (létrehozáskor `draft: true`, vagy a
felületen készült piszkozat). Minden más esetben `409 INVOICE_NOT_DRAFT` —
kiállított számla csak sztornóval vagy helyesbítéssel változhat. Csak a
módosítandó mezőket küldje:

| Mező | Megjegyzés |
|---|---|
| `client` | Ugyanaz az objektum, mint létrehozáskor (ugyanúgy keresi vagy hozza létre), **vagy** |
| `clientId` | egy meglévő ügyfél azonosítója — a kettő együtt nem |
| `lines` | **Minden** tételt lecserél. Ugyanaz a tételforma, mint létrehozáskor (`sku`, `name`, `quantity`, `unitPrice`, `vatRate` százalékban…); a végösszegek újraszámolódnak |
| `pricesIncludeVat` | Az ebben a hívásban küldött `lines` tételekre vonatkozik |
| `issueDate`, `performanceDate`, `dueDate` | `ÉÉÉÉ-HH-NN`, vagy `null` a törléshez |
| `notes` | A számlán megjelenő megjegyzés; `null` törli |
| `currency`, `exchangeRate` | `exchangeRate`: hány forint 1 egység, `null` törli |
| `paymentMethod` | `BANK_TRANSFER`, `CASH`, `CARD`, `VOUCHER`, `COD`, `OTHER` |
| `invoiceType` | `STANDARD`, `PROFORMA` vagy `PREPAYMENT` (előlegszámla) |
| `conventionalInfo` | Egyezményes adatok, mint létrehozáskor (megrendelés-, szállítólevél-, szerződés-, projektszám…); `null` törli. A tételek a `productCodes`, `lineNature`, `intermediatedService` mezőt is fogadják |

Válasz: `{ "data": számla }`. Utána a
`POST /public/v1/invoices/:id/issue` hívással állítható ki.

### DELETE /public/v1/invoices/:id — piszkozat törlése

Siker esetén `204`. Csak piszkozat törölhető (egyébként
`409 INVOICE_NOT_DRAFT`): kiállított számlát nem törlünk, hanem sztornózunk.

### GET /public/v1/invoices/:id/pdf

A számla PDF-je (`Content-Type: application/pdf`) — ugyanaz a tárolt fájl,
amelyet a felület, a NAV és a vevő is lát. Minden letöltés bekerül a cég
naplójába.

### POST /public/v1/invoices/:id/send — (újra)küldés e-mailben

```json
{ "to": "konyveles@example.com", "locale": "en" }
```

Mindkettő opcionális. `to` nélkül az ügyfél e-mail-címére megy; `locale`
(bármely `emailLocale`-kód: `hu`, `en`, `de`, `fr`, `ja` …) nélkül az
ügyfélnél tárolt nyelven, ennek hiányában magyarul. A cég mentett e-mail-szövegét használja. Piszkozat nem küldhető
(`400`), és az a számla sem, amelynek ügyfelénél nincs cím és `to` sincs
megadva (`400`).

Válasz: `{ "data": { "sent": true, "to": "…" } }`. A kézbesítési hiba nem
HTTP-hiba: `"sent": false` és egy `"reason"`.

### POST /public/v1/invoices/:id/duplicate

Egy számlát, díjbekérőt vagy előlegszámlát — kiállítottat, piszkozatot vagy
érvénytelenítettet — **új piszkozatként** másol. Törzs nem kell. Jogosultság:
`invoices:write`.

A másolat vevője, bizonylattípusa, tételei, pénzneme, fizetési módja,
megjegyzése, számlatömbje, egyezményes adatai és bankszámlája azonos az
eredetiével. Kelte és teljesítési dátuma a mai nap, fizetési határideje a vevő
(ennek hiányában a cég) fizetési feltétele szerint, egyébként 8 nap. **Nincs
sorszáma, nem kerül a NAV-hoz, és nincs rajta fizetés vagy nyilvános hivatkozás**,
amíg a `POST /public/v1/invoices/:id/issue` hívással ki nem állítja; előtte
a `PATCH /public/v1/invoices/:id` hívással módosítható. Árfolyamot nem
másolunk: devizás másolat a kiállításkor kap árfolyamot, mint bármely
piszkozat. Az adattörlő kódok nem kerülnek át.

```bash
curl -X POST "https://api.bizonylat.hu/public/v1/invoices/$INVOICE_ID/duplicate" \
  -H "Authorization: Bearer $BIZONYLAT_API_KEY" \
  -H "Idempotency-Key: ismetles-2026-11"
```

Válasz `201` — az új piszkozat (a fenti számlaobjektum, `status: "DRAFT"`,
`invoiceNumber: null`), kiegészítve a `sourceInvoiceId` mezővel. Minden hívás
új piszkozatot készít; `Idempotency-Key` küldésével az újrapróbálás az elsőt
adja vissza. Sztornó és helyesbítő számla nem másolható:
`409 INVOICE_NOT_DUPLICABLE` — az eredeti számlát másolja. A másolatról
`invoice.created` webhook érkezik.

### POST /public/v1/invoices/:id/storno

Kiállított számla érvénytelenítése **sztornó számlával**, amelyet a NAV-nak
jelentünk. A törzs minden mezője opcionális; az üres törzs (vagy a törzs
elhagyása) is megfelel.

| Mező | Típus | Kötelező | Megjegyzés |
|---|---|---|---|
| `reason` | szöveg | nem | Legfeljebb 500 karakter. A sztornó megjegyzéseként tárolódik; nélküle a megjegyzés `Storno: <az eredeti számla sorszáma>` |
| `sendEmail` | logikai | nem | Alapból `false`. `true` esetén a sztornót e-mailben elküldjük az ügyfélnek |
| `exchangeRate` | szöveg | nem | Hány forint 1 egység, legfeljebb 6 tizedesjeggyel (`"392.5"`). Csak olyan régi devizás számláknál kell, amelyeken nincs tárolt árfolyam (ha az eredetin van, figyelmen kívül marad); csak az `exchangeRateDate` mezővel együtt érvényes |
| `exchangeRateDate` | szöveg | nem | `ÉÉÉÉ-HH-NN`, az árfolyam napja |

```bash
curl -X POST "https://api.bizonylat.hu/public/v1/invoices/$INVOICE_ID/storno" \
  -H "Authorization: Bearer $BIZONYLAT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1234-storno" \
  -d '{ "reason": "A rendelés törölve", "sendEmail": true }'
```

Válasz `201` — az új sztornó számla (a fenti számla objektum kiegészítve az
`originalInvoiceId` mezővel; a végösszegek negatívak):

```json
{
  "data": {
    "id": "…",
    "invoiceNumber": "SZ-2026-000043",
    "status": "ISSUED",
    "navStatus": "PENDING",
    "invoiceType": "STORNO",
    "currency": "HUF",
    "netTotal": "-10000.00",
    "vatTotal": "-2700.00",
    "grossTotal": "-12700.00",
    "originalInvoiceId": "…",
    "publicUrl": "https://app.bizonylat.hu/i/…",
    "…": "…"
  }
}
```

Működése:

- **A számla teljes jelenlegi állapotát érvényteleníti:** az eredetit és az
  eddig kiállított összes helyesbítést is, egyetlen, negatív tételeket
  tartalmazó bizonylatban. Az `:id` lehet az eredeti számla vagy ugyanazon
  számla bármely későbbi bizonylata (helyesbítés); az `originalInvoiceId`
  mindig az eredeti számla.
- A sztornó azonnal kiállításra kerül, az **eredeti számlatömbjének** következő,
  kihagyásmentes sorszámával, a mai dátummal, ugyanazzal a vevővel és
  pénznemmel.
- **NAV:** az eredetit és minden korábbi helyesbítést a NAV-nak már be kellett
  fogadnia (`navStatus: "DONE"`), különben
  `409 INVOICE_CHAIN_NOT_ACCEPTED_BY_NAV`. Magát a sztornót a háttérben
  jelentjük a NAV-nak: a `navStatus` `PENDING` állapotból indul. Követéséhez
  használja a `GET /public/v1/invoices/:id/nav` hívást vagy az
  `invoice.storno_issued` webhookot.
- **E-mail:** csak a `"sendEmail": true` megadásakor megy ki.
- **Csomagkeret:** a sztornó soha nem számít bele a havi API-számlakeretbe, és
  a keret miatt sem utasítjuk el.
- Nem sztornózható: a piszkozat (`409 INVOICE_NOT_ISSUED`), a díjbekérő
  (`409 PROFORMA_NOT_MODIFIABLE`) és a sztornó (`409 CANNOT_STORNO_A_STORNO`);
  `409 CHAIN_FULLY_REVERSED`, ha már nincs mit érvényteleníteni.
  A `422 INVOICE_EXCHANGE_RATE_UNAVAILABLE` azt jelzi, hogy a régi devizás
  számlához `exchangeRate` + `exchangeRateDate` szükséges.
- **A sztornó ismétlése biztonságos:** a második hívás soha nem készít második
  sztornót. `Idempotency-Key` nélkül `409 ALREADY_STORNOED` a válasz, a
  `data` mezőben a meglévő sztornóval (ugyanaz a forma, mint a `201`-nél), az
  azonosítójával pedig az `error.invoiceId` mezőben — kezelje sikerként.
  Ha az első hívással megegyező `Idempotency-Key` kulcsot küld, az első
  `201` választ kapja vissza (lásd lent: *Idempotency-Key*).

### POST /public/v1/invoices/:id/correct — helyesbítés

Módosító számlát állít ki (a NAV-nak MODIFY műveletként jelentve). Ugyanazt
teszi, mint a felület helyesbítése, ugyanazokkal a korlátokkal:

- A **kívánt végső tételeket** küldi; a Bizonylat csak az előjeles
  különbséget jelenti. A jelenlegi tételeket a
  `GET /public/v1/invoices/:id/lines` adja; módosítsa, majd küldje vissza.
  Az elhagyott tétel törlődik; ha egy tétel terméke, neve, leírása,
  mennyiségi egysége, egységára, ÁFA-kulcsa vagy ÁFA-kategóriája változik,
  az a régi tétel törlésének és egy új felvételének számít.
- Csak a tételek, a dátumok és az indoklás változhat. **A vevő és a pénznem
  nem helyesbíthető** — `client`, `clientId` vagy `currency` küldése
  `400`; ilyenkor sztornózza a számlát, és állítson ki újat.
- A tételek végső, nem negatív értékek, kifejezett összegekkel
  (`netAmount + vatAmount = grossAmount`); a `vatRate` százalék (0–100).
  Minden más `400`, az üzenet megadja az okot. Az összegeknek a tételből is
  ki kell jönniük: `netAmount` ≈ `quantity × unitPrice` és
  `vatAmount` ≈ `netAmount × vatRate` (kerekítéssel — a `GET …/lines`
  válasza mindig megfelel), különben `400 LINE_AMOUNTS_INCONSISTENT`. A
  mennyiség legfeljebb 4 tizedesjegyű, az összeg legfeljebb
  9 999 999 999 999,99.
- Az `issueDate` nem lehet a mai napnál későbbi (`400 ISSUE_DATE_IN_FUTURE`),
  és egyik dátum sem lehet 2010-01-01 előtti (`400 DATE_TOO_EARLY`).
- Változatlan tételekre `422 CORRECTION_WITHOUT_CHANGE` — kivéve, ha
  `"dataOnly": true` (adattartalom helyesbítése: nulla összegű helyesbítés).
- Az eredetit és minden korábbi helyesbítést be kellett fogadnia a NAV-nak
  (`409 INVOICE_CHAIN_NOT_ACCEPTED_BY_NAV`); sztornózott számla nem
  helyesbíthető (`409 CANNOT_CORRECT_A_STORNO`); piszkozat és díjbekérő nem
  helyesbíthető (`409 INVOICE_NOT_ISSUED`, `409 PROFORMA_NOT_MODIFIABLE`).
  Az `:id` lehet az eredeti számla vagy ugyanazon számla későbbi
  helyesbítése.

A törzs:

| Mező | Típus | Kötelező | Megjegyzés |
|---|---|---|---|
| `lines` | tömb | igen | 1–100 végső tétel, lásd lent |
| `reason` | szöveg | nem | Legfeljebb 500 karakter; a helyesbítés megjegyzése (alapból `Correction: <az eredeti számla sorszáma>`) |
| `issueDate` | szöveg | nem | `ÉÉÉÉ-HH-NN`; alapból a mai nap |
| `performanceDate` | szöveg | nem | `ÉÉÉÉ-HH-NN`; alapból a kiállítás dátuma |
| `dueDate` | szöveg | nem | `ÉÉÉÉ-HH-NN`; alapból a kiállítás után 30 nappal |
| `dataOnly` | logikai | nem | `true`: minden adat változatlan marad, a helyesbítés összegei nullák |
| `sendEmail` | logikai | nem | Alapból **`true`** (a sztornóval ellentétben): a helyesbítést e-mailben elküldjük az ügyfélnek |
| `exchangeRate`, `exchangeRateDate` | szöveg | nem | Mint a sztornónál: csak régi devizás számláknál |

Egy tétel: kötelező a `name`, a `quantity` (nagyobb, mint 0), a
`unitPrice`, a `netAmount`, a `vatRate` (százalék), a `vatAmount` és a
`grossAmount` (számok vagy számot tartalmazó szövegek); opcionális a `unit`
(alapból `db`), a `description`, a `vatCategory` (lásd
`GET /public/v1/reference`) és a `productId`. Ugyanezt a formát adja a
`GET /public/v1/invoices/:id/lines`, a tételek NAV-adataival együtt
(`productCodes`, `lineNature`, `intermediatedService`); az ezek nélkül küldött
tétel megtartja a meglévőket. A helyesbítés az eredeti `conventionalInfo`
adatait viszi tovább.

```bash
curl -X POST "https://api.bizonylat.hu/public/v1/invoices/$INVOICE_ID/correct" \
  -H "Authorization: Bearer $BIZONYLAT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1234-correction-1" \
  -d '{
    "lines": [
      { "name": "Arckrém", "quantity": "3", "unit": "db", "unitPrice": "1000.00",
        "netAmount": "3000.00", "vatRate": 27, "vatCategory": "STANDARD",
        "vatAmount": "810.00", "grossAmount": "3810.00" }
    ],
    "reason": "Mennyiség javítása",
    "sendEmail": true
  }'
```

Válasz `201` — az új helyesbítő számla a számla objektum formájában, kiegészítve
az `originalInvoiceId` mezővel; a végösszegei a jelenlegi állapothoz képesti
**különbséget** mutatják (itt a mennyiség 4-ről 3-ra csökken, ezért negatív):

```json
{
  "data": {
    "id": "…",
    "invoiceNumber": "SZ-2026-000044",
    "status": "ISSUED",
    "navStatus": "PENDING",
    "invoiceType": "CORRECTION",
    "netTotal": "-1000.00",
    "vatTotal": "-270.00",
    "grossTotal": "-1270.00",
    "originalInvoiceId": "…",
    "…": "…"
  }
}
```

A NAV, a sorszámozás és a csomagkeret a sztornóéval azonosan működik: a
helyesbítés az eredeti számlatömbjének következő sorszámát kapja, a háttérben
kerül a NAV-hoz (`navStatus` `PENDING`, webhook: `invoice.corrected`), és soha
nem számít bele a havi API-számlakeretbe.

**A helyesbítés ismétlése:** `Idempotency-Key` nélkül az ismételt hívást nem
ismerjük fel ismétlésként — amíg az első helyesbítés a NAV-nál `PENDING`,
`409 INVOICE_CHAIN_NOT_ACCEPTED_BY_NAV` a válasz, utána (a tételek már
megegyeznek a jelenlegi állapottal) `422 CORRECTION_WITHOUT_CHANGE`. A
biztonságos újrapróbálkozáshoz és az első válasz visszakapásához küldjön
`Idempotency-Key` kulcsot.

### POST /public/v1/invoices/:id/void — díjbekérő érvénytelenítése

Visszavon egy **kiállított, kifizetetlen díjbekérőt**, amelyből még nem készült
bizonylat — a mögötte álló rendelést fizetés előtt lemondták. A díjbekérő nem
adóügyi bizonylat, és soha nem kerül a NAV-hoz, ezért semmit nem küldünk be és
semmit nem sztornózunk: a `status` értéke `VOIDED` lesz, és kitöltjük a
`voidedAt` mezőt. A sorszám felhasználtnak számít (a `DB` sorozat
hézagmentes marad), a bizonylatot, a tételeit és a PDF-et megőrizzük. Számlát
soha nem érvénytelenítünk így — azt sztornóval kell visszavonni.

```bash
curl -X POST "https://api.bizonylat.hu/public/v1/invoices/$PROFORMA_ID/void" \
  -H "Authorization: Bearer $BIZONYLAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Rendelés lemondva" }'
```

A `reason` (nem kötelező, legfeljebb 500 karakter) a vállalkozás naplójába
kerül; a törzs el is hagyható. Válasz: `200`, `{ "data": számla }`
`"status": "VOIDED"` és `voidedAt` értékkel; a `proforma.voided` webhook
elküldésre kerül.

| Elutasítás | Mikor |
|---|---|
| `409 NOT_A_PROFORMA` | nem díjbekérő (a számlát a `/storno` vonja vissza) |
| `409 PROFORMA_NOT_ISSUED` | még piszkozat — érvénytelenítés helyett törölje (`DELETE /public/v1/invoices/:id`) |
| `409 PROFORMA_PAID` | teljesen vagy részben kifizették, vagy fizetést rögzítettek rá (`error.paymentStatus`, `error.hasPayments`) — inkább alakítsa át |
| `409 PROFORMA_ALREADY_CONVERTED` | számla / előlegszámla készült belőle (`error.invoiceId`) |
| `409 PROFORMA_VOIDED` | már érvénytelenítették — lásd lent |

**Az ismétlés biztonságos.** A második hívás semmit nem változtat, és
`409 PROFORMA_VOIDED` választ ad, a `data` mezőben a díjbekérővel (a `200`
válasszal azonos szerkezetben) és az `error.voidedAt` mezővel — kezelje
sikerként. Az első hívással azonos `Idempotency-Key` kulccsal az első `200`
választ kapja vissza.

Érvénytelenítés után a díjbekérő nem alakítható át (`/convert` →
`409 PROFORMA_VOIDED`), nem fizethető (`POST …/payments` →
`409 PAYMENT_NOT_ALLOWED`, `PATCH …/payment-status` → `409 PROFORMA_VOIDED`),
és nem küldhető el e-mailben (`/send` → `409 PROFORMA_VOIDED`); fizetési
emlékeztetőt nem kap, és a banki egyeztetés sem ajánlja fel. Az irányítópulton
*Érvénytelenítve* címke jelzi (ott is érvényteleníthető: *Érvénytelenítés* a
díjbekérőn). Az ügyféloldal (`publicUrl`) érvénytelenítettként, fizetendő
összeg nélkül mutatja; az érvénytelenítés után előállított PDF-en
*ÉRVÉNYTELENÍTVE* bélyegző szerepel, a kiállításkor tárolt PDF
(`publicPdfUrl`) viszont változatlan marad.

### GET /public/v1/invoices/:id/lines

A jelenlegi tételek: kiállított számlánál az összes helyesbítés utáni
tényleges állapot, piszkozatnál a saját tételei. Ugyanaz a tételforma, amelyet
a `/correct` elfogad (`vatRate` százalékban).

### Fizetések

**GET /public/v1/invoices/:id/payments** —
`{ "data": [{ "id", "amount", "currency", "method", "paidAt", "reference", "note", "createdAt" }], "summary": { "paymentStatus", "currency", "grossTotal", "paidTotal", "cashRounding" } }`

**POST /public/v1/invoices/:id/payments** — fizetés rögzítése, pontosan úgy,
mint a felület fizetésrögzítő űrlapja:

```json
{ "amount": 12700, "paidAt": "2026-09-29", "method": "BANK_TRANSFER", "note": "Utalás", "reference": "BANK-TX-123" }
```

- Az `amount` és a `paidAt` (dátum vagy ISO dátum-idő) kötelező; negatív
  összeg visszatérítést rögzít. A `method` alapértéke a számla fizetési
  módja.
- A `paymentStatus` az összes fizetésből újraszámolódik: semmi →
  `UNPAID`, egy része → `PARTIAL`, legalább a bruttó végösszeg → `PAID`.
  `PAID` esetén kimegy a „fizetés beérkezett” e-mail, ha a cég bekapcsolta.
  Készpénzes, forintos számlán, ha van `cashRounding`, a `payableAmount` is
  elég: `1577.34` végösszegű számlára `1575` befizetése → `PAID`.
- Csak kiállított számlára: piszkozatra, sztornóra és nem pozitív
  helyesbítésre `409 PAYMENT_NOT_ALLOWED`.

Válasz `201`: `{ "data": fizetés, "invoice": számla }`. A
`PATCH /public/v1/invoices/:id/payment-status` változatlanul működik.

### GET /public/v1/invoices/:id/nav

NAV-beküldési állapot és előzmények:

```json
{
  "data": {
    "invoiceId": "…", "invoiceNumber": "SZ-2026-000042", "invoiceType": "STANDARD",
    "reportsToNav": true, "navStatus": "DONE", "navTransactionId": "…",
    "submissions": [
      { "id": "…", "operation": "CREATE", "status": "DONE", "transactionId": "…",
        "attemptCount": 1, "lastAttemptAt": "…", "nextRetryAt": null,
        "errorCode": null, "errorMessage": null, "createdAt": "…", "updatedAt": "…" }
    ]
  }
}
```

A legújabb beküldés az első. A `reportsToNav` piszkozatnál és díjbekérőnél
`false` (ezeket nem jelentjük). XML-t, kulcsot vagy hozzáférési adatot soha
nem ad vissza. A sztornó és a helyesbítés külön számla: a saját beküldéseit a
saját azonosítójával kérdezze le.

## Idempotency-Key

Az a webshop, amelynek a `POST /public/v1/invoices` hívása időtúllépéssel
végződik, nem tudja, elkészült-e a számla: a vak újrapróbálás második,
NAV-nak jelentett számlát állíthat ki, az újrapróbálás elmaradása pedig a
vásárláshoz tartozó számla elvesztésével járhat. `Idempotency-Key` küldésével
az újrapróbálás biztonságossá válik.

```bash
curl -X POST "https://api.bizonylat.hu/public/v1/invoices" \
  -H "Authorization: Bearer $BIZONYLAT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 8f14e45f-ceea-4672-a0c1-2c1f6d0b7a11" \
  -d '{ "client": { "name": "Kiss Anna" }, "lines": [ { "name": "Arckrém", "quantity": 1, "unitPrice": 4990 } ] }'
```

**Hol működik.** Az `Idempotency-Key: <kulcs>` fejlécet ezekre a hívásokra
küldheti:

- `POST /public/v1/invoices` (létrehozás és kiállítás; a piszkozat és a
  díjbekérő is)
- `POST /public/v1/invoices/:id/duplicate`
- `POST /public/v1/invoices/:id/storno`
- `POST /public/v1/invoices/:id/correct`
- `POST /public/v1/invoices/:id/payments`
- `POST /public/v1/clients` és `POST /public/v1/products` (az ismételt
  létrehozás az első rekordot adja vissza, nem hoz létre másodpéldányt — és
  cikkszámos terméknél nem kap `409 PRODUCT_SKU_TAKEN` választ önmaga miatt)
- `POST /public/v1/webhooks` (a telepítését ismétlő bővítmény egyetlen
  végpontot regisztrál; az ismételt válasz ugyanazt a `secret` értéket
  tartalmazza, amelyet a 24 óra alatt titkosítva tárolunk)

A többi végpont figyelmen kívül hagyja a fejlécet. Az `/issue` soha nem ad
kétszer sorszámot egy piszkozatnak, a `/convert` pedig ismétléskor a meglévő
bizonylatot adja vissza (`PROFORMA_ALREADY_CONVERTED`), ezért ezek a fejléc
nélkül is biztonságosan ismételhetők.

**A kulcs.** 1–255 látható ASCII karakter, szóköz nélkül — a legjobb egy UUID,
vagy a rendelés azonosítója a művelettel (`order-1234-invoice`,
`order-1234-storno`). Minden más `400` (az üzenet: `Idempotency-Key must be
1–255 printable ASCII characters (e.g. a UUID)`), és semmi nem fut le. A
kulcsot **műveletenként egyszer** állítsa elő, tárolja a rendelésnél, és csak
ugyanannak a műveletnek az újrapróbálásához használja fel újra. A kulcsok a
céghez tartoznak, nem egy API-kulcshoz.

**Mi történik ismétléskor** (ugyanaz a kulcs, az első használattól számított
**24 órán belül**):

| Helyzet | Válasz |
|---|---|
| Ugyanaz a kulcs, ugyanaz a kérés, az első hívás sikeresen befejeződött | Az első válasz újra: ugyanaz a státuszkód és JSON-törzs, valamint az `Idempotent-Replayed: true` fejléc. Semmi sem készül el, megy ki vagy számít bele másodszor |
| Ugyanaz a kulcs, **más kérés** | `422 IDEMPOTENCY_KEY_REUSED` |
| Ugyanaz a kulcs, amíg az első hívás **még fut** | `409 IDEMPOTENCY_KEY_IN_PROGRESS` — várjon néhány másodpercet, és ismételje ugyanazzal a kulccsal |
| Ugyanaz a kulcs 24 óra után | A kulcsot elfelejtettük: a hívás új kérésként fut le |

- „Ugyanaz a kérés”: azonos metódus, azonos útvonal (tehát azonos számla
  azonosító) és azonos JSON-törzs. A JSON kulcsainak sorrendje nem számít; a
  lekérdezési karakterlánc (query string) nem része. Ugyanaz a kulcs másik
  végponton más kérésnek számít (`422`).
- **Csak a sikeres (2xx) válaszokat tároljuk.** Az elutasítás — érvényesítési
  hiba, `402`, `409 ALREADY_STORNOED`, nem ellenőrzött NAV-hozzáférés — vagy a
  szerverhiba felszabadítja a kulcsot, ezért javítsa az okát, és ismételje
  ugyanazzal a kulccsal. Csak a státuszkódot és a JSON-törzset tároljuk;
  ismétléskor ne támaszkodjon más válaszfejlécekre.
- Ha az első hívás válasz nélkül elhalt, nagyjából két perc után már nem
  blokkolja a kulcsot: az ismétlés ilyenkor rendes első hívásként fut le.
- Érvényes API-kulcs nélkül a hívás a szokásos `401`, a fejléctől függetlenül.
- A fejléc nélkül a kérések pontosan úgy működnek, mint eddig.

## Hibák (ezeknél a végpontoknál)

| Státusz | Kód | Mikor |
|---|---|---|
| 400 | — | érvénytelen adat, piszkozat a `/send` hívásban, nincs címzett, vevő/pénznem a `/correct` hívásban, érvénytelen helyesbítő tételek, hibás `Idempotency-Key` |
| 400 | `AMOUNT_OUT_OF_RANGE`, `INVALID_NUMBER`, `VAT_RATE_CATEGORY_MISMATCH` | piszkozat tételei (`PATCH`), mint létrehozáskor; 9 999 999 999 999,99-nél nagyobb fizetési `amount` (az üres vagy 0,00-ra kerekedő összeg sima 400) |
| 400 | `DATE_TOO_EARLY`, `ISSUE_DATE_IN_FUTURE` | 2010-01-01 előtti dátum (piszkozat, helyesbítés); a mai napnál későbbi helyesbítési kiállítási dátum |
| 400 | `LINE_AMOUNTS_INCONSISTENT` | helyesbítő tétel, amelynek összegei nem a mennyiség, az egységár és a kulcs szerint jönnek ki |
| 404 | — | ismeretlen vagy más cég számlája |
| 409 | `INVOICE_NOT_DRAFT` | PATCH/DELETE kiállított számlán |
| 409 | `ALREADY_STORNOED` | ismételt sztornó — a `data` a meglévő sztornó, az `error.invoiceId` az azonosítója |
| 409 | `INVOICE_CHAIN_NOT_ACCEPTED_BY_NAV` | sztornó/helyesbítés, mielőtt a NAV befogadta a számlát (és a korábbi helyesbítéseit) |
| 409 | `CANNOT_STORNO_A_STORNO`, `CANNOT_CORRECT_A_STORNO`, `CHAIN_FULLY_REVERSED`, `INVOICE_NOT_ISSUED`, `PROFORMA_NOT_MODIFIABLE` | sztornó/helyesbítés rossz bizonylaton (sztornón, már teljesen érvénytelenített számlán, piszkozaton, díjbekérőn) |
| 409 | `PAYMENT_NOT_ALLOWED` | fizetés piszkozaton, sztornón, nem pozitív helyesbítésen vagy érvénytelenített díjbekérőn |
| 409 | `PROFORMA_VOIDED` | ismételt `/void` (a `data` a díjbekérőt tartalmazza), illetve `/convert`, `/send`, `PATCH …/payment-status` érvénytelenített díjbekérőn |
| 409 | `PROFORMA_PAID`, `PROFORMA_ALREADY_CONVERTED`, `PROFORMA_NOT_ISSUED`, `NOT_A_PROFORMA` | `/void` kifizetett, átalakított, piszkozat vagy nem díjbekérő bizonylaton |
| 409 | `IDEMPOTENCY_KEY_IN_PROGRESS` | ugyanaz a kulcs, amíg az első kérés fut |
| 409 | `NAV_CREDENTIALS_NOT_VERIFIED` | a NAV-kapcsolat nincs ellenőrizve (az `error.credentials` mutatja az állapotot) |
| 422 | `CORRECTION_WITHOUT_CHANGE` | a helyesbítés tételei megegyeznek a jelenlegiekkel (adattartalom-helyesbítéshez küldjön `dataOnly: true` értéket) |
| 422 | `IDEMPOTENCY_KEY_REUSED` | ugyanaz a kulcs, más kérés |
| 422 | `INVOICE_EXCHANGE_RATE_UNAVAILABLE` | régi devizás számla tárolt árfolyam nélkül; 0 értékű `exchangeRate` |

## NAV-jelölések — fordított adózás, elszámolási időszak, pénzforgalmi elszámolás

### Belföldi fordított adózás — `vatCategory: "DOMESTIC_REVERSE_CHARGE"`

Az ilyen tételt a NAV-nak `vatDomesticReverseCharge` jelöléssel jelentjük
(„A belföldi fordított adózás jelölése - ÁFA tv. 142. §”), 0%-kal, ÁFA
nélkül; a PDF-en a tételnél „Fordított adózás”, alul pedig „Fordított adózás
– belföldi fordított adózás (ÁFA tv. 142. §)” szerepel. Magyar értéknév:
`BELFOLDI_FORDITOTT_ADOZAS`.

A vevőnek **magyar adószámmal** rendelkező vállalkozásnak kell lennie (a
NAV-nak `DOMESTIC` vevőként jelentjük). Ellenkező esetben a kiállítás
`422 DOMESTIC_REVERSE_CHARGE_BUYER` hibával elmarad, sorszám nem fogy —
`POST /public/v1/invoices`, `…/:id/issue`, helyesbítés és előfizetéses
számla esetén egyaránt. A `GET /public/v1/reference/vat-categories` ennél a
kategóriánál `requiredBuyerFields: ["taxNumber"]` értéket ad.

### Elszámolási időszak — `deliveryPeriodStart`, `deliveryPeriodEnd`, `periodicalSettlement`

A `POST /public/v1/invoices` és a `PATCH /public/v1/invoices/:id` (piszkozat) hívásban:

| Mező | Típus | Megjegyzés |
|---|---|---|
| `deliveryPeriodStart` | dátum (`YYYY-MM-DD`) | Az időszak első napja (NAV `invoiceDeliveryPeriodStart`: „Amennyiben a számla egy időszakra vonatkozik, akkor az időszak első napja”). Magyar név: `elszamolasiIdoszakKezdete`. |
| `deliveryPeriodEnd` | dátum | Az időszak utolsó napja (NAV `invoiceDeliveryPeriodEnd`). Magyar név: `elszamolasiIdoszakVege`. A kettőt együtt küldje, vagy egyiket sem; csak az egyik, vagy a kezdetnél korábbi vég → `400 DATE_RANGE_INVALID`. PATCH-ben mindkettő `null` értéke törli az időszakot. |
| `periodicalSettlement` | boolean | Időszakos elszámolás (NAV `periodicalSettlement`). Alapértelmezés `false`. Magyar név: `idoszakosElszamolas`. |

Az időszak a PDF-en és a nyilvános számlaoldalon is megjelenik. A
`performanceDate`-et (teljesítés dátuma) nem változtatja meg, a NAV továbbra
is azt kapja `invoiceDeliveryDate`-ként. A sztornó és a helyesbítés az
eredeti számla időszakát viszi tovább.

### Előfizetések — `invoicePeriod`, `periodicalSettlement`

A `POST /public/v1/subscriptions` és a `PATCH /public/v1/subscriptions/:id` hívásban:

| Mező | Megjegyzés |
|---|---|
| `invoicePeriod` | `"NONE"` (alapértelmezés: nincs időszak), `"CURRENT"` (a számla ütemezett napjával kezdődő számlázási időszak, a következő számla előtti napig) vagy `"PREVIOUS"` (a számla napja előtti nappal záruló számlázási időszak). A `billingCycle` alapján számoljuk; a hónapból hiányzó nap helyett a hónap utolsó napját vesszük. Magyar név: `szamlaIdoszak`; értékek: `NINCS`, `AKTUALIS`, `ELOZO`. |
| `periodicalSettlement` | Minden generált számlára átkerül. Alapértelmezés `false`. |

Mindkettőt visszaadja a `GET /public/v1/subscriptions/:id`, valamint a
létrehozás és a PATCH válasza.

### Pénzforgalmi elszámolás és kisadózó

Két cégbeállítás (vezérlőpult: Beállítások → Cégprofil → Számlajelölések), nem
kérésmező: pénzforgalmi elszámolás (NAV `cashAccountingIndicator`, „… ha az
szerepel a számlán - ÁFA tv. 169. § h)”; a PDF-en ekkor „Pénzforgalmi
elszámolás” szerepel) és kisadózó (NAV `smallBusinessIndicator`, csak
jelentjük). Kiállításkor a számlán rögzítjük őket, így egy későbbi módosítás a
kiállított számlákat nem érinti; a sztornó és a helyesbítés az eredetiét
másolja.

### A számla-erőforrásban

A `GET /public/v1/invoices/:id`, a lista és minden számlát visszaadó végpont
a `voidedAt` után ezeket is tartalmazza: `deliveryPeriodStart`,
`deliveryPeriodEnd` (`YYYY-MM-DD` vagy `null`), `periodicalSettlement`,
`cashAccounting` és `smallBusiness` (a kiállításkor rögzített beállítás;
piszkozaton `false`).

## Kedvezmény

Számla, díjbekérő, árajánlat és előfizetés tételein és a bizonylat egészén.
Az összegeket a Bizonylat számolja ki; Ön a típust és a mértéket küldi.

**Tételkedvezmény** — a `POST /public/v1/invoices`,
`PATCH /public/v1/invoices/:id`, `POST/PATCH /public/v1/quotes`,
`POST /public/v1/subscriptions` bármely tételén:

| Mező | |
|---|---|
| `discountType` (`kedvezmenyTipus`) | `PERCENT` (`SZAZALEK`) — a mennyiség × egységár `discountValue` százaléka (0–100); `AMOUNT` (`OSSZEG`) — az egész tétel kedvezménye a bizonylat pénznemében |
| `discountValue` (`kedvezmeny`) | a százalék vagy az összeg |

Az egységár a listaár marad; a tétel nettó összege a kedvezmény utáni, az
ÁFA a kedvezményes nettóra számolódik. A NAV a `lineDiscountData/discountValue`
elemben kapja meg (interfészspecifikáció 3.0, 2.2.3.1.5), úgy, hogy
mennyiség × egységár − discountValue = lineNetAmount. `pricesIncludeVat:
true` esetén a kedvezmény a bruttó árból jön le.

**Kedvezmény a végösszegből** — `discountType` / `discountValue` magán a
bizonylaton: a nettó végösszeg `PERCENT`-je, vagy nettó `AMOUNT`. A NAV
előírása szerint a Bizonylat **ÁFA-kulcsonként egy negatív tételt** ad hozzá
(`lineKind: "INVOICE_DISCOUNT"`), a tételek arányában megosztva; ezek
közönséges tételként kerülnek az adatszolgáltatásba, soha nem
lineDiscountData-ként. Gyűjtőszámlán nem adható (`400 DISCOUNT_NOT_ALLOWED`).
`PATCH`-nél a `discountType: null` törli; a generált tételek a tételek vagy
a kedvezmény minden változásakor újra elkészülnek. Az ismétlődő számla
mindkét fajtát minden általa kiállított számlára átviszi.

A `GET /public/v1/invoices/:id/lines` minden tételen visszaadja a
`discountType`, `discountValue`, `discountAmount` (mennyiség × egységár −
nettó) és `lineKind` mezőt; a számla objektumban `discountType` és
`discountValue` szerepel. A sztornó a tételekkel együtt fordítja meg a
kedvezményt (negatív `discountAmount`); a `POST …/correct` hívásban a
tételeket úgy küldje, ahogy a `GET …/lines` adja — a `discountType`-os
tételt újraszámoljuk, az `INVOICE_DISCOUNT` tétel változatlan marad.
Elutasítás: `400 INVALID_DISCOUNT` (negatív, 100%-nál több, nagyobb a
tételnél, negatív tételen), `400 DISCOUNT_EXCEEDS_TOTAL`.

## Egyedi mezők

A cég saját mezői — szöveg, szám, dátum vagy választó — számlákhoz
(`scope: "INVOICE"`) vagy partnerekhez (`"CLIENT"`), a felületen
(Beállítások → Egyedi mezők) hozhatók létre.

| Hívás | |
|---|---|
| `GET /public/v1/custom-fields` | a mezők: `id`, `scope`, `label`, `fieldType` (`TEXT` / `NUMBER` / `DATE` / `SELECT`), `options`, `showOnPdf`, `navConventionalKey`; `?scope=INVOICE` szűr |

Az értékek a bizonylattal együtt érkeznek: `customFields`
(`egyediMezok`): `{ "<mezőazonosító>": "érték" }` a
`POST/PATCH /public/v1/invoices` és a `POST/PATCH /public/v1/clients`
hívásban. A dátum `ÉÉÉÉ-HH-NN`, a szám tizedes szám, a választó a lehetőségek
egyike, legfeljebb 500 karakter; `null` vagy `""` egy értéket töröl, a meg
nem nevezett mezők értéke marad. A válaszokban a `customFields` a tárolt
formában szerepel: `fieldId`, `scope`, `label`, `type`, `value`,
`showOnPdf`.

A `showOnPdf` mezők a PDF-en további adatként jelennek meg; kiállításkor a
vevő látható partnermezői is a számlára kerülnek, így egy későbbi átnevezés
vagy módosítás nem változtatja meg a kiállított számlát. Az egyedi mező nem
NAV-adat — kivéve azt a számlamezőt, amelyet a NAV egyezményes adatainak
(conventionalInvoiceInfo) egyik listájához rendelt (`navConventionalKey`,
pl. `orderNumbers`): értéke kiállításkor a számla `conventionalInfo`
adatai közé kerül. Elutasítás: `400 CUSTOM_FIELD_INVALID`,
`404 CUSTOM_FIELD_NOT_FOUND`.

## Számlamelléklet

Fájlok számlán / díjbekérőn vagy árajánlaton: PDF, JPEG, PNG, XLSX vagy CSV
(a típust a tartalomból olvassuk ki), fájlonként legfeljebb **10 MB**,
bizonylatonként legfeljebb **5**. Jogosultság: `invoices:read` /
`invoices:write` (árajánlatnál `quotes:read` / `quotes:write`).

| Hívás | |
|---|---|
| `GET /public/v1/invoices/:id/attachments` | lista: `id`, `fileName`, `contentType`, `sizeBytes`, `sha256`, `createdAt` |
| `POST /public/v1/invoices/:id/attachments` | feltöltés: `{ "fileName": "…", "data": "<Base64>" }` (`fajlnev`, `tartalom`) → `201` |
| `GET /public/v1/invoices/:id/attachments/:attachmentId` | a fájl |
| `DELETE /public/v1/invoices/:id/attachments/:attachmentId` | eltávolítás → `204` |
| (ugyanígy a `/public/v1/quotes/:id/attachments` alatt) | |

A melléklet nem része a számlának és nem kerül a NAV-hoz; kiállítás után is
csatolható vagy eltávolítható (naplózzuk). A számla e-mailje csatolja őket,
amíg a PDF-fel együtt 10 MB alatt maradnak; ami nem fér bele, letöltési
linkként megy. A vevő a számla online nézetéből letöltheti őket. Elutasítás:
`400 DOCUMENT_ATTACHMENT_TYPE_NOT_ALLOWED`, `400 ATTACHMENT_ACTIVE_CONTENT`
(JavaScriptet tartalmazó PDF, makrós munkafüzet),
`400 ATTACHMENT_HEIC_NOT_SUPPORTED`, `413 ATTACHMENT_TOO_LARGE`,
`409 ATTACHMENT_LIMIT_REACHED`.

## Ügyfelek

Minden kéréshez szükséges az `Authorization: Bearer <API_KULCS>` fejléc. Az
ügyfelek a kulcs cégéhez tartoznak; más cég ügyfelének azonosítójára `404`
a válasz.

### GET /public/v1/clients

Az aktív ügyfelek listája, a legújabbal kezdve.

| Paraméter | Alapértelmezés | Megjegyzés |
|---|---|---|
| `page` | `1` | |
| `limit` | `20` | legfeljebb 100 |
| `search` | — | részlet a névből, e-mail-címből vagy adószámból |
| `taxNumber` | — | pontos egyezés, `NNNNNNNN-N-NN` (hibás formátumra `INVALID_TAX_NUMBER`) |
| `email` | — | pontos egyezés, kis- és nagybetű nem számít |

Válasz: `{ "data": [ügyfél…], "pagination": { "page", "limit", "total", "totalPages" } }`

Keresés saját azonosító alapján: az ügyféladatlapon nincs külső azonosító
mező. Használja a `taxNumber` (cégek) vagy az `email` (magánszemélyek)
szűrőt, vagy tárolja el a létrehozáskor visszakapott Bizonylat `id`-t.

### GET /public/v1/clients/:id

`{ "data": ügyfél }`. Archivált ügyfélre `404`.

### POST /public/v1/clients

```json
{
  "name": "Minta Kft.",
  "taxNumber": "12345678-2-41",
  "euVatId": "HU12345678",
  "email": "szamla@minta.hu",
  "phone": "+36 1 234 5678",
  "address": "Fő utca 1.",
  "city": "Budapest",
  "postalCode": "1011",
  "country": "HU",
  "emailLocale": "hu",
  "defaultPaymentTermsDays": 8,
  "defaultPaymentMethod": "BANK_TRANSFER",
  "currency": "HUF",
  "notes": "…"
}
```

Csak a `name` kötelező. Az ellenőrzés ugyanaz, mint a felület ügyfélűrlapján:

- `taxNumber`: `NNNNNNNN-N-NN`, ÁFA-kód 1–5, megyekód 01–99, különben
  `400 INVALID_TAX_NUMBER`. (A mod-11 ellenőrzőszámot a NAV-beküldés
  ellenőrzi, nem ez a hívás — a cégnyilvántartás saját tesztadatai sem
  felelnek meg neki.)
  Az API nem kérdezi le az adószámhoz tartozó céget. Ha a cég nevét,
  székhelyét és adószámát az adószám alapján szeretné kitölteni, használja a
  [Felho API-t](https://felho.hu/api) (testvérszolgáltatásunk, ingyenes
  fiókkal és API-kulccsal; a felület automatikus kitöltése is erre épül), az
  eredményt pedig küldje el ide.
- `euVatId`: tagállami áfa-előtag (Görögországé `EL`; a `GB`, `XI`, `CH`
  nem tagállam) + 2–12 karakter, magyarnál `HU` + 8 számjegy, és akkor csak
  a teljes `taxNumber` mellett, különben `400 INVALID_EU_VAT_ID`. Nagybetűsen
  tároljuk.
- `thirdStateTaxId` (magyar mezőnév: `harmadikOrszagbeliAdoazonosito`): EU-n
  kívüli vevő adóazonosítója (szerb PIB, emírségekbeli TRN, japán cégszám,
  svájci UID, brit VAT, amerikai EIN…). 1–50 betű, számjegy, szóköz, `-` `.`
  `/`; levágott szóközökkel, nagybetűsen tároljuk. EU-n kívüli `country` kell
  hozzá. Közösségi adószám (az `euVatId` mezőbe való), magyar adószám
  (`taxNumber`), hiányzó, `HU` vagy EU-s `country` →
  `400 INVALID_THIRD_STATE_TAX_ID`. A NAV-hoz `OTHER` + `thirdStateTaxId`.
- `groupMemberTaxNumber` (magyar mezőnév: `csoporttagAdoszam`): magyar
  áfacsoport tagjának saját adószáma, `NNNNNNNN-4-NN`, ha a `taxNumber` a
  csoportazonosító szám (áfakód 5), különben
  `400 INVALID_GROUP_MEMBER_TAX_NUMBER`. A NAV-hoz a
  `customerTaxNumber/groupMemberTaxNumber` elemben megy.
- Magyar `taxNumber` `HU` (vagy üres) `country` mellett a fentiek szerint;
  más ország mellett (magyar áfaalanyként nyilvántartott külföldi cég) csak
  `NNNNNNNN-N-NN` alakban, érvényes ellenőrző számjeggyel, különben
  `400 INVALID_TAX_NUMBER`, a `thirdStateTaxId` / `euVatId` mezőre utalva. Mindez formai ellenőrzés —
  nincs VIES- vagy nyilvántartás-lekérdezés. `PATCH` esetén a tárolt
  rekorddal együtt ellenőrizzük, csak ha a kérés ezek egyikét vagy a
  `country` mezőt küldi; a `null` törli a mezőt. Lásd: *Vevőazonosítók és a
  NAV-adat*.
- `email`: érvényes cím. `country`: ISO 3166-1 kétbetűs kód (nagybetűsen
  tároljuk, alapértelmezés `HU`); a gyakori hárombetűs kódokat (`HUN`) és a
  magyar/angol országneveket (`Magyarország`, `Germany`) átalakítjuk; minden
  másra `400 INVALID_COUNTRY` a válasz.
- `emailLocale`: az ügyfél nyelve a bizonylatokhoz és e-mailekhez —
  `hu`, `en`, `de`, `ro`, `sr`, `lv`, `uk`, `bg`, `bs`, `da`, `el`, `et`, `fi`, `fr`, `hr`, `is`, `ja`, `lt`, `mk`, `nl`, `sk`, `sl`, `sq`, `sv`, `tr`, `ar`
  (a `GET /public/v1/reference/languages` a nevükkel együtt listázza).
- `defaultPaymentMethod`: `BANK_TRANSFER`, `CASH`, `CARD`, `VOUCHER`, `COD`, `OTHER`.

Válasz `201`: `{ "data": ügyfél }`. Nincs duplikációszűrés: ha „keresd meg
vagy hozd létre” működés kell, előbb keressen `taxNumber`/`email` alapján
(vagy hagyja, hogy a számla/árajánlat hívás hozza létre az ügyfelet).

### PATCH /public/v1/clients/:id

A létrehozási mezők tetszőleges része. A `null` törli az opcionális mezőt
(a `name`-et nem). Az ellenőrzés ugyanaz, mint létrehozáskor.

### DELETE /public/v1/clients/:id

Archiválja az ügyfelet, ahogy a felületen a törlés: eltűnik a listákból és
`404`-et ad, de a rá hivatkozó bizonylatok megtartják.
Válasz: `{ "data": { "id", "isActive": false } }`.

## Termékek

A termékkatalógus. A `GET /public/v1/products` (lista) és a
`POST /public/v1/products/sync` (tömeges frissítés SKU alapján) fent
szerepel; az alábbi végpontok egyenként kezelik a termékeket.

### A termék objektum

```json
{
  "id": "…",
  "sku": "CONSULT-1",
  "name": "Tanácsadás",
  "description": null,
  "unit": "óra",
  "unitPrice": "25000.00",
  "vatRate": "27.00",
  "vatCategory": "STANDARD",
  "isActive": true,
  "createdAt": "…",
  "updatedAt": "…"
}
```

A `unitPrice` a termékre hivatkozó tételek nettó alapára; a `vatRate`
**százalék**, mint az API-ban mindenhol.

### GET /public/v1/products/:id

`{ "data": termék }`. Inaktivált termékre `404`.

### POST /public/v1/products

```json
{ "name": "Tanácsadás", "sku": "CONSULT-1", "unit": "óra", "unitPrice": 25000, "vatRate": 27, "vatCategory": "STANDARD" }
```

- A `name` kötelező. Az `sku` opcionális (max. 100 karakter), cégenként
  egyedi — foglalt cikkszámra `409 PRODUCT_SKU_TAKEN`. SKU-val rendelkező
  termék számla- és árajánlat-tételben `{ "sku", "quantity" }` formában
  használható.
- `unitPrice`: nemnegatív szám, legfeljebb 9 999 999 999 999,99
  (`400 AMOUNT_OUT_OF_RANGE`). `vatRate`: 27, 18, 5 vagy 0 — ezekkel a
  kulcsokkal jelentjük az ÁFA-kategóriákat a NAV-nak (alapértelmezés 27). A
  terméket összeillő párként tároljuk: az egyedül küldött kategória a saját
  kulcsát kapja (REDUCED 18, REDUCED_MORE 5, a 0%-osak 0), az egyedül küldött
  kulcs az ahhoz tartozó kategóriát (27 STANDARD, 18 REDUCED, 5 REDUCED_MORE),
  a 0-hoz pedig `vatCategory` is kell (hacsak a terméknek már nincs 0%-os
  kategóriája). Más kulcs, vagy a kategóriáétól eltérő kulcs:
  `400 VAT_RATE_CATEGORY_MISMATCH`. Ugyanez érvényes a
  `POST /public/v1/products/sync` hívásra.
- `vatCategory` (alapértelmezés `STANDARD`): `STANDARD`, `REDUCED`,
  `REDUCED_MORE`, `ZERO`, `AAM`, `TAM`, `DOMESTIC_REVERSE_CHARGE`, `EU_REVERSE_CHARGE`,
  `EU_GOODS_SUPPLY`, `EXPORT_GOODS`, `THIRD_COUNTRY_SUPPLY`, `OUT_OF_SCOPE`,
  `MARGIN_TRAVEL_AGENCY`, `MARGIN_SECOND_HAND`, `MARGIN_ARTWORK`, `MARGIN_ANTIQUES`
  (különbözet szerinti szabályozás, 0%).
  A megszűnt `EXEMPT` értékre `422 LEGACY_VAT_CATEGORY` a válasz (a NAV-nál
  nincs rá kód).
- `productCodes`, `lineNature`, `intermediatedService` (opcionális): NAV-alapértékek,
  amelyek a termékből készült számlatételekre kerülnek (a tétel küldhet
  sajátot). A számlatételekkel azonos szabályok (`400 INVALID_PRODUCT_CODE`);
  `PATCH` esetén elhagyva változatlan, `null` / `[]` / `false` törli.

Válasz `201`: `{ "data": termék }`.

### PATCH /public/v1/products/:id

A létrehozási mezők tetszőleges része, azonos ellenőrzéssel. A
`"sku": null` és a `"unitPrice": null` törli az értéket.

### DELETE /public/v1/products/:id

Inaktiválja a terméket, ahogy a felület (a bizonylatok továbbra is
hivatkoznak rá; szinkronizált SKU a következő, azt tartalmazó szinkronnal
visszakerül). Válasz: `{ "data": { "id", "isActive": false } }`.

### Hibák

| Státusz | Kód | Mikor |
|---|---|---|
| 400 | `INVALID_TAX_NUMBER` | hibás formátumú magyar adószám, vagy `HU`-tól eltérő `country` mellett nem `NNNNNNNN-N-NN` alakú, érvényes ellenőrző számjegyű adószám |
| 400 | `INVALID_EU_VAT_ID` | hibás formátumú vagy nem tagállami előtagú közösségi adószám, illetve magyar közösségi adószám teljes `taxNumber` nélkül |
| 400 | `INVALID_THIRD_STATE_TAX_ID` | hibás formátumú `thirdStateTaxId`, benne közösségi vagy magyar adószám, vagy nincs EU-n kívüli `country` |
| 400 | `INVALID_GROUP_MEMBER_TAX_NUMBER` | `groupMemberTaxNumber` csoportazonosító (áfakód 5) nélküli `taxNumber` mellett, vagy nem 4-es áfakóddal |
| 400 | `INVALID_COUNTRY` | a `country` nem felismerhető ország (ISO-kód vagy országnév) |
| 400 | `AMOUNT_OUT_OF_RANGE`, `VAT_RATE_CATEGORY_MISMATCH` | túl nagy termékár; olyan ÁFA-kulcs, amellyel egyik kategóriát sem jelentjük, vagy nem a kategória kulcsa |
| 400 | — | egyéb érvénytelen mező (az üzenet megnevezi) |
| 404 | — | ismeretlen vagy más céghez tartozó azonosító, archivált/inaktivált rekord |
| 409 | `PRODUCT_SKU_TAKEN` | a cikkszám már szerepel a katalógusban |
| 422 | `LEGACY_VAT_CATEGORY` | `vatCategory: "EXEMPT"` |

A kóddal ellátott hibák formája: `{ "message", "error": { "code", "message", … } }`.

## Árajánlatok

Egy árajánlat útja: **DRAFT → SENT → (VIEWED) → ACCEPTED / REJECTED →
CONVERTED**. A piszkozatot létrehozza és szerkeszti, majd elküldi (az ügyfél
egy linken elfogadhatja vagy elutasíthatja), elfogadás után pedig
számlapiszkozattá, díjbekérő-piszkozattá vagy ismétlődő előfizetéssé
alakítja. Minden kéréshez szükséges az `Authorization: Bearer <API_KULCS>`
fejléc; más cég árajánlatának azonosítójára `404` a válasz.

### Az árajánlat objektum

```json
{
  "id": "…",
  "quoteNumber": "AJ-2026-000012",
  "status": "SENT",
  "clientId": "…",
  "clientName": "Ajánlatkérő Kft.",
  "currency": "HUF",
  "issueDate": "2026-09-29T00:00:00.000Z",
  "validUntil": "2026-12-31T00:00:00.000Z",
  "netTotal": "224000.00",
  "vatTotal": "60480.00",
  "grossTotal": "284480.00",
  "notes": "Az ajánlaton megjelenik",
  "internalNotes": "Az ügyfél sosem látja",
  "publicUrl": "https://app.bizonylat.hu/q/…",
  "convertedTo": null,
  "convertedDocumentId": null,
  "createdAt": "…",
  "updatedAt": "…",
  "lines": [
    { "id": "…", "productId": null, "name": "Weboldal készítés", "description": null,
      "quantity": "1.0000", "unit": "db", "unitPrice": "200000.00", "netAmount": "200000.00",
      "vatRate": 27, "vatCategory": "STANDARD", "vatAmount": "54000.00", "grossAmount": "254000.00",
      "lineOrder": 0 }
  ]
}
```

A `quoteNumber`, az `issueDate` (ha nem adta meg) és a `publicUrl` az első
küldéskor jön létre. A `lines` az egyedi lekérdezésekben szerepel, a
listában nem. A `vatRate` százalék.

### GET /public/v1/quotes

| Paraméter | Alapértelmezés | Megjegyzés |
|---|---|---|
| `page` | `1` | |
| `limit` | `20` | legfeljebb 100 |
| `status` | — | egy státusz vagy több vesszővel, pl. `SENT,VIEWED` |
| `clientId` | — | egy ügyfél árajánlatai |

Válasz: `{ "data": [árajánlat…], "pagination": { … } }`, a legújabbal kezdve.

### GET /public/v1/quotes/:id

`{ "data": árajánlat }` a `lines` tételekkel.

### POST /public/v1/quotes

```json
{
  "client": { "name": "Ajánlatkérő Kft.", "taxNumber": "23456789-2-13", "email": "info@ajanlatkero.hu" },
  "lines": [
    { "name": "Weboldal készítés", "quantity": 1, "unitPrice": 200000, "vatRate": 27 },
    { "sku": "HOSTING-12", "quantity": 1 }
  ],
  "currency": "HUF",
  "validUntil": "2026-12-31",
  "notes": "Az ajánlat 30 napig érvényes."
}
```

| Mező | Kötelező | Megjegyzés |
|---|---|---|
| `clientId` **vagy** `client` | igen | meglévő ügyfél azonosítója, vagy beágyazott ügyfél, amelyet a `POST /public/v1/invoices` szabályaival keresünk meg vagy hozunk létre (adószám, ennek híján közösségi adószám, majd e-mail, végül név). A beágyazott `taxNumber` és `euVatId` ellenőrzése ugyanaz, mint a `POST /public/v1/clients` hívásnál |
| `lines` | igen | 1–100 tétel, a számlatételekkel azonos formában (lásd *Tétel-formátumok*): beágyazott, `{ "sku", "quantity" }` vagy `{ "productId", "quantity" }`. Negatív tétel megengedett, nulla mennyiség nem |
| `pricesIncludeVat` | nem | `true` = a `unitPrice` bruttó, mint a számláknál |
| `currency` | nem | alapértelmezés `HUF` |
| `issueDate`, `validUntil` | nem | `ÉÉÉÉ-HH-NN` |
| `notes` | nem | megjelenik az ajánlaton |
| `internalNotes` | nem | az ügyfél sosem látja |

Az összegeket a szerver számolja. `vatCategory: "EXEMPT"` tételre
(közvetlenül vagy a termékből) `422 LEGACY_VAT_CATEGORY` a válasz — ebből
az ajánlatból sosem lehetne számlát kiállítani. Válasz `201`:
`{ "data": árajánlat }` (`DRAFT` státusszal).

### PATCH /public/v1/quotes/:id

**Csak piszkozat** — minden más státuszra `409 QUOTE_NOT_EDITABLE` (az
`error.status` mezővel). A létrehozási mezők tetszőleges része küldhető; a
`lines` az összes tételt lecseréli és újraszámolja az összegeket. A `null`
törli az `issueDate`, `validUntil`, `notes`, `internalNotes` értékét.

### DELETE /public/v1/quotes/:id

**Csak piszkozat** (nincs sorszáma, senki nem látta); egyébként
`409 QUOTE_NOT_EDITABLE`. Válasz: `{ "data": { "id", "deleted": true } }`.

### POST /public/v1/quotes/:id/send

Az első küldéskor sorszámot ad (`AJ-ÉÉÉÉ-NNNNNN`), új nyilvános linket
készít (`publicUrl`; a korábbi linkek megszűnnek), `SENT` állapotba teszi,
és e-mailben elküldi a linket az ügyfélnek.

```json
{ "to": "valaki@example.com", "subject": "Ajánlatunk", "body": "Tisztelt …" }
```

Mind opcionális: a `to` felülírja az ügyfél e-mail-címét, a `subject`/`body`
a cég alapértelmezett levélszövegét. Válasz: `{ "data": árajánlat + "emailTo" }`
— az `emailTo` a cím, ahová a levél ment; `null`, ha nem volt cím (az
ajánlat ettől még elküldöttnek számít). `SENT`/`VIEWED`/`EXPIRED` ajánlat
újraküldhető; `ACCEPTED`, `REJECTED` vagy `CONVERTED` állapotúra
`409 QUOTE_NOT_SENDABLE` a válasz.

Az ügyfél a `publicUrl` oldalon fogad el vagy utasít el; kérdezze le a
`GET /public/v1/quotes/:id` végponttal (vagy szűrje a listát
`status=ACCEPTED` szerint).

### GET /public/v1/quotes/:id/pdf

Az árajánlat PDF-je (`Content-Type: application/pdf`), bármely státuszban.

### POST /public/v1/quotes/:id/convert

```json
{ "to": "INVOICE", "paymentMethod": "BANK_TRANSFER", "notes": "…" }
```

| Mező | Megjegyzés |
|---|---|
| `to` | **kötelező**: `INVOICE` (számla), `PROFORMA` (díjbekérő) vagy `SUBSCRIPTION` (előfizetés) |
| `paymentMethod` | `BANK_TRANSFER` (alapértelmezés), `CASH`, `CARD`, `VOUCHER`, `COD`, `OTHER` |
| `notes` | alapértelmezés: az ajánlat megjegyzése |
| `billingCycle` | csak `SUBSCRIPTION`: `MONTHLY` (alapértelmezés) vagy `ANNUAL` |
| `paymentTermsDays` | csak `SUBSCRIPTION`, alapértelmezés 30 |

Csak **ACCEPTED** (elfogadott) ajánlat alakítható át, egyébként
`409 QUOTE_NOT_ACCEPTED` (az `error.status` mezővel). A tételek és összegek
változatlanul átkerülnek:

- `INVOICE` / `PROFORMA` → **piszkozat**. Még nincs sorszám és NAV-beküldés:
  állítsa ki a `POST /public/v1/invoices/:id/issue` hívással (díjbekérőt
  utána a szokásos `/convert` hívással alakíthat tovább).
- `SUBSCRIPTION` → `ACTIVE` előfizetés; az első számla havi ciklusnál a
  következő hónap 1-jén, évesnél a következő napi futáskor készül el.

Válasz `201`:

```json
{ "data": { "quoteId": "…", "convertedTo": "INVOICE",
  "invoice": { "id": "…", "invoiceNumber": null, "status": "DRAFT", "invoiceType": "STANDARD",
               "grossTotal": "284480.00", "sourceQuoteId": "…", … } } }
```

(`SUBSCRIPTION` esetén `"subscription": { "id", "status", "billingCycle", "startDate", "nextInvoiceDate", … }`.)

**Idempotens.** Egy ajánlat egyszer alakítható át. Minden későbbi hívás —
újrapróbálás vagy más `to` — nem hoz létre semmit, és `409` a válasz:

```json
{ "message": "…",
  "error": { "code": "QUOTE_ALREADY_CONVERTED", "convertedTo": "INVOICE", "documentId": "…" },
  "data": { "quoteId": "…", "convertedTo": "INVOICE", "invoice": { … } } }
```

A `data` az első hívás által létrehozott bizonylat, a sikeres válasz
formájában, így az újrapróbálás egyszerűen eltárolhatja.

### Hibák

| Státusz | Kód | Mikor |
|---|---|---|
| 400 | `INVALID_TAX_NUMBER` | a beágyazott ügyfél adószáma hibás formátumú |
| 400 | `INVALID_EU_VAT_ID` | a beágyazott ügyfél közösségi adószáma hibás formátumú |
| 400 | `INVALID_THIRD_STATE_TAX_ID`, `INVALID_GROUP_MEMBER_TAX_NUMBER` | a beágyazott ügyfél `thirdStateTaxId` / `groupMemberTaxNumber` mezője nem fogadható el (lásd: *Vevőazonosítók és a NAV-adat*) |
| 400 | `INVALID_COUNTRY` | a beágyazott ügyfél `country` mezője nem kétbetűs ISO-kód |
| 400 | `DATE_RANGE_INVALID` | a `validUntil` korábbi az `issueDate`-nél (PATCH-nél a módosítás utáni értékekkel) |
| 400 | `AMOUNT_OUT_OF_RANGE`, `INVALID_NUMBER`, `VAT_RATE_CATEGORY_MISMATCH` | tételek, mint a `POST /public/v1/invoices` hívásban |
| 400 | — | érvénytelen adat (ismeretlen SKU/productId, nulla mennyiség, `client` és `clientId` együtt vagy egyik sem…) |
| 404 | — | ismeretlen vagy más cég árajánlata, ismeretlen/archivált `clientId` |
| 409 | `QUOTE_NOT_EDITABLE` | PATCH/DELETE nem piszkozat ajánlaton |
| 409 | `QUOTE_NOT_SENDABLE` | küldés elfogadott, elutasított vagy átalakított ajánlatra |
| 409 | `NAV_CONNECTION_REQUIRED` | létrehozás (vagy díjbekérővé alakítás), mielőtt a cégnek ellenőrzött NAV-kapcsolata lenne |
| 409 | `NAV_CONNECTION_REQUIRED_FOR_EMAIL` | küldés ellenőrzött NAV-kapcsolat előtt — az ajánlat piszkozat marad, semmi nem megy ki |
| 403 | `ACCOUNT_UNDER_REVIEW` / 409 `EMAIL_HELD_FOR_REVIEW` | a cég ellenőrzésre vár: új ajánlat nem hozható létre, a küldés visszatartva |
| 409 | `QUOTE_NOT_ACCEPTED` | átalakítás az ügyfél elfogadása előtt |
| 409 | `QUOTE_ALREADY_CONVERTED` | ismételt átalakítás — a `data` a meglévő bizonylat |
| 422 | `LEGACY_VAT_CATEGORY` | egy tétel `EXEMPT` kategóriát használ |

## Bejövő számlák és kiadások — /public/v1/expenses

Jogosultság: minden alábbi híváshoz `expenses:write` (a kézzel létrehozott kulcs mindegyiket elérheti).

A cég bejövő (beszállítói) számlái: a NAV Online Számlából importáltak és a
kézzel rögzítettek, **számlánként egy sorban**. Ha egy magyar szállítói
adószámmal rögzített tételt később a NAV-ból is beimportálunk (azonos
szállítói adószám és számlaszám), összekapcsoljuk, nem duplikáljuk: a
`source` `MANUAL` marad, a `hasNavData` `true` lesz, az összegek a NAV
szerintiek, a csatolt fájlok és megjegyzések megmaradnak. Ezek költségek:
semmi nem számít bevételnek, és semmit nem küldünk a NAV-nak.

| Hívás | |
|---|---|
| `GET /public/v1/expenses` | lista; `search`, `from`, `to` (kelte), `source` (`all` / `manual` / `nav`), `accounting` (`all` / `counted` / `excluded`), `page`, `limit` ≤ 100. `meta.totals`: a könyvelésbe kerülők pénznemenkénti összege |
| `GET /public/v1/expenses/categories` | a cég kategóriái (alapértelmezetten: Anyag, Szolgáltatás, Rezsi, Utazás, Egyéb) |
| `GET /public/v1/expenses/:id` | egy sor `vatBreakdown`, `attachments` (adatok) és NAV `details` mezőkkel |
| `POST /public/v1/expenses` | kézi rögzítés (`Idempotency-Key` használható) |
| `PATCH /public/v1/expenses/:id` | kézi tétel adatai (amíg a NAV nem találja meg); `categoryId` / `categoryName`, `note`, `paid`, `paidDate` bármely soron |
| `DELETE /public/v1/expenses/:id` | a NAV által még meg nem talált kézi tétel (egyébként `409 EXPENSE_NAV_DATA_LOCKED`) |

A kérés törzse és a mezők szabályai megegyeznek az angol leírásban szereplő
példával:

- `vatLines`: kulcsonként egy sor, legfeljebb 10. `vatRate`: `27`, `18`,
  `5`, `0`, `AAM`, `TAM`, `FAD` (fordított adózás), `ATK` (áfa
  hatályán kívül). Az összegek a bizonylat szerint, legfeljebb 2
  tizedesjeggyel; a `grossAmount` elhagyható (nettó + ÁFA). A `0`, `AAM`,
  `TAM`, `FAD` és `ATK` sorban nincs ÁFA; százalékos kulcsnál az ÁFA-nak
  illenie kell a kulcshoz (kerekítés miatt 1 egység vagy a nettó 0,5%-a az
  eltérés) — különben `400 EXPENSE_VAT_AMOUNT_MISMATCH`.
- A `supplierTaxNumber` nem kötelező, és úgy ellenőrizzük, mint a
  partnerekét (`400 INVALID_TAX_NUMBER`). Megadása esetén ugyanaz a szállító
  + számlaszám nem rögzíthető kétszer: `409 EXPENSE_ALREADY_RECORDED`, az
  `error.existingId` és az `error.existingSource` (`NAV` vagy `MANUAL`)
  mezővel.
- `paymentMethod`: `TRANSFER`, `CASH`, `CARD`, `VOUCHER`, `OTHER`.
- A lista sorai ugyanazokat a mezőket tartalmazzák, mint a felület Bejövő
  számlák listája, köztük `source`, `hasNavData`, `categoryName`,
  `paid`, `attachmentCount`. Fájlt (fotót, PDF-et) a felületen lehet csatolni.

## Szállítólevél és teljesítésigazolás

A **szállítólevél** (`DELIVERY_NOTE`) az átadott árut, a **teljesítésigazolás**
(`COMPLETION_CERTIFICATE`) az elvégzett munkát dokumentálja, a megrendelő
aláírásával. Egyik sem számla: **a NAV-nak soha nem kerülnek beküldésre**,
ÁFA-fizetési kötelezettséget nem keletkeztetnek, számlaszámot nem kapnak
(`reportsToNav` mindig `false`). Jogosultság: `invoices:read` / `invoices:write`.

Állapot: **DRAFT → ISSUED → (VOIDED)**. Kiállításkor a dokumentum a cég
típusonkénti, évenkénti saját sorszámát kapja (`SZL-2026-000001`,
`TIG-2026-000001`) és egy vevői oldalt (`publicUrl`); a kiállított dokumentum
nem módosítható és nem törölhető, csak érvényteleníthető (a sorszám megmarad).
Az ár tételenként nem kötelező — szállítólevélen gyakran nincs (`showPrices`
alapértéke szállítólevélnél `false`, teljesítésigazolásnál `true`). A PDF-en
aláírásmezők vannak, és szerepel rajta, hogy nem számla.

| Metódus | Útvonal | |
|---|---|---|
| GET | `/public/v1/delivery-documents` | lista; `docType`, `status` (vesszővel több), `clientId`, `uninvoiced=true`, `page`, `limit` |
| GET | `/public/v1/delivery-documents/{id}` | tételekkel |
| POST | `/public/v1/delivery-documents` | piszkozat; `"issue": true` esetén azonnal kiállítva |
| PATCH | `/public/v1/delivery-documents/{id}` | csak piszkozat; a `lines` minden tételt lecserél |
| DELETE | `/public/v1/delivery-documents/{id}` | csak piszkozat |
| POST | `/public/v1/delivery-documents/{id}/issue` | sorszámozás |
| POST | `/public/v1/delivery-documents/{id}/void` | `{ "reason"? }`; csak kiállított, számlázatlan |
| POST | `/public/v1/delivery-documents/{id}/send` | a vevői oldal elküldése e-mailben; `{ "to"?, "subject"?, "body"? }` |
| GET | `/public/v1/delivery-documents/{id}/pdf` | PDF |
| POST | `/public/v1/delivery-documents/convert-to-invoice` | `{ "documentIds": [...] }` → egy **számlapiszkozat** |

Létrehozás: `docType`, `clientId` vagy beágyazott `client`, `lines[]` (`name`
vagy `productId` / `sku`, `quantity`, `unit`, nem kötelező nettó `unitPrice`,
`vatRate` százalékban, `vatCategory`), valamint `issueDate`,
`fulfilmentDate` (szállítás / teljesítés napja) vagy `periodStart` +
`periodEnd`, `deliveryAddress`, `projectReference` és `orderReference`
(egyenként legfeljebb 100 karakter), `showPrices`, `notes`, `internalNotes`,
`currency`.

```bash
curl -X POST https://api.bizonylat.hu/public/v1/delivery-documents \
  -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
  -d '{ "docType": "DELIVERY_NOTE", "clientId": "…", "issue": true,
        "deliveryAddress": "1118 Budapest, Rétköz utca 5.", "projectReference": "PRJ-7",
        "lines": [{ "sku": "CSEMPE-3060", "quantity": 42.5, "unit": "m2" }] }'
```

**Számla készítése.** Egy vagy több, azonos vevőnek azonos pénznemben kiállított
dokumentumból egy SZÁMLAPISZKOZAT készül: a tételeik (a dokumentum ára, vagy ha
nem volt, a termék alapára — ezek száma `linesWithoutPrice`), a szállítólevelek
száma a számla `conventionalInfo.deliveryNotes` („Szállítólevél szám”) adatába,
az `orderReference` az `orderNumbers`, a `projectReference` a `projectNumbers`
adatba, a teljesítésigazolások száma a megjegyzésbe kerül, a `performanceDate`
pedig a legkésőbbi szállítási / teljesítési nap (ellenőrizendő). Itt semmi nem
kerül kiállításra vagy a NAV-hoz: a piszkozatot a `POST /public/v1/invoices/{id}/issue`
állítja ki. Egy dokumentum egyszer alakítható át; ismételt hívásra
`409 DELIVERY_DOCUMENT_ALREADY_INVOICED` a válasz az `error.invoiceId` mezővel.
A számlapiszkozat törlése után a dokumentumok újra átalakíthatók.

## Részletfizetés

Egy számla összegét 2–24 részletre osztja, saját fizetési határidőkkel.
Jogosultság: `invoices:read` / `invoices:write`; a részlet fizetettnek
jelöléséhez `payments:write`. A számla sorszámát, tételeit és NAV-adatait nem
változtatja.

- **Kiállított** számlán (`mode: "INVOICE"`): a még fizetendő összeg részleteit
  a számlán tartjuk nyilván. A fizetési emlékeztetők részletenként, a saját
  határidejéhez képest, a cég / az ügyfél emlékeztető-sorozata szerint mennek ki;
  a számla saját emlékeztetője az ütemezés alatt szünetel. A részlet
  fizetettnek jelölése a részlet összegével befizetést rögzít a számlán.
- **Piszkozat** számlán — tervezett értékesítés (`mode: "PROFORMA"`):
  részletenként díjbekérő-piszkozat készül a határidejével (a díjbekérő nem
  kerül a NAV-hoz); kiállítás után a szokásos díjbekérő-emlékeztetők vonatkoznak rá.

Hogy egy részletről külön számlát kell-e kiállítani, az ÁFA-kérdés, amely a
szerződéstől függ (Áfa tv. 59. § előleg, 58. § időszakonkénti fizetés, 163. §):
az API ezt nem dönti el. A teljesítés előtt kapott részlet előleg — az
előlegszámlát a díjbekérőjéből készítheti (`POST /public/v1/invoices/{id}/convert`,
`"to": "PREPAYMENT"`).

| Metódus | Útvonal | |
|---|---|---|
| GET | `/public/v1/instalment-plans` | `status` (ACTIVE, COMPLETED, CANCELLED), `invoiceId`, `clientId` |
| POST | `/public/v1/instalment-plans` | `{ "invoiceId", "count", "firstDueDate", "intervalMonths"? }` (egyenlő részletek, a maradék az utolsón) vagy `{ "invoiceId", "instalments": [{ "amount", "dueDate" }] }` (összegük a fizetendő összeg) |
| GET | `/public/v1/instalment-plans/{id}` | ütemezés részletenkénti `status` (PAID, OVERDUE, DUE) és díjbekérő adatokkal |
| POST | `/public/v1/instalment-plans/{id}/cancel` | visszavonás; az általa készített díjbekérő-piszkozatok törlődnek |
| POST | `/public/v1/instalment-plans/{id}/instalments/{instalmentId}/pay` | `{ "paidAt"?, "paymentMethod"?, "reference"? }` |

## Készlet

Termékenkénti, nem kötelező készletnyilvántartás (minden csomagban).
Jogosultság: `products:read` / `products:write`. A számla kiállítása csökkenti
a követett termékek készletét (vagy a szállítólevél kiállítása, ha a cég ezt
választotta az alkalmazásban — az ilyen szállítólevélből készült számla nem
csökkenti újra); a sztornó visszaállítja, a helyesbítő számla a
mennyiségváltozás szerint módosítja, a szállítólevél érvénytelenítése
visszaállítja. A készlet negatív is lehet — a számlázást ez nem akadályozza.
Ha eléri a termék `lowStockThreshold` értékét, a cég tulajdonosai és
adminisztrátorai csökkenésenként egyszer e-mailt kapnak.

| Metódus | Útvonal | |
|---|---|---|
| GET | `/public/v1/stock` | `tracked` (alapértelmezés `true`, `false`, `all`), `low=true`, `search`; soronként `stockQuantity`, `lowStockThreshold`, `isLow`, `isNegative`; valamint `summary` |
| PATCH | `/public/v1/stock/{productId}` | `{ "trackStock", "lowStockThreshold"?, "initialQuantity"? }` (nyitókészlet a bekapcsoláskor) |
| POST | `/public/v1/stock/{productId}/adjustments` | `{ "change" }` vagy `{ "newQuantity" }`, és kötelező `"reason"` (naplózva) |
| GET | `/public/v1/stock/{productId}/movements` | mozgások (`reason`: INVOICE_ISSUED, INVOICE_STORNO, INVOICE_CORRECTION, DELIVERY_NOTE_ISSUED, DELIVERY_NOTE_VOIDED, MANUAL_ADJUSTMENT, TRACKING_STARTED) |

### Hibák

| Státusz | Kód | Mikor |
|---|---|---|
| 409 | `DELIVERY_DOCUMENT_NOT_EDITABLE` | nem piszkozat dokumentum módosítása / törlése / kiállítása |
| 409 | `DELIVERY_DOCUMENT_NOT_ISSUED` | piszkozat vagy érvénytelenített dokumentum küldése, érvénytelenítése, átalakítása |
| 409 | `DELIVERY_DOCUMENT_ALREADY_INVOICED` | olyan dokumentum átalakítása vagy érvénytelenítése, amelyből számla készült (`error.invoiceId`) |
| 400 | `DELIVERY_DOCUMENTS_MIXED` | eltérő vevő vagy pénznem egy átalakításban |
| 400 | `INSTALMENT_PLAN_INVALID` | hibás darabszám, az összegek nem adják ki a fizetendőt, nem növekvő határidők, nem számla, kifizetett vagy sztornózott számla |
| 409 | `INSTALMENT_PLAN_EXISTS` | a számlához már tartozik aktív ütemezés |
| 409 | `INSTALMENT_ALREADY_PAID` | a részlet (vagy díjbekérője) már ki van fizetve |
| 400 | `STOCK_ADJUSTMENT_INVALID` | nincs indoklás, a `change` és a `newQuantity` közül mindkettő vagy egyik sem, nulla változás |
| 409 | `STOCK_NOT_TRACKED` | korrekció olyan terméken, amelynél nincs készletnyilvántartás |
| 409 | `NAV_CONNECTION_REQUIRED` | dokumentum létrehozása vagy kiállítása ellenőrzött NAV-kapcsolat előtt (mint az árajánlatnál) |

## Aláírások (e-aláírás)

PDF (vagy Word .docx) küldése elektronikus aláírásra, az aláírók követése, majd az aláírt,
lezárt PDF és a tanúsítvány letöltése — az alkalmazás **Aláírások** funkciója
az API-n. Az aláírók e-mailben személyes hivatkozást kapnak, e-mail-címüket
6 jegyű kóddal (vagy Bizonylat-belépéssel) igazolják, és a böngészőben írnak
alá; fiók nem kell hozzá. Az aláírás egyszerű elektronikus aláírás (eIDAS
3. cikk 10. pont); a kész fájlt a Bizonylat lezárja és időbélyegzővel látja el.

A kulcs annak a felhasználónak a nevében jár el, aki létrehozta: az olvasáshoz
az Aláírásokat látó szerepkör (bármely tag), minden máshoz **Tulajdonos, Admin
vagy Alkalmazott** kulcsa kell (különben `403 API_KEY_ROLE_FORBIDDEN`, az
`error.requiredPermission` mezővel). Csak teljes hozzáférésű kulccsal (az
összekapcsolt alkalmazás korlátozott kulcsa `403 INSUFFICIENT_SCOPE` választ kap).
A korlátok az alkalmazáséval azonosak: havonta aláírásra küldhető dokumentumok
a csomag szerint (`402 SIGNATURE_MONTHLY_LIMIT_REACHED`), cégenként 24 óra
alatt legfeljebb 50 meghívó és emlékeztető e-mail (`429 SIGNATURE_EMAIL_LIMIT_REACHED`),
a cégen kívülieknek pedig csak ellenőrzött NAV-kapcsolattal küldünk aláírási
hivatkozást — tesztcég (Tesztcég) csak a saját tagjainak.

Állapot: **DRAFT → SENT → COMPLETED**, illetve **DECLINED** (egy aláíró
elutasította), **VOIDED** (visszavonva), **EXPIRED** (lejárt a határidő).
Aláíró állapota: `PENDING` (a sorára vár), `SENT`, `VIEWED`, `SIGNED`, `DECLINED`.

| Metódus | Útvonal | |
|---|---|---|
| POST | `/public/v1/signatures` | piszkozat PDF-ből, mentett sablonból vagy beépített sablonból; `"send": true` esetén azonnal kiküldve |
| GET | `/public/v1/signatures` | lista; `status` (vesszővel több), `q` (cím, fájlnév, aláíró neve vagy e-mail-címe), `page`, `limit` |
| GET | `/public/v1/signatures/{id}` | aláírókkal (állapot, időpontok) és mezőkkel |
| PATCH | `/public/v1/signatures/{id}` | csak piszkozat; a `signers` / `fields` a teljes listát cseréli |
| DELETE | `/public/v1/signatures/{id}` | csak piszkozat |
| POST | `/public/v1/signatures/{id}/send` | az aláírási hivatkozások kiküldése (beleszámít a havi keretbe) |
| POST | `/public/v1/signatures/{id}/remind` | `{ "signerId"? }`; a soron lévő aláíróknak, aláírónként 24 óránként egyszer |
| POST | `/public/v1/signatures/{id}/void` | `{ "reason"? }`; csak SENT; a még alá nem írók értesítést kapnak |
| POST | `/public/v1/signatures/{id}/signers/{signerId}/link` | az aláíró aláírási linkje, más csatornán való elküldéshez (lásd lent) |
| GET | `/public/v1/signatures/{id}/pdf` | `version=auto` (alapértelmezés): COMPLETED után az aláírt PDF, előtte a jelenlegi állapot „nem végleges” vízjellel; `original`; `final` (befejezés előtt 409). Az `X-Signature-Pdf` fejléc: `final`, `in-progress` vagy `original` |
| GET | `/public/v1/signatures/{id}/certificate` | a tanúsítvány oldalai külön PDF-ben (az aláírt PDF-ben is benne vannak); COMPLETED előtt 409 |
| GET | `/public/v1/signature-templates` | `data.saved` (a cég sablonjai, `slots` helyekkel) és `data.builtin` (kész űrlapok, `inputs` és `roles` adatokkal) |

### Dokumentum létrehozása

Pontosan egy forrást adjon meg:

1. **PDF vagy Word-dokumentum (.docx)** (legfeljebb 20 MB; a PDF legfeljebb 100
   oldal, jelszó nélkül) — `multipart/form-data` kérésben a fájl a `file`
   mezőben, minden más egyetlen JSON-szövegként a `data` mezőben; vagy
   JSON-ban: `"file": { "filename", "contentBase64" }`. A .docx-et (a fájlnév
   alapján) a szerverünk PDF-fé alakítja, mint az alkalmazásban: az aláírók ezt
   a PDF-et írják alá, a neve a Word-fájlé, az erőforrásban pedig megjelenik a
   `convertedFrom` (`{ "format": "DOCX", "filename", "sizeBytes" }`; PDF-nél
   `null`) — küldés előtt nézze át a `GET …/pdf` eredményét. Nem fogadjuk:
   .doc és makrót tartalmazó Word-fájl.
2. **Mentett sablon**: `templateId`, és helyenként (`slotKey`) egy aláíró
   (a mezők, az üzenet és a sorrend a sablonból jön).
3. **Beépített sablon**: `builtinTemplate` (pl. `teljesitesigazolas`), az
   `inputs` a sablon adatkulcsai szerint, és aktív szerepkörönként egy aláíró
   (`role`: `company` vagy `partner`); az űrlap a cég arculatával készül,
   a mezők a helyükre kerülnek.

További mezők (mind elhagyható): `title` (alapértelmezés: a fájl vagy a sablon
neve), `message` (az e-mailben és az aláíró oldalon jelenik meg),
`signingOrder` (`PARALLEL` alapértelmezés, vagy `SEQUENTIAL` az aláírók
`signOrder` értéke szerint; azonos szám együtt ír alá), `expiresAt`
(ISO időpont, legfeljebb 180 nap múlva; alapértelmezés a küldéstől 30 nap),
`locale` (`hu` / `en`: e-mailek és aláíró oldal nyelve),
`reminderIntervalDays` (1–14, automatikus emlékeztető), `remindBeforeExpiry`.

`signers`: `[{ "name", "email", "signOrder"? }]`, legfeljebb 20, minden
e-mail-cím egyszer. `fields` (csak PDF-forrásnál), legfeljebb 500:

| Mező | |
|---|---|
| `signerIndex` / `signerEmail` / `signerId` | pontosan egy: az aláíró sorszáma a `signers` listában (0 = első), e-mail-címe, vagy (PATCH) azonosítója |
| `type` | `SIGNATURE`, `INITIALS`, `NAME`, `DATE`, `COMPANY`, `EMAIL`, `TEXT`, `CHECKBOX`, `TAX_NUMBER`, `REGISTRATION_NUMBER`, `ADDRESS`, `TITLE`, `PHONE`, `TAX_ID`, `BANK_ACCOUNT`, `BIRTH`, `MOTHER_NAME` (lásd lent) |
| `page` | 1-től számozva |
| `x`, `y`, `width`, `height` | a mező helye, lásd lent |
| `required` | alapértelmezés `true` |
| `label`, `prefill` | szöveg; a `prefill` az aláíró által módosítható kezdőérték |
| `options` | `DATE`: `{ "format" }`; `ADDRESS`: `{ "addressPart" }`; `NAME`: `{ "namePart" }` (mint az alkalmazásban) |

Mezőtípusok — mit kér az aláírótól:

| `type` | Az alkalmazásban | |
|---|---|---|
| `SIGNATURE`, `INITIALS` | Aláírás, Kézjegy | rajzolt, gépelt vagy feltöltött kép |
| `NAME`, `DATE`, `EMAIL`, `TITLE` | Név, Dátum, E-mail, Beosztás | a `DATE` értéke `ÉÉÉÉ-HH-NN` |
| `COMPANY`, `TAX_NUMBER`, `REGISTRATION_NUMBER`, `ADDRESS` | Cégnév, Adószám, Cégjegyzékszám, Cím | |
| `PHONE` | Telefonszám | 7–15 számjegy; `+` csak az elején; szóköz, `-`, `/` és zárójel megengedett (`+36 30 123 4567`, `06-30/123-4567`); ahogy beírták, úgy tároljuk |
| `TAX_ID` | Adóazonosító jel | magánszemély adóazonosító jele: 10 számjegy, 8-cal kezdődik, az ellenőrző számjegyet ellenőrizzük; 10 számjegyként tároljuk |
| `BANK_ACCOUNT` | Bankszámlaszám | belföldi számlaszám (2×8 vagy 3×8 számjegy, ellenőrző számjegyekkel) vagy IBAN (mod-97); így tároljuk: `11773016-11111018` / `HU42 1177 3016 1111 1018 0000 0000` |
| `BIRTH`, `MOTHER_NAME` | Születési hely és idő, Anyja neve | szabad szöveg |
| `TEXT`, `CHECKBOX` | Szöveg, Jelölőnégyzet | a `CHECKBOX` értéke `"true"` / `"false"` |

A hibás `PHONE`, `TAX_ID` vagy `BANK_ACCOUNT` értéket aláíráskor
elutasítjuk (az aláíró oldal még küldés előtt jelzi), így a visszaolvasott
`value` mindig a fenti tárolt alakban van. A `prefill` értékét nem ellenőrizzük.

**Koordináták.** Alapértelmezésben az oldal törtrészei: az `x` és a `width`
a szélességéé, az `y` és a `height` a magasságáé, az oldal **bal felső
sarkától**, úgy, **ahogy a PDF-olvasó mutatja** (vágódoboz, elforgatással),
az `y` lefelé nő. A mezőnek az oldalon belül kell lennie (`x + width ≤ 1`,
`y + height ≤ 1`; mindkét irányban legalább 0,005). `"fieldUnit": "pt"`
esetén PDF-pontban (1/72 hüvelyk) adja meg ugyanattól a saroktól; törtrészként
tároljuk. Az A4-es oldal 595,28 × 841,89 pt; minden oldal mérete a válasz
`pageSizes` mezőjében. Küldés előtt minden aláírónak legalább egy `SIGNATURE`
mező kell.

```bash
curl -X POST https://api.bizonylat.hu/public/v1/signatures \
  -H "Authorization: Bearer $API_KEY" -H "Idempotency-Key: szerzodes-1042" \
  -F file=@szerzodes.pdf \
  -F 'data={ "title": "Megbízási szerződés", "send": true,
             "signers": [{ "name": "Nagy Mihály", "email": "mihaly@example.com" }],
             "fields": [{ "signerIndex": 0, "type": "SIGNATURE", "page": 2,
                          "x": 0.1, "y": 0.72, "width": 0.35, "height": 0.08 },
                        { "signerIndex": 0, "type": "DATE", "page": 2,
                          "x": 0.1, "y": 0.81, "width": 0.2, "height": 0.03 }] }'
```

```json
{ "data": { "id": "…", "status": "SENT", "title": "Megbízási szerződés", "pageCount": 2,
  "pageSizes": [{ "width": 595.28, "height": 841.89 }, { "width": 595.28, "height": 841.89 }],
  "signerCount": 1, "signedCount": 0, "expiresAt": "…", "sentAt": "…",
  "files": { "original": { "sha256": "…", "size": 48213 }, "final": null, "sealStatus": null, "timestamp": null },
  "signers": [{ "id": "…", "name": "Nagy Mihály", "email": "mihaly@example.com", "status": "SENT",
    "canSignNow": true, "sentAt": "…", "viewedAt": null, "signedAt": null, "declinedAt": null, "nextReminderAt": null }],
  "fields": [{ "id": "…", "signerId": "…", "type": "SIGNATURE", "page": 2, "x": 0.1, "y": 0.72,
    "width": 0.35, "height": 0.08, "required": true, "value": null, "hasValue": false }] } }
```

Sablonból:

```json
{ "templateId": "…", "signers": [{ "slotKey": "slot_1", "name": "Kovács Anna", "email": "anna@example.com" }] }
{ "builtinTemplate": "teljesitesigazolas",
  "inputs": { "partner": { "name": "Partner Kft." }, "workDescription": "Weboldal karbantartása" },
  "signers": [{ "role": "company", "name": "Kiss Péter", "email": "peter@ceg.hu" },
              { "role": "partner", "name": "Kovács Anna", "email": "anna@example.com" }] }
```

Az elutasított piszkozat (hibás koordináta, ismeretlen aláíró) nem marad meg.
Ha a `"send": true` küldést utasítjuk el (bizalmi szabály, havi vagy napi
keret), a piszkozat **megmarad**: a hibaválasz `data` mezője tartalmazza —
szüntesse meg az okot, és hívja a `…/send` végpontot, vagy törölje. Az
`Idempotency-Key` használható (multipart feltöltésnél azonos `data` és azonos
fájl számít ugyanannak a kérésnek).

Az erőforrás soha nem tartalmazza az aláírási hivatkozásokat (egyet a
`…/signers/{signerId}/link` ad vissza), kódokat, IP-címeket és a rajzolt
aláírások képét: a `SIGNATURE` / `INITIALS` mezőnél
csak a `hasValue` látszik, a többi mezőnél aláírás után a `value`. Webhookok:
`signature.sent`, `signature.signer_signed`, `signature.completed`,
`signature.declined`, `signature.voided`, `signature.expired` — a `data`
ez az erőforrás (aláírásnál és elutasításnál a `data.signer` mezővel).

### Az aláíró linkje

A `POST /public/v1/signatures/{id}/signers/{signerId}/link` a meghívó e-mailben
szereplő személyes linket adja vissza, hogy Ön küldje el (csevegőben, SMS-ben,
saját e-mailben). Ez biztonságos: a dokumentum megtekintése előtt az aláíró az
e-mail-címére küldött kóddal igazolja magát (vagy ezzel a címmel lép be a
Bizonylatba). Csak `SENT` állapotú (és `expiresAt` előtti) dokumentumnál,
olyan aláírónak, aki még nem írta alá és nem utasította el. `canSignNow: false`:
még nem következik (`SEQUENTIAL` sorrend) — a linket megnyitva ezt látja, és
e-mailt kap, amikor sorra kerül. Minden hívás bekerül a dokumentum eseménynaplójába
(és a tanúsítványba); webhookot nem indít, e-mailt nem küld.

```json
{ "data": { "signerId": "…", "url": "https://app.bizonylat.hu/hu/sign/…", "canSignNow": true, "expiresAt": "…" } }
```

### Hibák

| Státusz | Kód | Mikor |
|---|---|---|
| 400 | `SIGNATURE_FILE_INVALID` | nem olvasható PDF vagy .docx (vagy hibás base64) |
| 413 / 400 | `SIGNATURE_FILE_TOO_LARGE` / `SIGNATURE_FILE_TOO_MANY_PAGES` / `SIGNATURE_FILE_ENCRYPTED` | 20 MB-nál nagyobb, 100 oldalnál hosszabb, jelszóval védett |
| 400 | `SIGNATURE_FILE_LEGACY_DOC` / `SIGNATURE_FILE_MACRO_DOCUMENT` / `SIGNATURE_DOCX_INVALID` | .doc, makrós Word-fájl, sérült vagy nem biztonságos .docx (`error.reason`) |
| 422 / 503 | `SIGNATURE_DOCX_CONVERSION_FAILED` / `SIGNATURE_DOCX_CONVERSION_UNAVAILABLE` | a .docx nem alakítható át; az átalakítás foglalt vagy nem érhető el (foglaltságnál `Retry-After`) — töltsön fel PDF-et |
| 400 | `SIGNATURE_DOCUMENT_INVALID` | `error.field` + `error.reason`: `OUTSIDE` (kilóg az oldalról vagy nincs ilyen oldal), `UNKNOWN_SIGNER`, `UNKNOWN_SLOT`, `MISSING` (sablonhely vagy szerepkör aláíró nélkül), `DUPLICATE`, `INVALID`, `TOO_MANY` |
| 400 | `SIGNATURE_BUILTIN_INPUT_INVALID` | beépített sablon adata (`error.field`, pl. `inputs.workDescription`) |
| 404 | `SIGNATURE_BUILTIN_TEMPLATE_NOT_FOUND` | ismeretlen `builtinTemplate` |
| 400 | `SIGNATURE_SEND_INVALID` | `error.reason`: `NO_SIGNERS`, `SIGNER_WITHOUT_SIGNATURE_FIELD`, `FIELD_OUTSIDE_PAGE`, `EXPIRY_INVALID` |
| 409 | `SIGNATURE_DOCUMENT_NOT_EDITABLE` | nem piszkozat módosítása, törlése vagy küldése |
| 409 | `SIGNATURE_DOCUMENT_NOT_ACTIVE` | emlékeztető, visszavonás vagy aláírói link nem aláírásra váró dokumentumon (a linknél `error.reason`: `DRAFT`, `COMPLETED`, `DECLINED`, `VOIDED`, `EXPIRED`) |
| 409 | `SIGNATURE_ALREADY_SIGNED` | aláírói link olyan aláírónak, aki már aláírt vagy elutasított (`error.reason`: `SIGNER_SIGNED` / `SIGNER_DECLINED`) |
| 429 | `SIGNATURE_REMINDER_TOO_SOON` | 24 órán belül már ment emlékeztető (`Retry-After`) |
| 429 | `SIGNATURE_EMAIL_LIMIT_REACHED` | 24 órán belül elérte az 50 aláírási e-mailt (`Retry-After`) |
| 402 | `SIGNATURE_MONTHLY_LIMIT_REACHED` | elfogyott a csomag havi kerete; `error.limit`, `used`, `resetsAt`, `plan` |
| 409 | `NAV_CONNECTION_REQUIRED_FOR_EMAIL` / `SANDBOX_BUYER_EMAIL_BLOCKED` / `EMAIL_HELD_FOR_REVIEW` | bizalmi szabály: cégen kívüli aláírónak csak ellenőrzött NAV-kapcsolattal és ellenőrzés alatt nem álló fiókból küldünk; tesztcég csak a saját tagjainak |
| 409 | `SIGNATURE_FINAL_NOT_READY` | `…/pdf?version=final` vagy `…/certificate` COMPLETED előtt |
| 403 | `API_KEY_ROLE_FORBIDDEN` | a kulcs létrehozójának szerepköre nem elég (`error.requiredPermission`) |

## Webhookok

A `GET /public/v1/invoices/:id` ismételt lekérdezése helyett regisztráljon
egy HTTPS végpontot, és a Bizonylat aláírt JSON eseményt küld rá (POST), amikor
valami történik. A végpontokat az irányítópulton (API oldal → Webhookok) vagy
az alábbi API-val kezelheti.

### Események

| Esemény | Mikor |
|---|---|
| `invoice.created` | Számlapiszkozat jött létre (irányítópult, `draft: true`, árajánlat átalakítása) |
| `invoice.issued` | Egy számla vagy díjbekérő sorszámot kapott (az előfizetéses számlák is) |
| `invoice.nav_accepted` | A NAV befogadta a beküldést (`navStatus: "DONE"`) |
| `invoice.nav_rejected` | A NAV elutasította a beküldést (`navStatus: "REJECTED"`) |
| `invoice.paid` | A számlát fizetettnek jelölték, vagy teljesen kiegyenlítették |
| `invoice.payment_recorded` | Fizetést rögzítettek; a `data.payment` tartalmazza |
| `invoice.storno_issued` | Sztornó bizonylat készült; a `data` a sztornó, a `data.originalInvoiceId` az eredeti számla |
| `invoice.corrected` | Helyesbítő számla készült; a szerkezet a sztornóéval azonos |
| `proforma.converted` | Díjbekérőből számla / előlegszámla lett; a `data` az új számla, a `data.sourceProformaId` a díjbekérő |
| `proforma.voided` | Egy díjbekérőt érvénytelenítettek (`POST /public/v1/invoices/:id/void`); a `data` a díjbekérő `"status": "VOIDED"` értékkel |
| `quote.sent` | Az árajánlatot elküldték az ügyfélnek |
| `quote.accepted` / `quote.declined` | Az ügyfél elfogadta / elutasította az ajánlatot |
| `subscription.invoice_generated` | Egy előfizetés elkészítette az esedékes számlát (`data.subscriptionId`) |
| `signature.sent` | Egy dokumentumot elektronikus aláírásra küldtek |
| `signature.signer_signed` | Egy aláíró aláírta; a `data.signer` az aláíró |
| `signature.completed` | Mindenki aláírta: elkészült a lezárt PDF (`GET /public/v1/signatures/:id/pdf`) |
| `signature.declined` | Egy aláíró elutasította (a dokumentum lezárult); az indok a `data.signer` adataiban |
| `signature.voided` | A küldő visszavonta a dokumentumot |
| `signature.expired` | A határidő lejárt, mielőtt mindenki aláírta volna |

### Az esemény tartalma

```json
{
  "id": "5f0c…",                 // esemény-azonosító — minden újraküldésnél azonos; erre szűrje a duplikátumokat
  "type": "invoice.issued",
  "createdAt": "2026-09-29T10:15:02.114Z",
  "tenantId": "…",
  "sandbox": true,               // csak tesztcégnél (Tesztcég)
  "data": { "id": "…", "invoiceNumber": "SZ-2026-000042", "status": "ISSUED", "navStatus": "PENDING", "paymentStatus": "UNPAID", "…": "…" }
}
```

A `data` szerkezete megegyezik a `GET /public/v1/invoices/:id` válaszáéval
(árajánlat-eseményeknél a `GET /public/v1/quotes/:id` válaszáéval, tételek
nélkül, aláírás-eseményeknél a `GET /public/v1/signatures/:id` válaszáéval), az esemény feldolgozásakori állapot szerint — ez általában a
változás után néhány másodperccel történik.

### Fejlécek és aláírás

- `Bizonylat-Webhook-Id` — az esemény azonosítója
- `Bizonylat-Webhook-Timestamp` — a kísérlet elküldésének ideje (Unix másodperc)
- `Bizonylat-Webhook-Signature` — `v1=` + a `${timestamp}.${nyersTörzs}`
  hex HMAC-SHA256 értéke a végpont titkos kulcsával (`whsec_…`)
- `Bizonylat-Webhook-Event` — az esemény típusa

Az aláírást a **nyers** kérés-törzsön ellenőrizze, még a feldolgozás előtt;
utasítsa el az 5 percnél régebbi időbélyeget, és konstans idejű
összehasonlítást használjon:

```js
import crypto from 'node:crypto';

function verify(secret, rawBody, headers) {
  const ts = headers['bizonylat-webhook-timestamp'];
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
  const expected = 'v1=' + crypto.createHmac('sha256', secret).update(`${ts}.${rawBody}`).digest('hex');
  const got = headers['bizonylat-webhook-signature'] ?? '';
  return got.length === expected.length && crypto.timingSafeEqual(Buffer.from(got), Buffer.from(expected));
}
```

```php
$ts = $_SERVER['HTTP_BIZONYLAT_WEBHOOK_TIMESTAMP'];
$raw = file_get_contents('php://input');
$expected = 'v1=' . hash_hmac('sha256', $ts . '.' . $raw, $secret);
$ok = abs(time() - (int) $ts) <= 300 && hash_equals($expected, $_SERVER['HTTP_BIZONYLAT_WEBHOOK_SIGNATURE'] ?? '');
```

A titkos kulcsot **egyszer** mutatjuk meg: a végpont létrehozásakor, illetve a
kulcs cseréjekor. Akkor mentse el, később nem olvasható ki.

### Kézbesítés és újrapróbálás

- Válaszoljon bármilyen **2xx** kóddal **10 másodpercen belül**. Minden más —
  más státuszkód, időtúllépés, kapcsolódási hiba, **átirányítás** (ezt soha nem
  követjük) — sikertelen kísérletnek számít.
- A sikertelen kísérletet 1 perc, 5 perc, 30 perc, 2 óra, 6 óra, 12 óra és
  24 óra múlva újra megpróbáljuk; 8 kísérlet után a kézbesítés `FAILED`
  állapotú lesz. Egy esemény többször és más sorrendben is megérkezhet: az
  esemény-azonosítóra szűrjön, és ha a sorrend számít, kérdezze le újra az
  erőforrást.
- Ha egymás után 20 kísérlet sikertelen, és ez több mint 24 órán át tart, a
  végpontot **kikapcsoljuk**, és a fiók tulajdonosa e-mailt kap. Az
  irányítópulton visszakapcsolhatja; a kimaradt kézbesítéseket ott, a
  kézbesítési naplóból egyenként újraküldheti.
- Éles környezetben a végpont csak `https://` címen, nyilvános gépen lehet;
  privát, loopback és link-local címre nem küldünk.
- A kézbesítési naplót 30 napig őrizzük.

### Végpontok kezelése API-val

```bash
curl -X POST "$BASE/public/v1/webhooks" \
  -H "Authorization: Bearer $BIZONYLAT_API_KEY" -H "Content-Type: application/json" \
  -d '{ "url": "https://shop.example.com/wc-api/bizonylat", "events": ["invoice.issued", "invoice.nav_accepted", "invoice.paid"], "description": "WooCommerce" }'
```

Válasz: `201`, a végpont adatai és `"secret": "whsec_…"` (csak itt). Küldjön
`Idempotency-Key` fejlécet (pl. `wc-install-<webhely azonosító>`), hogy az
időtúllépés után a telepítést megismétlő bővítmény egy végpontot regisztráljon,
ne kettőt — az ismételt válasz ugyanazt a `secret` értéket tartalmazza.

| Metódus | Útvonal | |
|---|---|---|
| GET | `/public/v1/webhooks` | végpontok listája |
| POST | `/public/v1/webhooks` | létrehozás (`url`, `events`, opcionálisan `description`, `enabled`) |
| GET | `/public/v1/webhooks/:id` | egy végpont |
| PATCH | `/public/v1/webhooks/:id` | `url`, `events`, `description`, `enabled` módosítása |
| DELETE | `/public/v1/webhooks/:id` | törlés |
| POST | `/public/v1/webhooks/:id/test` | `webhook.test` esemény küldése most |
| POST | `/public/v1/webhooks/:id/rotate-secret` | új titkos kulcs |

**Tesztesemény — `POST /public/v1/webhooks/:id/test`** (törzs nélkül).
`webhook.test` eseményt (`"data": { "message": "Bizonylat webhook test event" }`)
küld a végpontra a szokásos kézbesítési úton — ugyanazokkal a fejlécekkel,
aláírással, 10 másodperces időkorláttal és címszabályokkal, mint egy valódi
eseményt —, **egyszer, a válaszra várva**, és a kézbesítést adja vissza:
`{ "data": { "id", "endpointId", "eventId", "eventType": "webhook.test",
"status": "SUCCEEDED" | "FAILED" | "PENDING", "attempts": 1, "lastStatusCode",
"lastError", "nextAttemptAt", "createdAt", "deliveredAt" } }`. A sikertelen
tesztet nem próbáljuk újra. A végpontnak nem kell bekapcsolva lennie, és
semmilyen eseményre nem kell feliratkoznia. A végpont létrehozása után
közvetlenül használja az URL és az aláírás-ellenőrzés kipróbálására.

**Kulcscsere — `POST /public/v1/webhooks/:id/rotate-secret`** (törzs nélkül).
`200` válasz a végpont adataival és az új `"secret": "whsec_…"` értékkel —
csak ekkor olvasható ki. **A régi kulcs azonnal érvényét veszti:** innentől
minden kézbesítést — a korábbi események újrapróbálásait is — kizárólag az új
kulccsal írunk alá; átfedési időszak nincs. Az új kulcsot azonnal mentse el a
fogadó oldalon: az addig elutasított kézbesítés sikertelen lesz, és a szokásos
ütemezés szerint (1 perc, 5 perc, …) újra megpróbáljuk, így semmi nem vész el.
Minden kulcscsere bekerül a vállalkozás naplójába. Ide ne küldjön
`Idempotency-Key` fejlécet: minden hívás új kulcscsere.

Vállalkozásonként legfeljebb 50 végpont. Hibakódok: `WEBHOOK_URL_INVALID`,
`WEBHOOK_EVENTS_INVALID` (400), `WEBHOOK_ENDPOINT_NOT_FOUND` (404, a
`/test` és a `/rotate-secret` hívásnál is, ha a végpont ismeretlen vagy
másik vállalkozásé), `WEBHOOK_ENDPOINT_LIMIT` (409). A kézbesítési napló és az
újraküldés az irányítópulton érhető el.

## Hívásnapló — GET /public/v1/logs

A kulcsaival a `/public/v1/*` végpontokra indított minden hívást **30 napig**
naplózzuk: időpont, metódus, útvonal-minta és útvonal, státuszkód, hibakód,
időtartam és a kulcs előtagja. Ugyanez a napló az irányítópulton is megvan
(API oldal → API napló), 24 órás összesítővel. Ez a leggyorsabb módja annak,
hogy kiderüljön, miért hiúsult meg egy hívás — különösen tesztcégben
végzett tesztelés közben.

- Csak **érvényes kulccsal** indított hívást naplózunk: hiányzó, ismeretlen
  vagy visszavont kulcsnál nincs vállalkozás, amelynek megmutathatnánk. Ha a
  kulcsot felismertük, az elutasítás is bekerül (például `400` validációs
  hiba, `403` felfüggesztés).
- **Csak metaadat.** A kérés és a válasz törzsét, a fejléceket és a
  lekérdezési paraméterek értékét soha nem tároljuk; a hívó IP-címét csak
  egyirányú hash-ként őrizzük.
- A `GET /public/v1/logs` hívásokat magukat nem naplózzuk.

```bash
curl "$BASE/public/v1/logs?status=4xx&route=invoices&limit=20" \
  -H "Authorization: Bearer $BIZONYLAT_API_KEY"
```

| Paraméter | |
|---|---|
| `status` | `2xx`, `4xx` vagy `5xx` |
| `apiKeyId` | csak az ezzel a kulccsal indított hívások (azonosító az irányítópultról) |
| `route` | az útvonal-minta vagy az útvonal része, pl. `invoices` |
| `from`, `to` | ISO dátum-idő vagy dátum (dátumként megadott `to` a teljes UTC-napot tartalmazza) |
| `page`, `limit` | lapozás; `limit` ≤ 100, alapértelmezés 50 |

A legújabb elöl. Válasz `200`:

```json
{
  "data": [
    {
      "id": "…",
      "createdAt": "2026-09-29T10:15:02.114Z",
      "method": "POST",
      "route": "/public/v1/invoices",
      "path": "/public/v1/invoices",
      "statusCode": 409,
      "errorCode": "NAV_CREDENTIALS_NOT_VERIFIED",
      "errorDetail": null,
      "durationMs": 84,
      "idempotencyKeyPresent": true,
      "requestId": "req-3f",
      "apiKeyId": "…",
      "keyPrefix": "bz_live_1a2b3c4d",
      "userAgent": "WooCommerce/9.3"
    }
  ],
  "pagination": { "page": 1, "limit": 20, "total": 1, "totalPages": 1 }
}
```

A `route` a minta (`/public/v1/invoices/:id`), a `path` a tényleges útvonal
a lekérdezési rész nélkül; a `route` értéke `null`, ha az útvonal egyetlen
végpontnak sem felel meg. Az `errorCode` egy 4xx/5xx válasz `error.code`
mezője (lásd: Hibák), kérési séma hibájánál `FST_ERR_VALIDATION`, egyébként
`null`. Az `errorDetail` csak `FST_ERR_VALIDATION` esetén van kitöltve:
egy mondat arról, melyik mező hibás és mit vár, pl. *A „currency” mező értéke
nem megengedett. Lehetséges értékek: HUF, EUR, …* A sémahibából készül, az Ön
által küldött értéket soha nem tartalmazza.

## Magyar mezőnevek

Minden kérésmező és lekérdezési paraméter **magyar néven is küldhető**: a
`client.address` helyett `ugyfel.cim`, a `lines[].unitPrice` helyett
`tetelek[].egysegar`, a `?page=2` helyett `?oldal=2`. A gyakori értékek is
írhatók magyarul: `"fizetesiMod": "ATUTALAS"`, `"szamlaTipus": "DIJBEKERO"`.
Az angol nevek változatlanul, ugyanúgy működnek — a kettő egy kérésen belül
keverhető is.

```json
{
  "ugyfel": {
    "nev": "Kiss Anna",
    "email": "anna@example.com",
    "cim": "Fő utca 1.",
    "varos": "Budapest",
    "iranyitoszam": "1011",
    "orszag": "HU"
  },
  "tetelek": [
    { "nev": "Hidratáló arckrém", "mennyiseg": 1, "egysegar": 4990, "afaKulcs": 27 }
  ],
  "fizetesiMod": "ATUTALAS",
  "emailKuldes": true
}
```

- **Ékezet, kis- és nagybetű nem számít:** `cim`, `cím` és `Cím`, illetve
  `ATUTALAS`, `átutalás` és `Átutalás` ugyanaz. A táblázat az ékezet
  nélküli, camelCase alakot javasolja.
- **A válasz mindig angol** (`data.invoiceNumber`, `data.grossTotal` …): a
  válaszmezők a géppel feldolgozott, stabil szerződés részei, ezért nem
  fordítjuk őket. Magyar hibaüzenetet a `?lang=hu` kér (lásd *Magyar
  hibaüzenetek*).
- **Egy mezőt egyszer küldjön.** Ha ugyanazt a mezőt angol és magyar néven
  (vagy két magyar írásmóddal) is elküldi, például `cim` és `address`, a
  kérés **400**-at kap `DUPLICATE_FIELD_ALIAS` kóddal; az `error.field` az
  angol mezőnév, az `error.sent` a küldött nevek.
- **A hibaüzenet a küldött nevet használja:** magyar mezőnevekkel küldött
  kérésre a validációs hiba is azt nevezi meg, pl.
  `body/tetelek/0 must have required property 'mennyiseg' (quantity)`,
  `?lang=hu` esetén `Hibás kérés: a „tetelek[0].mennyiseg” mező kötelező.`
- **Idempotency-Key:** a magyar és az angol nevekkel küldött azonos kérés
  ugyanannak a kérésnek számít (ismétléskor az első válasz jön vissza).
- Egy név csak ott érvényes, ahol az angol megfelelője mező: a `nyelv` a
  számlán `emailLocale`, a küldésnél `locale`; a `fizetesiMod` a számlán
  `paymentMethod`, a fizetés rögzítésénél `method`. A `to` háromféle: a
  küldésnél `cimzett`, az átalakításnál `cel`, az API naplóban `ig`.
- Magyar érték csak akkor alakul át, ha az adott mezőben az angol megfelelője
  megengedett; ismeretlen értékre ugyanúgy 400-as validációs hiba jön, mint
  eddig.

### Mezőnevek

**Ügyfél**

| Angol mező | Magyar név | Szintén elfogadott | Hol |
|---|---|---|---|
| `client` | `ugyfel` | `vevo` | számla, árajánlat, előfizetés |
| `clientId` | `ugyfelId` | `vevoId`, `ugyfelAzonosito` | számla, árajánlat; listaszűrő |
| `name` | `nev` | `megnevezes` | ügyfél, tétel, termék |
| `taxNumber` | `adoszam` | — | ügyfél; ügyféllista-szűrő |
| `euVatId` | `kozossegiAdoszam` | `euAdoszam` | ügyfél |
| `thirdStateTaxId` | `harmadikOrszagbeliAdoazonosito` | `kulfoldiAdoazonosito` | ügyfél (EU-n kívüli vevő) |
| `groupMemberTaxNumber` | `csoporttagAdoszam` | — | ügyfél (áfacsoport tagja) |
| `registrationNumber` | `cegjegyzekszam` | `nyilvantartasiSzam` | ügyfél |
| `email` | `emailCim` | — | ügyfél; ügyféllista-szűrő |
| `phone` | `telefon` | `telefonszam` | ügyfél |
| `address` | `cim` | — | ügyfél (utca, házszám) |
| `city` | `varos` | `telepules` | ügyfél |
| `postalCode` | `iranyitoszam` | `irsz` | ügyfél |
| `country` | `orszag` | `orszagkod` | ügyfél (ISO kód, pl. HU) |
| `emailLocale` | `nyelv` | `emailNyelv` | ügyfél, számla, kiállítás, átalakítás |
| `defaultPaymentTermsDays` | `fizetesiHataridoNapok` | `alapFizetesiHatarido` | ügyfél |
| `defaultPaymentMethod` | `alapFizetesiMod` | `alapertelmezettFizetesiMod` | ügyfél |
| `currency` | `penznem` | `deviza` | ügyfél, számla, árajánlat, előfizetés |
| `notes` | `megjegyzes` | — | ügyfél, számla, árajánlat, előfizetés |

**Tételek**

| Angol mező | Magyar név | Szintén elfogadott | Hol |
|---|---|---|---|
| `lines` | `tetelek` | — | számla, árajánlat, előfizetés, helyesbítés |
| `sku` | `cikkszam` | — | tétel, termék |
| `productId` | `termekId` | `termekAzonosito` | tétel |
| `description` | `leiras` | — | tétel, termék, webhook |
| `quantity` | `mennyiseg` | — | tétel |
| `unit` | `egyseg` | `mennyisegiEgyseg` | tétel, termék (pl. db, óra) |
| `unitPrice` | `egysegar` | `nettoEgysegar` | tétel, termék |
| `vatRate` | `afaKulcs` | `afa` | tétel, termék (százalék, pl. 27) |
| `vatCategory` | `afaKategoria` | `afaTipus` | tétel, termék |
| `netAmount` | `nettoOsszeg` | `netto` | helyesbítő tétel |
| `vatAmount` | `afaOsszeg` | — | helyesbítő tétel |
| `grossAmount` | `bruttoOsszeg` | `brutto` | helyesbítő tétel |
| `productCodes` | `termekkodok` | — | tétel, termék |
| `dataErasureCodes` | `adattorloKodok` | `adattorloKod` | tétel |
| `category` | `termekkodFajta` | `kodFajta` | termékkód (productCodes) |
| `value` | `termekkodErtek` | `kodErtek` | termékkód (productCodes) |
| `lineNature` | `tetelJelleg` | `jelleg` | tétel, termék |
| `intermediatedService` | `kozvetitettSzolgaltatas` | — | tétel, termék |

**Számla és számlaműveletek**

| Angol mező | Magyar név | Szintén elfogadott | Hol |
|---|---|---|---|
| `invoiceType` | `szamlaTipus` | `bizonylatTipus`, `tipus` | számla; számlalista-szűrő |
| `issueDate` | `kiallitasDatuma` | `kelte`, `szamlaKelte`, `kelt` | számla, árajánlat, helyesbítés |
| `performanceDate` | `teljesitesDatuma` | `teljesites` | számla, helyesbítés, díjbekérő átalakítása (az előleg beérkezése); gyűjtőszámla tétele |
| `advanceDeductions` | `eloleglevonasok` | `elolegBeszamitasok`, `elolegBeszamitas` | végszámla (előlegszámlák beszámítása: invoiceId, amount) |
| `invoiceCategory` | `szamlaKategoria` | — | számla (NORMAL vagy AGGREGATE = gyűjtőszámla) |
| `dueDate` | `fizetesiHatarido` | `esedekesseg` | számla, helyesbítés |
| `paymentMethod` | `fizetesiMod` | — | számla, előfizetés, fizetési állapot, árajánlat átalakítása |
| `exchangeRate` | `arfolyam` | — | számla, átalakítás, sztornó, helyesbítés, előfizetés |
| `exchangeRateDate` | `arfolyamDatuma` | `arfolyamDatum` | sztornó, helyesbítés |
| `sendEmail` | `emailKuldes` | `kuldesEmailben` | számla, kiállítás, átalakítás, sztornó, helyesbítés |
| `pricesIncludeVat` | `bruttoArak` | `arakAfaval` | számla, árajánlat, előfizetés |
| `invoicePrefix` | `szamlatomb` | `szamlatombElotag` | számla |
| `paymentStatus` | `fizetesiAllapot` | `fizetesiStatusz` | számla, fizetési állapot; számlalista-szűrő |
| `paidAmount` | `fizetettOsszeg` | — | számla, fizetési állapot |
| `paidAt` | `fizetesDatuma` | `fizetesIdopontja` | számla, fizetési állapot, fizetés |
| `paymentReference` | `fizetesiHivatkozas` | `tranzakcioAzonosito` | számla |
| `draft` | `piszkozat` | — | számla |
| `to` | `cel` | `celBizonylat` | díjbekérő és árajánlat átalakítása (mivé) |
| `markSourcePaid` | `dijbekeroFizetve` | `forrasFizetve` | díjbekérő átalakítása |
| `to` | `cimzett` | — | számla és árajánlat küldése (e-mail-cím) |
| `locale` | `nyelv` | `emailNyelv` | számla küldése |
| `reason` | `indok` | `indoklas` | sztornó, helyesbítés |
| `dataOnly` | `csakAdattartalom` | `adattartalomHelyesbites` | helyesbítés |
| `conventionalInfo` | `egyezmenyesAdatok` | — | számla |
| `deliveryPeriodStart` | `elszamolasiIdoszakKezdete` | `idoszakKezdete` | számla (elszámolási időszak első napja) |
| `deliveryPeriodEnd` | `elszamolasiIdoszakVege` | `idoszakVege` | számla (elszámolási időszak utolsó napja) |
| `periodicalSettlement` | `idoszakosElszamolas` | — | számla, előfizetés |
| `bankAccountId` | `bankszamlaId` | `bankszamlaAzonosito` | számla, díjbekérő (a cég egyik bankszámlája) |
| `discountType` | `kedvezmenyTipus` | `kedvezmenyFajta` | tétel; számla, árajánlat, előfizetés (a végösszegből) |
| `discountValue` | `kedvezmeny` | `kedvezmenyMerteke` | tétel; számla, árajánlat, előfizetés (százalék vagy összeg) |
| `discountAmount` | `kedvezmenyOsszege` | — | helyesbítő tétel (ahogy a GET …/lines adja) |
| `lineKind` | `tetelFajta` | — | helyesbítő tétel (INVOICE_DISCOUNT = a végösszegből adott kedvezmény sora) |
| `customFields` | `egyediMezok` | — | számla, ügyfél ({ mezőazonosító: érték }) |
| `fileName` | `fajlnev` | — | melléklet feltöltése |
| `contentType` | `fajltipus` | `tartalomTipus` | melléklet feltöltése |
| `data` | `tartalom` | `fajlTartalom` | melléklet feltöltése (Base64) |
| `docType` | `dokumentumTipus` | — | szállítólevél, teljesítésigazolás (DELIVERY_NOTE / COMPLETION_CERTIFICATE) |
| `fulfilmentDate` | `szallitasNapja` | `teljesitesNapja` | szállítólevél, teljesítésigazolás |
| `periodStart` | `teljesitesiIdoszakKezdete` | — | teljesítésigazolás (időszak első napja) |
| `periodEnd` | `teljesitesiIdoszakVege` | — | teljesítésigazolás (időszak utolsó napja) |
| `deliveryAddress` | `szallitasiCim` | `teljesitesHelye` | szállítólevél, teljesítésigazolás |
| `projectReference` | `projektszam` | `munkaszam` | szállítólevél, teljesítésigazolás |
| `orderReference` | `megrendelesszam` | `szerzodesszam` | szállítólevél, teljesítésigazolás |
| `showPrices` | `arakMegjelenitese` | — | szállítólevél, teljesítésigazolás |
| `issue` | `kiallitas` | `kiallitva` | szállítólevél létrehozása (azonnal kiállítva) |
| `documentIds` | `dokumentumIdk` | `dokumentumok` | számla készítése szállítólevélből |
| `supplierName` | `szallitoNeve` | `szallito` | kiadás |
| `supplierTaxNumber` | `szallitoAdoszama` | `szallitoAdoszam` | kiadás |
| `invoiceNumber` | `szamlaszam` | — | kiadás |
| `vatLines` | `afaSorok` | — | kiadás (ÁFA-kulcsonkénti összegek) |
| `categoryId` | `kategoriaAzonosito` | — | kiadás |
| `categoryName` | `kategoriaNeve` | `kategoria` | kiadás (új kategória neve) |
| `paid` | `fizetve` | — | kiadás |
| `paidDate` | `fizetesNapja` | — | kiadás |

**Fizetés rögzítése**

| Angol mező | Magyar név | Szintén elfogadott | Hol |
|---|---|---|---|
| `amount` | `osszeg` | — | fizetés rögzítése; előleg beszámítása (levonandó bruttó összeg) |
| `method` | `fizetesiMod` | — | fizetés rögzítése |
| `reference` | `hivatkozas` | `kozlemeny` | fizetés rögzítése, fizetési állapot |
| `note` | `megjegyzes` | — | fizetés rögzítése |
| `invoiceId` | `szamlaId` | `szamlaAzonosito` | részletfizetés; előleg beszámítása (az előlegszámla); listaszűrő |
| `count` | `reszletekSzama` | — | részletfizetés (egyenlő részletek) |
| `firstDueDate` | `elsoHatarido` | `elsoFizetesiHatarido` | részletfizetés |
| `intervalMonths` | `gyakorisagHonap` | `honapokKozott` | részletfizetés |
| `instalments` | `reszletek` | — | részletfizetés (egyedi részletek) |

**Termékek**

| Angol mező | Magyar név | Szintén elfogadott | Hol |
|---|---|---|---|
| `products` | `termekek` | — | terméklista szinkronizálása |
| `deactivateMissing` | `hianyzokInaktivalasa` | `hianyzoInaktivalas` | terméklista szinkronizálása |
| `includeWithoutSku` | `cikkszamNelkulIs` | `cikkszamNelkuliekIs` | terméklista (cikkszám nélküli termékek is) |
| `trackStock` | `keszletKovetes` | `keszletnyilvantartas` | készlet |
| `lowStockThreshold` | `minimumKeszlet` | `keszletMinimum` | készlet |
| `initialQuantity` | `nyitokeszlet` | — | készlet bekapcsolása |
| `change` | `valtozas` | `keszletValtozas` | készletkorrekció |
| `newQuantity` | `ujKeszlet` | `leltarKeszlet` | készletkorrekció (leltár) |

**Árajánlatok**

| Angol mező | Magyar név | Szintén elfogadott | Hol |
|---|---|---|---|
| `validUntil` | `ervenyesseg` | `ervenyesIg` | árajánlat |
| `internalNotes` | `belsoMegjegyzes` | — | árajánlat |
| `subject` | `targy` | — | árajánlat küldése |
| `body` | `szoveg` | `uzenet` | árajánlat küldése |
| `paymentTermsDays` | `fizetesiHataridoNapok` | — | árajánlat átalakítása előfizetéssé |

**Előfizetések**

| Angol mező | Magyar név | Szintén elfogadott | Hol |
|---|---|---|---|
| `billingCycle` | `szamlazasiCiklus` | `gyakorisag` | előfizetés, árajánlat átalakítása |
| `startDate` | `kezdoDatum` | `kezdes` | előfizetés |
| `nextInvoiceDate` | `kovetkezoSzamlaDatuma` | `kovetkezoSzamlazas` | előfizetés |
| `endDate` | `zaroDatum` | `befejezes` | előfizetés |
| `sendInvoice` | `szamlaKuldes` | — | előfizetés |
| `status` | `allapot` | `statusz` | előfizetés; listaszűrő |
| `invoicePeriod` | `szamlaIdoszak` | `elszamolasiIdoszak` | előfizetés (a generált számlák elszámolási időszaka) |

**Webhookok**

| Angol mező | Magyar név | Szintén elfogadott | Hol |
|---|---|---|---|
| `url` | `vegpont` | `webcim` | webhook |
| `events` | `esemenyek` | — | webhook |
| `enabled` | `aktiv` | `engedelyezve`, `bekapcsolva` | webhook |

**Cégadatok**

| Angol mező | Magyar név | Szintén elfogadott | Hol |
|---|---|---|---|
| `legalForm` | `cegforma` | `tarsasagiForma` | cégadatok (PATCH /company) |
| `bankAccount` | `bankszamlaszam` | `bankszamla` | cégadatok (PATCH /company) |
| `quotePrefix` | `arajanlatElotag` | `arajanlatTomb` | cégadatok (PATCH /company) |
| `documentLanguage` | `bizonylatNyelv` | `dokumentumNyelv` | cégadatok (PATCH /company) |
| `documentFooterText` | `labjegyzet` | `lablecSzoveg` | cégadatok (PATCH /company) |
| `defaultInvoiceNotes` | `alapSzamlaMegjegyzes` | `alapertelmezettSzamlaMegjegyzes` | cégadatok (PATCH /company) |
| `defaultQuoteNotes` | `alapArajanlatMegjegyzes` | `alapertelmezettArajanlatMegjegyzes` | cégadatok (PATCH /company) |

**Aláírások**

| Angol mező | Magyar név | Szintén elfogadott | Hol |
|---|---|---|---|
| `title` | `cim` | `dokumentumCim` | aláírási dokumentum |
| `message` | `uzenet` | — | aláírási dokumentum (az e-mail üzenete) |
| `signingOrder` | `alairasiSorrend` | `sorrend` | aláírási dokumentum |
| `expiresAt` | `lejarat` | `hatarido` | aláírási dokumentum |
| `reminderIntervalDays` | `emlekeztetoNapok` | — | aláírási dokumentum (emlékeztető ennyi naponta) |
| `remindBeforeExpiry` | `emlekeztetoLejaratElott` | — | aláírási dokumentum |
| `signers` | `alairok` | — | aláírási dokumentum |
| `fields` | `mezok` | — | aláírási dokumentum |
| `fieldUnit` | `mezoEgyseg` | — | aláírási dokumentum (tört vagy pt) |
| `id` | `azonosito` | — | aláírók (meglévő aláíró, PATCH) |
| `signOrder` | `sorszam` | — | aláírási dokumentum, aláírók |
| `slotKey` | `sablonHely` | — | aláírók (mentett sablon helye) |
| `role` | `szerep` | — | aláírók (beépített sablon szerepe) |
| `signerIndex` | `alairoSorszam` | `alairoIndex` | aláírási dokumentum, mezők |
| `signerEmail` | `alairoEmail` | `alairoEmailCim` | aláírási dokumentum, mezők |
| `signerId` | `alairoAzonosito` | — | mezők; emlékeztető egy aláírónak |
| `type` | `tipus` | `mezoTipus` | aláírási dokumentum, mezők |
| `x` | `balrol` | `vizszintes` | mezők (távolság a lap bal szélétől) |
| `y` | `felulrol` | `fuggoleges` | mezők (távolság a lap tetejétől) |
| `width` | `szelesseg` | — | aláírási dokumentum, mezők |
| `height` | `magassag` | — | aláírási dokumentum, mezők |
| `required` | `kotelezo` | — | aláírási dokumentum, mezők |
| `label` | `felirat` | `cimke` | aláírási dokumentum, mezők |
| `prefill` | `elotoltes` | `alapertek` | aláírási dokumentum, mezők |
| `options` | `beallitasok` | `opciok` | aláírási dokumentum, mezők |
| `format` | `formatum` | — | mezők (dátum formátuma) |
| `addressPart` | `cimResz` | — | mezők (a cím melyik része) |
| `namePart` | `nevResz` | — | mezők (a név melyik része) |
| `file` | `fajl` | — | aláírási dokumentum létrehozása (JSON-ban küldött fájl) |
| `filename` | `fajlnev` | — | aláírási dokumentum létrehozása (fájl) |
| `contentBase64` | `tartalomBase64` | — | aláírási dokumentum létrehozása (fájl) |
| `templateId` | `sablonAzonosito` | — | aláírási dokumentum létrehozása (mentett sablonból) |
| `builtinTemplate` | `beepitettSablon` | — | aláírási dokumentum létrehozása (beépített sablonból) |
| `inputs` | `adatok` | — | aláírási dokumentum létrehozása (beépített sablon adatai) |
| `send` | `kuldes` | `kuldesAzonnal` | aláírási dokumentum létrehozása (azonnali küldés) |
| `version` | `valtozat` | `verzio` | aláírt PDF letöltése (auto / eredeti / végleges) |

**Listák és szűrők (query string)**

| Angol mező | Magyar név | Szintén elfogadott | Hol |
|---|---|---|---|
| `page` | `oldal` | — | listák |
| `limit` | `darab` | `oldalMeret` | listák |
| `search` | `kereses` | `keres` | számla-, ügyfél- és terméklista |
| `navStatus` | `navAllapot` | `navStatusz` | számlalista |
| `issueDateFrom` | `kiallitasDatumaTol` | `keltTol` | számlalista |
| `issueDateTo` | `kiallitasDatumaIg` | `keltIg` | számlalista |
| `updatedSince` | `modositvaOta` | `valtozottOta` | számlalista (ennél az időpontnál később módosult) |
| `apiKeyId` | `apiKulcsId` | `apiKulcsAzonosito` | API napló |
| `scope` | `hatokor` | `mezoHelye` | egyedi mezők listája (INVOICE vagy CLIENT) |
| `route` | `utvonal` | — | API napló |
| `from` | `tol` | `datumTol` | API napló |
| `to` | `ig` | `datumIg` | API napló |
| `uninvoiced` | `szamlazatlan` | — | szállítólevél-lista |
| `tracked` | `kovetett` | — | készletlista |
| `low` | `alacsony` | `alacsonyKeszlet` | készletlista |
| `from` | `tol` | `datumTol` | kiadások listája |
| `to` | `ig` | `datumIg` | kiadások listája |
| `source` | `forras` | — | kiadások listája (NAV / kézi) |
| `accounting` | `konyveles` | — | kiadások listája (könyvelésben / kihagyva) |
| `q` | `kereses` | `keres` | aláírások listája (cím, fájlnév, aláíró) |

### Értékek

**Fizetési mód** (`paymentMethod`, `method`, `defaultPaymentMethod`)

| Angol érték | Magyar érték | Szintén elfogadott |
|---|---|---|
| `BANK_TRANSFER` | `ATUTALAS` | `BANKI_ATUTALAS`, `UTALAS` |
| `CASH` | `KESZPENZ` | — |
| `CARD` | `BANKKARTYA` | `KARTYA` |
| `VOUCHER` | `UTALVANY` | — |
| `COD` | `UTANVET` | — |
| `OTHER` | `EGYEB` | — |

**Kedvezmény típusa** (`discountType`)

| Angol érték | Magyar érték | Szintén elfogadott |
|---|---|---|
| `PERCENT` | `SZAZALEK` | — |
| `AMOUNT` | `OSSZEG` | — |

**Bizonylattípus (számlatípus, átalakítás célja)** (`invoiceType`, `to`)

| Angol érték | Magyar érték | Szintén elfogadott |
|---|---|---|
| `STANDARD` | `SZAMLA` | — |
| `INVOICE` | `SZAMLA` | — |
| `PROFORMA` | `DIJBEKERO` | — |
| `PREPAYMENT` | `ELOLEGSZAMLA` | `ELOLEG` |
| `STORNO` | `SZTORNO` | `SZTORNOSZAMLA` |
| `CORRECTION` | `HELYESBITO` | `HELYESBITES`, `HELYESBITO_SZAMLA` |
| `SUBSCRIPTION` | `ELOFIZETES` | — |

**Szállítólevél / teljesítésigazolás típusa** (`docType`)

| Angol érték | Magyar érték | Szintén elfogadott |
|---|---|---|
| `DELIVERY_NOTE` | `SZALLITOLEVEL` | — |
| `COMPLETION_CERTIFICATE` | `TELJESITESIGAZOLAS` | — |

**Számlakategória** (`invoiceCategory`)

| Angol érték | Magyar érték | Szintén elfogadott |
|---|---|---|
| `NORMAL` | `NORMAL_SZAMLA` | — |
| `AGGREGATE` | `GYUJTOSZAMLA` | `GYUJTO` |

**ÁFA-kategória** (`vatCategory`)

| Angol érték | Magyar érték | Szintén elfogadott |
|---|---|---|
| `STANDARD` | `ALTALANOS` | — |
| `REDUCED` | `KEDVEZMENYES_18` | — |
| `REDUCED_MORE` | `KEDVEZMENYES_5` | — |
| `ZERO` | `NULLA_KULCS` | `NULLAS` |
| `EU_REVERSE_CHARGE` | `FORDITOTT_ADOZAS` | `EUFAD37` |
| `EU_GOODS_SUPPLY` | `KOZOSSEGEN_BELULI` | `KBAET` |
| `EXPORT_GOODS` | `TERMEKEXPORT` | `EAM` |
| `THIRD_COUNTRY_SUPPLY` | `HARMADIK_ORSZAG` | `HO` |
| `OUT_OF_SCOPE` | `TARGYI_HATALYON_KIVULI` | `ATK` |
| `MARGIN_TRAVEL_AGENCY` | `KULONBOZET_UTAZASI_IRODAK` | — |
| `MARGIN_SECOND_HAND` | `KULONBOZET_HASZNALT_CIKKEK` | — |
| `MARGIN_ARTWORK` | `KULONBOZET_MUALKOTASOK` | — |
| `MARGIN_ANTIQUES` | `KULONBOZET_GYUJTEMENYDARABOK_REGISEGEK` | — |
| `DOMESTIC_REVERSE_CHARGE` | `BELFOLDI_FORDITOTT_ADOZAS` | — |

**Elszámolási időszak az előfizetés számláin** (`invoicePeriod`)

| Angol érték | Magyar érték | Szintén elfogadott |
|---|---|---|
| `NONE` | `NINCS` | — |
| `CURRENT` | `AKTUALIS` | `FOLYO` |
| `PREVIOUS` | `ELOZO` | — |

**Fizetési állapot** (`paymentStatus`)

| Angol érték | Magyar érték | Szintén elfogadott |
|---|---|---|
| `UNPAID` | `FIZETETLEN` | `NEM_FIZETETT` |
| `PARTIAL` | `RESZBEN_FIZETETT` | `RESZBEN_FIZETVE` |
| `PAID` | `FIZETVE` | `FIZETETT`, `KIFIZETVE` |
| `OVERDUE` | `LEJART` | `KESEDELMES` |
| `REFUNDED` | `VISSZATERITVE` | `VISSZATERITETT` |

**Állapot (számla, árajánlat, előfizetés)** (`status`)

| Angol érték | Magyar érték | Szintén elfogadott |
|---|---|---|
| `DRAFT` | `PISZKOZAT` | — |
| `ISSUED` | `KIALLITOTT` | `KIALLITVA` |
| `SENT` | `ELKULDVE` | `ELKULDOTT` |
| `VIEWED` | `MEGTEKINTVE` | `MEGTEKINTETT` |
| `ACCEPTED` | `ELFOGADVA` | `ELFOGADOTT` |
| `REJECTED` | `ELUTASITVA` | `ELUTASITOTT` |
| `EXPIRED` | `LEJART` | — |
| `CONVERTED` | `ATALAKITVA` | `ATALAKITOTT` |
| `ACTIVE` | `AKTIV` | — |
| `PAUSED` | `SZUNETEL` | `SZUNETELTETVE` |
| `CANCELLED` | `LEMONDVA` | `MEGSZUNTETVE` |

**Számlázási ciklus** (`billingCycle`)

| Angol érték | Magyar érték | Szintén elfogadott |
|---|---|---|
| `MONTHLY` | `HAVI` | — |
| `ANNUAL` | `EVES` | — |

**NAV-állapot** (`navStatus`)

| Angol érték | Magyar érték | Szintén elfogadott |
|---|---|---|
| `PENDING` | `FUGGOBEN` | `VARAKOZIK` |
| `SUBMITTED` | `BEKULDVE` | — |
| `RECEIVED` | `BEFOGADVA` | — |
| `PROCESSING` | `FELDOLGOZAS_ALATT` | — |
| `DONE` | `FELDOLGOZVA` | `KESZ` |
| `ABORTED` | `MEGSZAKITVA` | — |
| `REJECTED` | `ELUTASITVA` | — |

## Választható értékek (referenciaadatok)

Az API által ellenőrzött összes értéklista, ugyanazzal az API-kulccsal
lekérdezhető. Minden lista abból a konstansból készül, amelyet maga az
ellenőrzés is használ, így a listában szereplő érték mindig elfogadott, a
listán kívüli pedig elutasított. A megnevezések mindig magyarul és angolul is
szerepelnek (`"label": { "hu": …, "en": … }`), az `Accept-Language`-től
függetlenül.

| Végpont | Mező | Elemek |
|---|---|---|
| `GET /public/v1/reference/currencies` | `currency` | `code`, `name.hu/en`, `decimals` (minden pénznemnél 2), `exchangeRateRequired`, `mnbRateAutoFilled` (mindkettő a **saját** cége árfolyam-beállítása szerint), `navRateLimits` (`{ min, max }` forintban, vagy `null`, ha nem ismert) |
| `GET /public/v1/reference/countries` | `client.country` | `code` (ISO 3166-1 alpha-2), `name.hu/en`, `isEu`, `euVatPrefix` (pl. Görögországnál `EL`, EU-n kívül `null`) |
| `GET /public/v1/reference/vat-categories` | `lines[].vatCategory` | `code`, `huAliases`, `label` (az irányítópult megnevezése), `vatRate` (százalék), `vatRateImpliedWhenOmitted`, `nav` (`{ type, value }`: NAV ÁFA-kulcs, mentességi vagy hatályon kívüli eset), `issuable`, `requiredBuyerFields` (vevőadat, amely nélkül az API nem állít ki — jelenleg egy sincs) |
| `GET /public/v1/reference/payment-methods` | `paymentMethod` | `code`, `huAliases`, `label` (ahogy a számlán szerepel), `navCode` |
| `GET /public/v1/reference/languages` | `emailLocale` | `code`, `name.hu/en/native`, `document` (PDF és nyilvános oldal), `email` (az e-mail ezen a nyelven íródik; különben angolul) |
| `GET /public/v1/reference/units` | `lines[].unit` | `unit`, `navCode` — azok a szavak, amelyekhez van NAV-kód; bármely más mennyiségi egység is elfogadott, `OWN`-ként jelentjük |
| `GET /public/v1/reference/invoice-types` | `invoiceType` | `code`, `huAliases`, `label`, `reportedToNav` |
| `GET /public/v1/reference/billing-cycles` | `billingCycle` | `code`, `huAliases`, `label` |

A `GET /public/v1/reference` mindet egy válaszban adja vissza:
`{ "data": { "currencies": […], "countries": […], "vatCategories": […], "paymentMethods": […], "languages": […], "units": […], "invoiceTypes": […], "billingCycles": […] } }`.
Egyetlen lista válasza: `{ "data": […] }`.

A válaszok `Cache-Control: private` fejlécet kapnak — `max-age=300` a
`currencies` és az összesítő hívás esetén (ezek a cég árfolyam-beállítását
követik), a többinél `max-age=3600`. Példa egy elemre:

```json
{
  "code": "EU_REVERSE_CHARGE",
  "huAliases": ["FORDITOTT_ADOZAS", "EUFAD37"],
  "label": { "hu": "EU szolgáltatás – fordított adózás", "en": "EU service – reverse charge" },
  "vatRate": 0,
  "vatRateImpliedWhenOmitted": true,
  "nav": { "type": "vatOutOfScope", "value": "EUFAD37" },
  "issuable": true,
  "requiredBuyerFields": []
}
```

## Bizonylat összekapcsolása — partnerszoftvereknek (OAuth 2.0)

Olyan szoftvereknek, amelyek sok vállalkozást szolgálnak ki (szerviz- és
munkalapkezelő, webshopmotor, foglalási rendszer…). Ahelyett, hogy minden
ügyfele API-kulcsot hozna létre és bemásolná az Önök beállításaiba, egy
**„Bizonylat összekapcsolása”** gombot jelenítenek meg. Az ügyfél belép a
Bizonylatba, kiválasztja a cégét, jóváhagyja, és visszakerül Önökhöz; az Önök
szervere hozzáférési tokent kap az adott céghez. Szabványos OAuth 2.0
authorization code folyamat (RFC 6749) PKCE-vel (RFC 7636).

- A hozzáférési token **egy szokásos API-kulcs** a cégnél (`bz_live_…`): a
  dokumentáció minden része változatlanul érvényes rá — végpontok,
  csomagkeretek, kérésnapló, webhookok.
- Egy token = egy cég. A több céggel rendelkező ügyfél mindegyiket külön
  kapcsolja össze.
- A cég az **API kulcsok** oldalon az Önök alkalmazásának kulcsaként látja, és
  ott bármikor visszavonhatja. Egyébként nem jár le; refresh token nincs.
- Újbóli összekapcsolás (ugyanaz a cég, ugyanaz az alkalmazás) új tokent ad,
  és visszavonja az előzőt.
- Csak a cég **tulajdonosa vagy adminisztrátora** hagyhatja jóvá.

### 1. Az alkalmazás regisztrálása

Hozzák létre maguk: a Bizonylatban **API → Saját alkalmazások → Új
alkalmazás** (a cég tulajdonosaként vagy adminisztrátoraként). Adják meg az
alkalmazás nevét (ezt látja a felhasználó a jóváhagyó oldalon; nem
tartalmazhatja a „Bizonylat” szót), a weboldalát, egy kapcsolattartó
e-mail-címet és a pontos **visszairányítási URI(ka)t** (legfeljebb 10;
`https://`, fejlesztéshez `http://localhost`; `#fragment` nélkül). Ezután
kapnak egy `client_id`-t (`bzc_…`) és egy `client_secret`-et (`bzs_…`). A
titkos kulcs csak egyszer látható: kizárólag a szerveren tárolják — soha ne
böngészőben, mobilappban vagy kódtárban. Ugyanott szerkeszthetik,
kikapcsolhatják, vagy új titkos kulcsot kérhetnek.

- Az új alkalmazás **ellenőrizetlen**: csak azokkal a cégekkel kapcsolható
  össze, amelyeknél Önök (a készítő) tulajdonosok vagy adminisztrátorok —
  fejlesztéshez, teszteléshez, vagy olyan ügyfélcégekhez elég, ahol ilyen
  szerepük van. A jóváhagyó oldalon „Ellenőrizetlen alkalmazás” figyelmeztetés
  jelenik meg; más cégnél a jóváhagyás nem sikerül (`app_not_verified`).
- Ha más vállalkozások is használni fogják, kattintsanak az **Ellenőrzés
  kérése** gombra (weboldal és kapcsolattartó e-mail-cím szükséges). A
  Bizonylat jóváhagyása után bármely cég összekapcsolhatja; a döntésről
  e-mailben értesítjük Önöket. Az ellenőrzött alkalmazás nevének vagy
  weboldalának módosítása után újra ellenőrizzük; a meglévő összekapcsolások
  addig is működnek.

### 2. A felhasználó átirányítása a jóváhagyó oldalra

```
https://app.bizonylat.hu/oauth/authorize
  ?response_type=code
  &client_id=bzc_…
  &redirect_uri=https%3A%2F%2Fyourapp.example%2Fbizonylat%2Fcallback
  &state=<véletlen érték, a felhasználó munkamenetéhez kötve>
  &code_challenge=<BASE64URL(SHA256(code_verifier))>
  &code_challenge_method=S256
  &scope=invoices:write%20invoices:read%20payments:write
```

| Paraméter | |
|---|---|
| `response_type` | `code` (az egyetlen érték) |
| `client_id` | Az Önök client id-ja |
| `redirect_uri` | Pontosan az egyik regisztrált URI (karakterre egyezően) |
| `state` | Ajánlott. Véletlen érték, amelyet visszaérkezéskor ellenőriznek (CSRF-védelem); változatlanul visszakapják |
| `code_challenge` | Ajánlott. 43–128 karakter `[A-Za-z0-9-._~]` |
| `code_challenge_method` | `S256` (ajánlott) vagy `plain` |
| `scope` | Ajánlott. Szóközzel elválasztott jogosultságok (lent); ha hiányzik: `api` (teljes hozzáférés) |

**Jogosultságok (scope-ok)** — csak azt kérjék, amit használnak: a jóváhagyó
oldal pontosan ezeket sorolja fel, és a token mást nem tehet (minden máson
`403` `INSUFFICIENT_SCOPE`, az `error.requiredScope` mezőben a szükséges
jogosultsággal). A `GET /public/v1/me` és a `GET /public/v1/reference`
bármely jogosultsággal működik.

| Scope | Mit enged |
|---|---|
| `invoices:read` | `GET /public/v1/invoices…` (lista, egy számla, tételek, PDF, NAV-állapot) |
| `invoices:write` | Létrehozás, kiállítás, piszkozat módosítása, sztornó, helyesbítés, küldés, átalakítás, érvénytelenítés |
| `payments:write` | `PATCH …/payment-status`, `POST …/payments` |
| `clients:read` / `clients:write` | Partnerek |
| `products:read` / `products:write` | Termékek (a `/products/sync` is) |
| `quotes:read` / `quotes:write` | Árajánlatok |
| `company:write` | `PATCH /public/v1/company` (cégadatok; olvasni bármely jogosultsággal lehet) |
| `expenses:write` | `/public/v1/expenses` (bejövő számlák és kiadások: lista, kézi rögzítés, módosítás, törlés) |
| `webhooks` | `/public/v1/webhooks` |
| `api` | Minden, mint egy kézzel létrehozott kulcs (a kérésnapló is) |

**Teljes oldalas átirányításként vagy felugró ablakban** nyissák meg. Az oldal
iframe-ben nem jeleníthető meg (nem engedi a beágyazást, így más oldal nem
veheti rá trükkel a felhasználót a jóváhagyásra). Ha a felhasználó nincs
belépve, a Bizonylat előbb a belépést (vagy a regisztrációt) mutatja, majd
visszaviszi a jóváhagyó oldalra.

Ismeretlen `client_id` vagy nem regisztrált `redirect_uri` esetén nincs
visszairányítás: az oldal hibát jelez.

### 3. A visszairányítás kezelése

Jóváhagyva:

```
https://yourapp.example/bizonylat/callback?code=…&state=…
```

Elutasítva („Mégse”):

```
https://yourapp.example/bizonylat/callback?error=access_denied&state=…
```

Először a `state`-et ellenőrizzék. A `code` **10 percig** és **egyszer**
használható.

### 4. A kód cseréje tokenre (szerveroldalon)

```bash
curl -X POST "https://api.bizonylat.hu/api/v1/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d grant_type=authorization_code \
  -d code="$CODE" \
  -d redirect_uri="https://yourapp.example/bizonylat/callback" \
  -d client_id="$BIZONYLAT_CLIENT_ID" \
  -d client_secret="$BIZONYLAT_CLIENT_SECRET" \
  -d code_verifier="$CODE_VERIFIER"
```

Az alkalmazás azonosítása a törzsmezők helyett HTTP Basic is lehet
(`Authorization: Basic base64(client_id:client_secret)`). A `redirect_uri`
ugyanaz legyen, mint a 2. lépésben. JSON törzs is elfogadott.

`200 OK`:

```json
{
  "access_token": "bz_live_…",
  "token_type": "Bearer",
  "scope": "invoices:read invoices:write payments:write",
  "tenant": { "id": "…", "name": "Példa Szerviz Kft.", "taxNumber": "12345678-2-42", "sandbox": false }
}
```

**Nincs `expires_in` és nincs refresh token**: a token nem jár le, így a
háttérben végzett munka (számla kiállítása, amikor senki nincs belépve)
addig működik, amíg a cég vagy az Önök alkalmazása vissza nem vonja.

Az `access_token`-t titkosítva, ügyfélcégenként tárolják (`tenant.id`
szerint). A `tenant.sandbox: true` tesztcéget (Tesztcég) jelent: csak a NAV
tesztkörnyezetébe küld, semmi, amit kiállít, nem valódi bizonylat.

Hibák (`400`, illetve `invalid_client` esetén `401`), RFC 6749 formában:

```json
{ "error": "invalid_grant", "error_description": "The code is invalid, expired or already used" }
```

| `error` | Jelentés |
|---|---|
| `invalid_request` | Hiányzik egy kötelező paraméter |
| `invalid_client` | Ismeretlen/inaktív `client_id` vagy hibás titkos kulcs |
| `invalid_grant` | A kód érvénytelen, lejárt vagy már felhasznált; a `redirect_uri` vagy a `code_verifier` nem egyezik |
| `unsupported_grant_type` | Csak az `authorization_code` támogatott |

### 5. A token használata

Pontosan úgy, mint egy API-kulcsot: `Authorization: Bearer bz_live_…` minden
`/public/v1/…` hívásban. A `GET /public/v1/me` hívással megjeleníthetik a
beállításaikban, hogy „Összekapcsolva: <cégnév>”. Ha később `401` jön, a cég
visszavonta az összekapcsolást (vagy újra összekapcsolta, és az új token
lépett a helyére): ilyenkor jelenítsék meg a „Bizonylat újbóli
összekapcsolása” gombot.

### 6. Leválasztás az Önök oldaláról (RFC 7009)

```bash
curl -X POST "https://api.bizonylat.hu/api/v1/oauth/revoke" \
  -u "$BIZONYLAT_CLIENT_ID:$BIZONYLAT_CLIENT_SECRET" \
  -d token="$ACCESS_TOKEN"
```

Mindig `200 {}` (ismeretlen vagy már visszavont tokenre is). Így csak a
saját alkalmazásuk tokenjei vonhatók vissza.

### Tesztelés

Hozzanak létre egy tesztcéget (Tesztcég) a Bizonylatban, és azt kapcsolják
össze: csak a NAV tesztkörnyezetébe küld (`tenant.sandbox: true`). Helyi
fejlesztéshez regisztráljanak `http://localhost…` visszairányítási URI-t.

## Havi API-számlakeret

Az API minden csomagban elérhető. **2026. október 1-jétől** (budapesti idő)
az **API-n keresztül** kiállított számlák száma naptári hónaponként
(budapesti idő) csomagonként korlátozott:

| Csomag | API-n kiállított számla havonta |
|---|---|
| Ingyenes | 50 |
| Induló | 300 |
| Növekedés | 1000 |
| Vállalat | korlátlan |

A Bizonylat felületén kiállított számla minden csomagban korlátlan.

**Mi számít bele:** az a számla (`STANDARD`, az előleg- és végszámlát is
beleértve, valamint a `PREPAYMENT`), amely egy `/public/v1` kérés
eredményeként lesz kiállított — `POST /public/v1/invoices` (létrehozás és
kiállítás), `POST /public/v1/invoices/:id/issue` (a
`POST /public/v1/quotes/:id/convert` által készített piszkozatra is) és
`POST /public/v1/invoices/:id/convert` (díjbekérő → számla).
**Soha nem számít bele és soha nem kerül elutasításra:** a sztornó és a
helyesbítés, a díjbekérő (`PROFORMA`), a piszkozat, a felületen kiállított
számla, az előfizetésekből ütemezetten kiállított számla és a tesztcég.

**A keret elérése:** a keretet elérő kérés **72 órás türelmi időt** indít — addig
az API tovább kiállítja a számlákat. Utána a hónap végéig (vagy csomagváltásig)
minden beleszámító kérés **HTTP 402**-vel elutasításra kerül, és nem jön létre
bizonylat:

```json
{
  "message": "The monthly limit of invoices issued through the API on the Free plan (50) has been reached. …",
  "error": {
    "code": "API_INVOICE_LIMIT_REACHED",
    "message": "…",
    "plan": "FREE",
    "limit": 50,
    "used": 53,
    "resetsAt": "2026-12-01",
    "graceEndedAt": "2026-11-21T10:12:00.000Z",
    "nextPlan": "STARTER",
    "nextPlanLimit": 300,
    "upgradeUrl": "https://app.bizonylat.hu/hu/settings#billing"
  }
}
```

`?lang=hu` vagy `Accept-Language: hu` esetén az üzenet magyarul érkezik.
A `resetsAt` a következő hónap első napja. Az `upgradeUrl` a csomagváltás
oldala, illetve a kapcsolatfelvételi oldal, ha a következő csomag a Vállalat
(egyedi árazás). Magasabb (vagy keret nélküli) csomagra váltva az elutasítás
azonnal megszűnik; az új naptári hónap nulláról indul. A sztornó és a
helyesbítés továbbra is működik.

**Fejlécek:** kerettel rendelkező csomagon (a keret alkalmazásától kezdve)
minden beleszámító válasz tartalmazza:

| Fejléc | Érték |
|---|---|
| `X-Bizonylat-Api-Invoice-Limit` | a csomag havi kerete, pl. `300` |
| `X-Bizonylat-Api-Invoice-Used` | az ebben a hónapban beszámított API-számlák, ezzel együtt |
| `X-Bizonylat-Api-Invoice-Reset` | a következő hónap első napja, `YYYY-MM-DD` |
| `X-Bizonylat-Api-Grace-Ends` | csak a türelmi idő alatt: annak vége (ISO 8601, UTC) |

### GET /public/v1/usage

Az e havi darabszám, a keret és az állapot — csak olvasás, nem számít bele.

```json
{
  "data": {
    "plan": "STARTER",
    "exempt": null,
    "period": "2026-11",
    "limit": 300,
    "used": 243,
    "remaining": 57,
    "state": "warning",
    "enforced": true,
    "enforcedFrom": "2026-10-01",
    "upcoming": false,
    "resetsAt": "2026-12-01",
    "reachedAt": null,
    "graceEndsAt": null,
    "nextPlan": "GROWTH",
    "nextPlanLimit": 1000,
    "upgradeUrl": "https://app.bizonylat.hu/hu/settings#billing"
  }
}
```

`state`: `ok`, `warning` (legalább 80 % elfogyott), `grace` (a keret
betelt, `graceEndsAt`-ig még kiállít), `blocked` (a türelmi idő lejárt),
`unlimited` (Vállalat, vagy `exempt`: tesztcég), `not_enforced` (a keret még
nem érvényes — 2026. október 1. előtt `upcoming: true`). A cég tulajdonosai
e-mailt is kapnak 80 %-nál, a keret elérésekor, a türelmi idő alatt naponta és
annak lejártakor.

## GET /public/v1/me

Kié a kulcs — egy „Kapcsolódva: …” képernyőhöz, a beállítás ellenőrzéséhez,
vagy ahhoz, hogy tesztcégnél másként viselkedjen az integráció. Csak olvas,
soha nem számít bele a keretbe; ugyanazokat az `X-Bizonylat-Api-Invoice-*`
fejléceket adja, mint a `/usage`. **Titkos adatot nem ad vissza**: a kulcs
csak a nevével és a megjelenítési előtagjával szerepel.

```json
{
  "data": {
    "company": {
      "id": "3f2b…",
      "name": "Minta Webshop Kft.",
      "taxNumber": "12345678-2-42",
      "euVatId": "HU12345678",
      "sandbox": false
    },
    "plan": "STARTER",
    "usage": { "plan": "STARTER", "period": "2026-11", "limit": 300, "used": 243, "remaining": 57, "state": "warning", "…": "…" },
    "apiKey": { "id": "9a1c…", "name": "WooCommerce", "keyPrefix": "bz_live_1a2b3c4d", "createdAt": "2026-09-01T08:12:44.120Z" }
  }
}
```

- `company.sandbox`: tesztcégnél (Tesztcég) `true` — csak a NAV
  tesztkörnyezetébe küld, semmi, amit kiállít, nem valódi bizonylat.
- `plan`: az érvényes csomag — `FREE`, `STARTER`, `GROWTH` vagy
  `ENTERPRISE`.
- `usage`: pontosan a `GET /public/v1/usage` válaszának `data` mezője
  (lásd fent).
- `apiKey`: a hívó kulcs, ahogyan az irányítópult API oldalán szerepel.

## Hibák

| Státusz | Jelentés |
|---|---|
| 400 | Validációs hiba — az üzenet megnevezi a mezőt (pl. ismeretlen SKU, hiányzó unitPrice). `CLIENT_REQUIRED` / `CLIENT_AND_CLIENT_ID`: a `POST /public/v1/invoices` hívás a `client` és a `clientId` mező közül egyiket sem, illetve mindkettőt tartalmazta. `DUPLICATE_FIELD_ALIAS`: ugyanaz a mező angol és magyar néven is szerepel. `INVALID_EU_VAT_ID`: hibás formátumú `client.euVatId` (vagy két különböző közösségi adószám a `taxNumber` és az `euVatId` mezőben). `INVALID_COUNTRY`: a `client.country` nem felismerhető ország (ISO-kód vagy országnév). `INVALID_TAX_NUMBER`: a NAV által nem fogadható magyar `client.taxNumber`, külföldi ország mellett nem `NNNNNNNN-N-NN` alakú, érvényes ellenőrző számjegyű adószám, vagy `thirdStateTaxId`-be nem áthelyezhető, betűvel kezdődő EU-n kívüli azonosító. `INVALID_THIRD_STATE_TAX_ID`: hibás formátumú, közösségi adószámot vagy magyar adószámot tartalmazó, illetve EU-n kívüli `country` nélküli `client.thirdStateTaxId`. `INVALID_GROUP_MEMBER_TAX_NUMBER`: `client.groupMemberTaxNumber` csoportazonosító (áfakód 5) nélküli `taxNumber` mellett, vagy nem 4-es áfakóddal. `AMOUNT_OUT_OF_RANGE`: az adatbázisban tárolhatónál nagyobb összeg vagy mennyiség (összeg 9 999 999 999 999,99, mennyiség 99 999 999 999,9999). `INVALID_NUMBER`: 4-nél több tizedesjegyű mennyiség, vagy 0 `paidAmount`. `VAT_RATE_CATEGORY_MISMATCH`: olyan `vatRate`, amellyel egyik kategóriát sem jelentjük, vagy nem a küldött `vatCategory` kulcsa. `DATE_TOO_EARLY`: 2010-01-01 előtti dátum. `ISSUE_DATE_IN_FUTURE`: a mai napnál (budapesti idő) későbbi kiállítási dátum. `DATE_RANGE_INVALID`: a kezdő dátumnál korábbi záró dátum (előfizetés `endDate`, árajánlat `validUntil`). `LINE_AMOUNTS_INCONSISTENT`: helyesbítő tétel, amelynek összegei nem a mennyiség × egységár és a kulcs szerint jönnek ki. `INVALID_CONVENTIONAL_INFO`: ismeretlen `conventionalInfo`-kulcs, 100 karakternél hosszabb érték vagy 20-nál több érték. `INVALID_PRODUCT_CODE`: a NAV formátumának nem megfelelő termékkód (lásd `lines[].productCodes`). `ADVANCE_DEDUCTION_NOT_ALLOWED`: `advanceDeductions` olyan bizonylaton, amelyen nem adható meg. Hibás formátumú azonosító az útvonalban szintén 400 |
| 401 | `API_KEY_MISSING` — hiányzik az `Authorization: Bearer …` fejléc. `API_KEY_INVALID` — ismeretlen, csonka vagy visszavont kulcs (kulcsok: felület → API → Kulcsok) |
| 422 | `INVOICE_EXCHANGE_RATE_UNAVAILABLE` — érvénytelen/hiányzó árfolyam (a `0` is) vagy sikertelen MNB-lekérés. `CORRECTION_WITHOUT_CHANGE` — a helyesbítés tételei megegyeznek a jelenlegiekkel. `IDEMPOTENCY_KEY_REUSED` — már másik kéréshez használt `Idempotency-Key`. `PERFORMANCE_DATE_INVALID` — a `/convert` `performanceDate` jövőbeli, egy évnél régebbi vagy nem dátum. `ADVANCE_INVOICE_NOT_DEDUCTIBLE`, `ADVANCE_DEDUCTION_EXCEEDS_REMAINING`, `ADVANCE_DEDUCTION_EXCEEDS_TOTAL` — lásd *Előleg és végszámla* |
| 402 | Csomagkorlát: `API_INVOICE_LIMIT_REACHED` (havi API-számlakeret, a türelmi idő után — lásd *Havi API-számlakeret*) vagy `PLAN_LIMIT_REACHED` (törzs: `{ "error": { "code": "…", … } }`) |
| 403 | `API_ACCESS_DISABLED` — ennél a cégnél egyedi beállítás kikapcsolta az API-hozzáférést (az API minden csomagban elérhető; írjon nekünk). `API_KEY_ROLE_FORBIDDEN` — a kulcs létrehozójának szerepköre nem elég a híváshoz: `PATCH /public/v1/company` (Tulajdonos vagy Admin), az aláírás-végpontok (`error.requiredPermission`). `INSUFFICIENT_SCOPE` — összekapcsolt alkalmazás kulcsa, amely nem kapta meg a híváshoz szükséges jogosultságot |
| 404 | A számla, az előfizetés vagy az ügyfél nem található (rossz id, másik cég, illetve `clientId` esetén archivált ügyfél). `ADVANCE_INVOICE_NOT_FOUND`: az `advanceDeductions[].invoiceId` nem ennek a cégnek a bizonylata |
| 409 | `INVOICE_NOT_DRAFT` (`/issue` nem piszkozatra), `PROFORMA_ALREADY_CONVERTED` (ismételt `/convert` — a `data` a meglévő bizonylatot tartalmazza), `NOT_A_PROFORMA`, `PROFORMA_NOT_ISSUED`. Díjbekérő érvénytelenítése: `PROFORMA_VOIDED` (ismételt `/void` — a `data` a díjbekérőt tartalmazza; vagy érvénytelenített díjbekérő bármilyen módosítása), `PROFORMA_PAID`. Sztornó és helyesbítés: `ALREADY_STORNOED` (a `data` a meglévő sztornót tartalmazza), `INVOICE_CHAIN_NOT_ACCEPTED_BY_NAV`, `INVOICE_NOT_ISSUED`, `PROFORMA_NOT_MODIFIABLE`, `CANNOT_STORNO_A_STORNO`, `CANNOT_CORRECT_A_STORNO`, `CHAIN_FULLY_REVERSED`, `NAV_CREDENTIALS_NOT_VERIFIED`. `PAYMENT_NOT_ALLOWED` (fizetés piszkozaton, sztornón vagy nem pozitív helyesbítésen). `IDEMPOTENCY_KEY_IN_PROGRESS` (ugyanaz az `Idempotency-Key`, amíg az első kérés még fut). A teljes lista okokkal: fent, *Hibák (ezeknél a végpontoknál)* |

**Fiók- és NAV-feltételek** (minden végpont, amely bizonylatot hoz létre vagy
a vevőnek e-mailt küld):

| Státusz | Kód | Mikor |
|---|---|---|
| 409 | `NAV_CONNECTION_REQUIRED` | árajánlat vagy díjbekérő létrehozása (`invoiceType: "PROFORMA"`, kiállítása, árajánlatból díjbekérő), mielőtt a cégnek ellenőrzött NAV-kapcsolata lenne — a felületen Beállítások → NAV kapcsolat; tesztcégnél ellenőrzött *teszt* hitelesítő adatok kellenek |
| 409 | `NAV_CONNECTION_REQUIRED_FOR_EMAIL` | e-mail a vevőnek (`/send-email`, árajánlat `/send`) ellenőrzött NAV-kapcsolat előtt. Semmi nem megy ki, az árajánlat piszkozat marad; a NAV összekötése után küldje újra. A létrehozáskor `sendEmail: true`-val kért e-mail ugyanígy kimarad, és el nem küldöttként látszik |
| 409 | `SANDBOX_BUYER_EMAIL_BLOCKED` | e-mail vevőnek tesztcégből. A tesztcég számlái nem valódiak, ezért csak a cég saját felhasználóinak címére küld; a vevőhöz semmi nem megy ki |
| 409 | `SANDBOX_INVOICE_LIMIT_REACHED` | kiállítás olyan tesztcégben, amely már kiállította a 100 számláját (a piszkozat és a díjbekérő nem számít bele, a sztornó és a helyesbítő igen). Törzs: `error.limit`, `error.used`. Nem jön létre bizonylat (a létrehozó hívás piszkozata is törlődik); piszkozat továbbra is létrehozható. A tesztcég számlái nem valódiak — valódi számlázáshoz hozzon létre egy valódi céget, és kösse össze az éles NAV-val. Nem csomagkorlát: csomagváltás nem oldja fel (409, nem 402) |
| 403 | `ACCOUNT_UNDER_REVIEW` | a cég ügyfélszolgálati ellenőrzésre vár; a jóváhagyásig nem hozható létre bizonylat |
| 409 | `EMAIL_HELD_FOR_REVIEW` | e-mail a vevőnek, amíg a cég ellenőrzés alatt áll — visszatartva, nem ment ki; a jóváhagyás után küldje újra |
| 403 | `TENANT_SUSPENDED` | a cég fel van függesztve (üzenet: *This account has been suspended*, `?lang=hu` esetén magyarul) |

Ezek a hibatörzsek mindkét alakot tartalmazzák: `{ "statusCode", "code", "message", "error": { "code", "message" } }`.

A többi hibatörzs: a Fastify formátuma `{ "statusCode", "code", "error", "message" }`
(a `code` hiányzik az egyszerű 404-nél és néhány mezőszintű 400-nál,
ezek üzenete megnevezi az erőforrást vagy a mezőt), illetve kódolt elutasításnál `{ "message", "error": { "code", "message", … } }`.
A kódot a `code` vagy az `error.code` mezőből olvassa, amelyik szerepel.

### Magyar hibaüzenetek (Hungarian error messages)

A hibaüzenetek alapértelmezés szerint angolul érkeznek. Magyarul kapja őket,
ha `Accept-Language: hu` fejlécet küld (a `hu-HU` is jó; a q-értékeket
figyelembe vesszük, így a magyar legyen az első helyen preferált nyelv), vagy
az URL-hez hozzáfűzi a `?lang=hu` paramétert. A kifejezett `lang` erősebb a
fejlécnél. Minden más esetben — vagy ha egyiket sem küldi — pontosan a fent
leírt angol válaszok érkeznek.

- Csak az emberi olvasásra szánt szöveg változik: a legfelső szintű
  `message` és a beágyazott `error.message` (ahol van) magyar lesz, az eredeti
  angol szöveg pedig mellette, a `messageEn` mezőben marad meg. A válasz
  `Content-Language: hu` fejlécet kap.
- A státuszkódok, a `code` / `error.code` és minden más mező mindkét nyelven
  azonos. **A programlogikát a `code` értékére építse, soha ne az üzenet
  szövegére** — az üzenetek megfogalmazása változhat, a `code` nem.
- A sikeres (2xx) válaszok soha nem változnak, és az Idempotency-Key
  ismétlés sem.
- A `lang` fenntartott paraméter, minden `/public/v1` végpont elfogadja
  (GET, POST, PATCH, DELETE egyaránt); a szűrőkre és az API naplóra nincs
  hatása.

```json
{
  "statusCode": 400,
  "code": "FST_ERR_VALIDATION",
  "error": "Bad Request",
  "message": "Hibás kérés: a „lines[0].quantity” mező kötelező.",
  "messageEn": "body/lines/0 must have required property 'quantity'"
}
```

## Integrációs tudnivalók

- **Kapcsolat ellenőrzése:** közvetlenül azután, hogy a felhasználó beilleszti
  a kulcsot, hívja meg a `GET /public/v1/me` végpontot — ez igazolja, hogy a
  kulcs működik, és visszaadja a cég nevét, azt, hogy tesztcégről van-e szó
  (`company.sandbox`), valamint a csomagot, anélkül hogy bármit létrehozna.
- **Képezze le a saját checkout-mezőit** a kérésre — másra nincs szükség. A
  minimális küldemény: vevőnév + egy tétel névvel, mennyiséggel, egységárral.
- **Fizetés után irányítsa a vevőt a válaszban kapott `publicUrl`-re**
  (vagy jelenítse meg „Számla megtekintése" linkként a visszaigazoló
  oldalán). Az API-hívás alatt (~1–2 mp) mutasson saját töltési állapotot.
- **Idempotencia:** küldjön `Idempotency-Key` fejlécet (műveletenként egyszer
  előállított UUID-t, vagy pl. `order-1234-invoice`) a
  `POST /public/v1/invoices`, a `/storno`, a `/correct` és a
  `POST …/payments` hívásokon, valamint a `POST /public/v1/clients`, a
  `/products` és a `/webhooks` hívásokon. Az ugyanazzal a kulccsal és törzzsel 24 órán
  belül ismételt kérés — például időtúllépés után — az első választ kapja
  vissza (`Idempotent-Replayed: true`), nem állít ki második számlát.
  Rendelésenként továbbra is egyszer hozza létre a számlát (pl. a
  fizetés-visszaigazoló webhookból), és tárolja el a kapott
  `id`/`invoiceNumber` értékeket a rendelésen. Ugyanazt a kulcsot másik
  kéréshez használva `422 IDEMPOTENCY_KEY_REUSED` a válasz; ha az első hívás
  még fut, `409 IDEMPOTENCY_KEY_IN_PROGRESS`. A `/convert` és az `/issue`
  nem fogad kulcsot, és nincs is rá szükség: a `/convert` díjbekérőnként
  idempotens (az ismételt hívás a meglévő bizonylatot adja vissza
  `PROFORMA_ALREADY_CONVERTED` kóddal), az `/issue` pedig soha nem ad egy
  bizonylatnak két sorszámot. Részletek: fent, *Idempotency-Key*.
- **B2C vs. B2B:** magánszemélynél elég a név (+ cím, ha megvan). Céges
  vevőnél mindig küldje a `client.taxNumber`-t, hogy a számla
  ÁFA-levonásra alkalmas, NAV-kompatibilis legyen.
- **Ismert ügyfél:** ha a rendszere már tárolja a Bizonylat-ügyfél
  azonosítóját (a `POST /public/v1/clients`, a
  `GET /public/v1/clients?taxNumber=…` hívásból vagy egy korábbi számla
  `clientId` mezőjéből), a `POST /public/v1/invoices` hívásban a
  `client` helyett küldje a `clientId` mezőt (számlánál, díjbekérőnél és
  piszkozatnál egyaránt). A tárolt ügyfelet változatlanul használjuk. A kettőt
  soha ne küldje együtt: ilyenkor a kérést elutasítjuk
  (`400 CLIENT_AND_CLIENT_ID`), ahelyett hogy találgatnánk, melyiket
  gondolta — ha előbb a tárolt adatokat módosítaná, használja a
  `PATCH /public/v1/clients/:id` végpontot.
- **Sztornó / helyesbítés:** az API-n keresztül is elérhető —
  `POST /public/v1/invoices/:id/storno` (lemondott rendelés) és
  `POST /public/v1/invoices/:id/correct` (helyesbítés). Mindkettőhöz az
  szükséges, hogy a NAV előbb befogadja a számlát (`navStatus: "DONE"`;
  különben `409 INVOICE_CHAIN_NOT_ACCEPTED_BY_NAV`), soha nem számítanak
  bele a havi API-számlakeretbe, és fogadnak `Idempotency-Key` kulcsot. A
  Bizonylat felületén is elvégezhetők, ahol minden API-val kiállított számla
  megjelenik.
- **Szinkronban tartott másolat:** kérdezze le rendszeresen a
  `GET /public/v1/invoices?updatedSince=…` végpontot (az `updatedAt` minden
  változáskor frissül; néhány perces átfedéssel kérdezzen), vagy iratkozzon fel
  webhookokra. A `paymentStatus` több értéket is elfogad egyszerre — az
  `UNPAID,PARTIAL,OVERDUE` minden még nyitott számlát listáz.
- **Ismétlődő számlázás:** minden ütemezetten megújuló tételhez (havi/éves
  csomagok) számla helyett előfizetést hozzon létre — a Bizonylat ezután
  minden megújítási számlát automatikusan kiállít. Lásd az *Előfizetések*
  fejezetet fent.

## API-változási szabály (verziózás és kivezetés)

Az API verziója az útvonalban szerepel: `/public/v1`. A v1-en belül a működő
integráció működő marad; ez a fejezet leírja, mit változtathatunk, és arról
hogyan értesül előre.

**Bővítés — bármikor, előzetes értesítés nélkül.** Az integrációt úgy
készítse el, hogy ezeket elviselje:
- új végpontok;
- új, nem kötelező kérésmezők, lekérdezési paraméterek vagy fejlécek;
- új mezők a válaszokban (az ismeretlen mezőket hagyja figyelmen kívül);
- új hibakódok olyan helyzetekre, amelyek korábban nem fordulhattak elő;
- új webhook-eseménytípusok (csak azokat kapja meg, amelyekre feliratkozott);
- új értékek a választható értékek listáiban (`GET /public/v1/reference`),
  például új pénznem vagy mennyiségi egység.

**Visszafelé nem kompatibilis (törő) változás** — minden, ami miatt egy ma
működő kérés hibára futhat, vagy mást csinál:
- végpont, kérésmező vagy válaszmező megszüntetése vagy átnevezése;
- nem kötelező mező kötelezővé tétele, vagy olyan szigorúbb ellenőrzés, amely
  egy ma elfogadott kérést elutasít;
- mező típusának, formátumának, jelentésének vagy alapértékének módosítása;
- egy meglévő helyzetben visszaadott HTTP-állapotkód vagy hibakód módosítása;
- a hitelesítés, illetve a webhook-kézbesítések szerkezetének vagy
  aláírásának módosítása;
- érték eltávolítása a választható értékek listájából.

**Értesítés: legalább 90 nappal előre.** Törő változás vagy végpont
megszüntetése legkorábban a bejelentést követő 90. napon lép hatályba.
A bejelentés helyei:
- a változásnapló: https://bizonylat.hu/frissitesek;
- e-mail minden olyan cég tulajdonosának, amelynek aktív API-kulcsa van;
- ez a referencia, amelyben az érintett részt *kivezetés alatt* jelöléssel és
  a megszűnés dátumával látjuk el.

A megszűnés dátumáig a korábbi működés megmarad. A v1-en belül meg nem
valósítható, nagyobb változások új verzióként (`/public/v2`) érkeznek; ekkor a
v1 a v2 elérhetővé válásától számítva még legalább 90 napig működik.

**Kivétel:** jogszabály, a NAV előírásainak változása vagy biztonsági javítás
miatt szükséges változás 90 napnál hamarabb is hatályba léphet. Ilyenkor
a lehető legkorábban, ugyanezeken a csatornákon jelentjük be, az ok
megjelölésével.
