FEJLESZTŐI API

Számlázz a saját
rendszeredből.

Az ÚjSzámla.hu egyszerű REST JSON API-t ad a számlázási folyamatok automatizálásához. Hozz létre számlát, töltsd le a PDF-et, küldd el e-mailben, rögzíts fizetést, vagy készíts sztornó és helyesbítő bizonylatot – mindezt API-kulccsal, kiszámítható válaszokkal.

Gyors indulás Részletes specifikáció

✓ API-kulcsos hitelesítés ✓ Teszt- és éles környezet ✓ Idempotens számlalétrehozás

MIELŐTT ELKEZDED

Három dolog, és mehet az első hívás.

Az API ugyanazt a számlázási motort használja, mint a webes felület, így a két felületen kiállított bizonylatok pontosan ugyanúgy viselkednek.

Fiók és cég

Regisztrálj, majd add meg a számlázó vállalkozás adatait és legalább egy számlatömböt. Az API minden kérésben elvárja a számlatömböt.

API-kulcs

A belépés után a Beállítások → API-kulcsok oldalon hozhatsz létre kulcsot. A nyers kulcs csak egyszer látható, jegyezd fel biztonságos helyre.

Környezet

Tesztelj nyugodtan a tesztkörnyezetben, élesíts, ha kész vagy. A két környezet külön adatbázison fut, kulcsot és adatot nem kever.

GYORS INDULÁS

Az első számla három lépésben.

Az alábbi példák a tesztkörnyezetet használják. Élesben csak a gazdagépnév változik: https://api.ujszamla.hu.

Ellenőrizd az elérhetőséget

Ez a végpont nem igényel kulcsot, jó első kapcsolatpróbának.

curl

curl https://api-test.ujszamla.hu/api/v1/ping

válasz

{
  "status": "ok",
  "version": "v1",
  "time": "2026-10-05T09:12:00+02:00",
  "environment": "test"
}

Hozz létre egy számlát

A számlalétrehozás egyetlen, azonnal véglegesítő művelet. A Idempotency-Key fejléc kötelező: ha ugyanezt a kérést újraküldöd, nem készül második számla.

curl

curl -X POST https://api-test.ujszamla.hu/api/v1/invoices \
  -H "Authorization: Bearer $UJSZAMLA_API_KEY" \
  -H "Idempotency-Key: order-2026-987" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "ORDER-2026-987",
    "document_type": "INVOICE",
    "document_block": "WEB",
    "fulfillment": { "type": "DATE", "date": "2026-10-01" },
    "payment": { "method": "TRANSFER", "due_date": "2026-10-09", "paid": false },
    "currency": { "code": "HUF" },
    "customer": {
      "vat_status": "DOMESTIC",
      "name": "Minta Kft.",
      "tax_number": "12345678-2-43",
      "address": {
        "country_code": "HU",
        "postal_code": "1111",
        "city": "Budapest",
        "address_line": "Minta utca 1."
      },
      "email": "szamla@minta.hu"
    },
    "items": [
      {
        "description": "Tanácsadás",
        "quantity": "2",
        "unit": "HOUR",
        "unit_net_price": "25000",
        "vat": { "type": "PERCENT", "rate": "27" }
      }
    ],
    "send_email": false
  }'

Használd a választ

Sikeres létrehozásnál 201-et és a számla adatait kapod. Innen a visszaadott id-vel tölthető le a PDF, küldhető e-mail vagy rögzíthető fizetés.

201 Created

{
  "id": 1234,
  "invoice_number": "WEB/2026/0042",
  "document_type": "INVOICE",
  "external_id": "ORDER-2026-987",
  "status": "finalized",
  "issued_at": "2026-10-01",
  "fulfillment_date": "2026-10-01",
  "payment_deadline": "2026-10-09",
  "currency": "HUF",
  "totals": { "net": "50000", "vat": "13500", "gross": "63500" },
  "email_status": "not_requested",
  "nav_status": "submitted",
  "pdf_available": true,
  "idempotent_replay": false
}

PDF letöltése

curl -L https://api-test.ujszamla.hu/api/v1/invoices/1234/pdf \
  -H "Authorization: Bearer $UJSZAMLA_API_KEY" \
  -o szamla-1234.pdf

ugyanaz PHP-ból (curl)

<?php
$payload = [
    'external_id'    => 'ORDER-2026-987',
    'document_type'  => 'INVOICE',
    'document_block' => 'WEB',
    'fulfillment'    => ['type' => 'DATE', 'date' => '2026-10-01'],
    'payment'        => ['method' => 'TRANSFER', 'due_date' => '2026-10-09'],
    'currency'       => ['code' => 'HUF'],
    'customer'       => [
        'vat_status' => 'DOMESTIC',
        'name'       => 'Minta Kft.',
        'tax_number' => '12345678-2-43',
        'address'    => [
            'country_code' => 'HU',
            'postal_code'  => '1111',
            'city'         => 'Budapest',
            'address_line' => 'Minta utca 1.',
        ],
        'email' => 'szamla@minta.hu',
    ],
    'items' => [[
        'description'    => 'Tanácsadás',
        'quantity'       => '2',
        'unit'           => 'HOUR',
        'unit_net_price' => '25000',
        'vat'            => ['type' => 'PERCENT', 'rate' => '27'],
    ]],
    'send_email' => false,
];

$ch = curl_init('https://api-test.ujszamla.hu/api/v1/invoices');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . getenv('UJSZAMLA_API_KEY'),
        'Idempotency-Key: order-2026-987',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS     => json_encode($payload),
]);

$response = curl_exec($ch);
$status   = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

$invoice = json_decode($response, true);
// $invoice['id'], $invoice['invoice_number'], $invoice['pdf_available']

VÉGPONTOK

Egy API, a teljes számlázási folyamatra.

Minden /api/v1/ végpont a kulcsodhoz tartozó cég adataira van korlátozva. A {id} a számlalétrehozáskor visszaadott belső azonosító.

Metódus	Útvonal	Leírás
GET	`/api/v1/ping`	Állapotellenőrzés – nem igényel kulcsot.
POST	`/api/v1/invoices`	Számla létrehozása (kötelező `Idempotency-Key`).
GET	`/api/v1/invoices/{id}`	Számla lekérése.
GET	`/api/v1/invoices/{id}/pdf`	A számla PDF-jének letöltése.
POST	`/api/v1/invoices/{id}/send`	Számla küldése vagy újraküldése e-mailben.
GET	`/api/v1/invoices/{id}/payments`	A számlához rögzített fizetések listája.
POST	`/api/v1/invoices/{id}/payments`	Fizetés rögzítése.
GET	`/api/v1/invoices/{id}/chain`	A számlalánc állapota (verzió, tételek, dokumentumok).
POST	`/api/v1/invoices/{id}/storno`	Sztornó számla létrehozása.
POST	`/api/v1/invoices/{id}/corrections`	Helyesbítő számla létrehozása.

JÓ TUDNI

Ami megkímél a fejfájást.

Néhány viselkedés, amit érdemes fejben tartani az integráció során.

Hitelesítés

Küldd a kulcsot az Authorization: Bearer ujsz_... fejlécben, vagy kényelmi alternatívaként az X-Api-Key: ujsz_... fejlécben. A kulcs a céghez kötődik, és minden művelet annak adataira korlátozódik.

Idempotencia

A számlalétrehozásnál kötelező az Idempotency-Key. Azonos kulcs és azonos törzs esetén a korábbi eredményt kapod vissza (idempotent_replay: true); eltérő tartalom esetén 409 konfliktust.

Hibák

Minden hiba egységes JSON formátumban érkezik (type, code, message, request_id, errors[]), és minden válasz tartalmaz X-Request-Id fejlécet a hibakereséshez.

Forgalmi korlát

Túllépéskor 429 Too Many Requests és Retry-After fejléc érkezik. A limitek kulcsonként értendők, és a terheléstől függően hangolhatók.

Teszt és éles

A két környezet külön adatbázison fut. A tesztkörnyezetben készült számlák PDF-je „Teszt" jelölést kap, és a NAV-adatszolgáltatás is teszt módban marad.

Biztonság

Az API-kulcsot csak szerveroldalon tárold és használd. Sose kerüljön nyilvános, böngészőből elérhető kódba. Gyanú esetén a kulcs a felületen azonnal visszavonható.

Készen állsz a részletekre?

A teljes OpenAPI 3 leírás minden mezőt, sémát és hibakódot tartalmaz.

Részletes specifikáció

Számlázz a sajátrendszeredből.