Automatikus Számlázás BillX API-val

Nyugta API és nyugtatömbök

Számítógéppel előállított nyugta létrehozása vevőadatok és customer rekord nélkül. Ez nem e-pénztárgépes e-nyugta. A nyugta API a natív /api/billx felület része.

Végpontok

Bázis URL: https://billx.hu/api/billx. Hitelesítés: Authorization: Bearer API_KULCS. A létrehozási kérés formátuma Content-Type: application/json.

1. Nyugtatömb kiválasztása

Az Admin → Számlázás → Nyugtatömbök oldalon hozd létre a tömböket. Az első aktív tömb automatikusan alapértelmezett; később a „Legyen alapértelmezett” gombbal válthatsz. A tömbök azonosítóit az admin listájából vagy a GET /receipt-series válaszából olvashatod ki.

A válasz series_id mezője a ténylegesen használt nyugtatömböt tartalmazza. Nyugtához series_id kell, a számláknál használt block_id itt nem elfogadott. A számlatömbök és a nyugtatömbök külön azonosítókat használnak.

Használt tömb előtagja és számozási formátuma rögzített. A név és az ÁFA-alapérték módosítható; az ÁFA-változás csak az új bizonylatokat érinti. Tömb létrehozása önmagában nem aktiválja az éles kiállítást.

2. A létrehozási kérés mezői

Tételmezők (items[])

ÁFA-prioritás: tétel → nyugtatömb → cég, a cég AAM-jogállásának figyelembevételével. Kezdetben százalékos ÁFA, AAM és TAM támogatott. A mennyiség, egységár és árfolyam JSON számként vagy decimális stringként adható meg, legfeljebb 9 egész és 6 tizedesjeggyel. A bruttó/nettó/ÁFA végösszegeket két tizedesjegyű decimális stringként adja vissza az API.

A válasz exchange_rate mezője a rögzített árfolyam; az exchange_rate_source értéke mnb, provided vagy huf. Ismétlés és korrekció az eredeti árfolyamot használja. MNB-kieséskor a legutóbbi érvényes cache-ből folytatódik a kiállítás. 503 RECEIPT_EXCHANGE_RATE_UNAVAILABLE csak akkor érkezik, ha egyáltalán nincs használható MNB- vagy cache-árfolyam; ekkor explicit árfolyam adható.

A nyugtaszám formátuma NYUGTA-IDC-2026/00000001: a fix NYUGTA- jelölés a számlák BILLX- jelölésétől eltér, ezért azonos tömbelőtag is használható. A módosítás és sztornó ugyanebben a számsorban kap új számot.

Az API pozitív végösszeget és 900 000 HUF alatti, árfolyammal átszámított bruttó ellenértéket vár. A teljes fizetésnek legkésőbb a teljesítéskor meg kell történnie; jövőbeli időpont nem fogadható el. Csak dátum megadásakor naponként történik az ellenőrzés, ezért a napon belüli sorrendhez add meg a fulfillment_at mezőt is. A fizetési szolgáltató ellenőrzése a kliens feladata. Az AAM-ellenőrzés a BillX-ben tárolt számla- és nyugtabevételeket együtt vizsgálja.

3. Kipróbálás tesztkulccsal

Először kérd le az ÁFA-profilokat, és válaszd ki a példához a VAT27 rendszerprofilt:

curl 'https://billx.hu/api/billx/vat-profiles' \
  -H 'Authorization: Bearer test_billx_api_key_demo_12345678'

Az alábbi vat_profile_id: 1 példaazonosítót szükség esetén cseréld a kapott ID-ra. A tesztmód series_id: 1 értéke a demo tömböt jelöli; a mező el is hagyható. Saját kulcsnál a saját nyugtatömböd ID-ját használd.

curl -X POST 'https://billx.hu/api/billx/receipts' \
  -H 'Authorization: Bearer test_billx_api_key_demo_12345678' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: webshop-order-84729' \
  --data-binary '{
    "external_id": "webshop-order-84729",
    "series_id": 1,
    "fulfillment_date": "2026-10-24",
    "fulfillment_at": "2026-10-24T13:03:24+02:00",
    "paid_at": "2026-10-24T13:03:24+02:00",
    "payment_completed": true,
    "customer_type": "individual",
    "invoice_requested": false,
    "payment_method": "card",
    "currency": "HUF",
    "items": [
      {
        "name": "Teszt szolgáltatás",
        "unit": "db",
        "quantity": 1,
        "gross_unit_price": "1270.00",
        "vat_profile_id": 1
      }
    ]
  }'

Sikeres tesztválasz: HTTP 201. A következő részlet a fő mezőket szemlélteti; a válasz teljes items listát is tartalmaz. A tesztnyugtaszám vége a kérés tartalmától függ.

{
  "id": null,
  "series_id": 1,
  "test_mode": true,
  "receipt_number": "TEST-NY-2026-a1b2c3d4e5f6",
  "status": "issued",
  "document_kind": "sale",
  "issue_date": "2026-10-24",
  "fulfillment_date": "2026-10-24",
  "paid_at": "2026-10-24T11:03:24Z",
  "payment_method": "card",
  "currency": "HUF",
  "gross_total": "1270.00",
  "huf_gross_total": "1270.00",
  "vat_summary": [
    {"vat_profile_id": 1, "code": "VAT27", "rate": "27.00", "gross": "1270.00", "net": "1000.00", "vat": "270.00"}
  ],
  "external_id": "webshop-order-84729",
  "receipt_url": null,
  "pdf_url": null,
  "nav_report_status": "not_submitted_test_mode"
}

A tesztkulcs nem ment nyugtát, nem foglal valódi sorszámot, nem érinti az AAM-keretet és nem küld a NAV-hoz. A tesztválasz issued állapota szimuláció. A demo lista üres, a tesztnyugta később ID alapján nem kérhető le, és PDF/megtekintési link sem készül. A tárolt idempotencia is csak a saját fiókos kiállításnál értelmezett.

4. Idempotencia, megtekintés és PDF

Tárolt nyugtakiállításnál minden rendeléshez stabil external_id-t használj. Az opcionális Idempotency-Key 1–191 látható ASCII karakterből állhat, szóköz nélkül. Azonos normalizált tartalom ismétlése a meglévő nyugtát adja vissza 200 státusszal; eltérő tartalom azonos külső azonosítóval vagy kulccsal 409 RECEIPT_EXTERNAL_ID_CONFLICT.

Az alapértelmezett tömb későbbi megváltoztatása nem helyezi át a nyugtát: az idempotens ismétlés az eredeti id, receipt_number és series_id értékeket adja vissza. Új bizonylat sorszáma a tömb előtagjából, az évből és a folyamatos számlálóból áll, például WEB-2026-00000001.

Engedélyezett, tárolt kiállításnál az id valós azonosító, a receipt_url véletlen tokenes https://billx.hu/r/{token} hivatkozás. Ez API-kulcs nélkül megnyitható, és az oldalról a PDF is letölthető. A pdf_url az autentikált /api/billx/receipts/{id}/pdf végpontra mutat; böngészős sikeroldalon a receipt_url-t használd. A dokumentum a kiállításkor mentett kibocsátó- és tételadatokból készül.

5. Hibakezelés

{
  "error": "RECEIPT_SERIES_NOT_FOUND",
  "message": "Select one receipt series; a unique default is required when series_id is omitted."
}

6. Módosítás és sztornó

Mindkét művelet az eredeti nyugta ID-jára hivatkozik, és saját sorszámú, PDF-ben is letölthető okiratot állít ki az eredeti tömbben. Az eredeti pénzügyi tartalom megmarad. Nyugtát törlő végpont nincs.

POST /receipts/{id}/cancel – teljes sztornó a korábbi módosítások után fennmaradó összegre:

{
  "external_id": "order-84729-cancel",
  "reason": "Teljes visszatérítés"
}

POST /receipts/{id}/modify – egytételes nyugta részleges visszatérítése:

{
  "external_id": "order-84729-refund-1",
  "reason": "Részleges visszatérítés",
  "gross_delta": "-3.00"
}

Több eredeti tételnél a gross_delta helyett az érintett tételeket add meg: "items": [{"position": 0, "gross_delta": "-3.00"}]. A position az eredeti tétel nullától induló indexe. Az összegek az eredeti nyugta pénznemében értendők, legfeljebb két tizedessel. A pénznem és az eredeti ÁFA nem változtatható.

Kötelező az egyedi external_id és az indok (reason, legfeljebb 2000 karakter). Az opcionális effective_date az eredeti kiállítás és a mai nap közötti dátum; alapértéke a mai nap. Pozitív korrekcióhoz payment_completed: true és tényleges, RFC3339 paid_at szükséges. A módosítás nem utal vissza pénzt.

Új okirat: HTTP 201. Azonos kérés ismétlése: HTTP 200, ugyanaz az okirat. Újabb sztornó már sztornózott nyugtára: 409 RECEIPT_ALREADY_CANCELLED. A tétel maradékánál nagyobb csökkentés: 422 RECEIPT_CORRECTION_EXCEEDS_REMAINING. Többtételes nyugtához hiányzó tételbontás: 422 RECEIPT_CORRECTION_ITEMS_REQUIRED. A demo nem tárol nyugtát, így annak módosítása és sztornója 404.

7. NAV és kézbesítési állapot

A válasz nav_report_status mezője: pending (napi zárásra vár), queued, sending, retry, uncertain, failed vagy accepted. A háttérfeldolgozó csak lezárt napokat összesít, tömb, pénznem és árfolyam szerint. A NAV elfogadását a accepted jelzi; a nyugta HTTP 201 válasza a kiállítás sikerét jelenti.

A delivery_status értékei: not_requested, pending, sending, sent, uncertain, failed. Bizonytalan NAV- vagy e-mail-válasznál a rendszer megőrzi a bizonylatot, és nem ismétli meg vakon a küldést. Az állapotokat a nyugta újralekérésével és az adminban követheted.

Éles kiállításkor 503 RECEIPT_NAV_NOT_READY vagy RECEIPT_WORKER_NOT_READY a NAV-beállítás vagy háttérfeldolgozó hiányát jelzi. 422 RECEIPT_NAV_VAT_MAPPING_INVALID: hiányzó vagy lejárt NAV ÁFA-hozzárendelés. RECEIPT_NAV_CURRENCY_INVALID: nem támogatott deviza vagy árfolyam. Az éles árfolyam 1–1000 közötti, legfeljebb négy tizedesjegyű.

Checkout: számlakérés vagy céges vásárlás esetén marad a partner létrehozása és a POST /invoices folyamat. A nyugtás checkoutot a cég éles nyugtakiállításának aktiválása után kapcsold be. Egy fizetéshez egy bizonylattípust válassz; nyugtához ne hozz létre fiktív „Magánszemély” partnert.