API referencia – ÚjSzámla.hu

MIELŐTT ELKEZDED

Négy dolog, és mehet az első hívás.

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ó. A kódpéldák nyelve a lap tetején váltható.

Hitelesítés

Küldd a kulcsot az Authorization: Bearer ujsz_... fejlécben, vagy kényelmi alternatívaként X-Api-Key: ujsz_... néven. A kulcs a céghez kötődik; a nyers kulcs csak létrehozáskor látható.

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ő tartalomnál 409.

Hibák

Minden hiba egységes JSON-t ad (type, code, message, request_id, errors[]), és minden válasz tartalmaz X-Request-Id fejlécet.

Forgalmi korlát

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

INVOICES

Számlák életciklusa

Létrehozás, lekérés, PDF, kézbesítés, fizetések, valamint sztornó és helyesbítés – mind ugyanazon a számlaláncon.

POST /api/v1/invoices #

Számla létrehozása

Egyetlen tranzakcióban véglegesíti a számlát, kiosztja a számlaszámot és elkészíti a PDF-et. Azonnal véglegesítő művelet, nincs külön „véglegesítés” lépés.

🔒 API-kulcs Idempotency-Key kötelező

Fejlécek

Fejléc	Típus	Leírás
`Authorization`	string	`Bearer ujsz_...`, avagy `X-Api-Key`.
`Idempotency-Key`	string, max 191	Egy konkrét művelet biztonságos megismétlésére. kötelező

Példa kérés

cURL

curl -X POST https://api.ujszamla.hu/api/v1/invoices \
  -H "Authorization: Bearer ujsz_..." \
  -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" },
    "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
  }'

<?php
require 'vendor/autoload.php';

use GuzzleHttp\Client;

$client = new Client([
    'base_uri' => 'https://api.ujszamla.hu',
    'headers'  => [
        'Authorization'   => 'Bearer ' . getenv('UJSZAMLA_API_KEY'),
        'Idempotency-Key' => 'order-2026-987',
        'Accept'          => 'application/json',
    ],
]);

$response = $client->post('/api/v1/invoices', [
    'json' => [
        '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,
    ],
]);

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

<?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.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),
]);

$invoice = json_decode(curl_exec($ch), true);
curl_close($ch);

const response = await fetch('https://api.ujszamla.hu/api/v1/invoices', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.UJSZAMLA_API_KEY}`,
    'Idempotency-Key': 'order-2026-987',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    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,
  }),
});

const invoice = await response.json();
console.log(invoice.id, invoice.invoice_number);

import os, requests

response = requests.post(
    'https://api.ujszamla.hu/api/v1/invoices',
    headers={
        'Authorization': f"Bearer {os.environ['UJSZAMLA_API_KEY']}",
        'Idempotency-Key': 'order-2026-987',
    },
    json={
        '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,
    },
    timeout=30,
)
response.raise_for_status()
invoice = response.json()
print(invoice['id'], invoice['invoice_number'])

using System.Net.Http.Json;
using System.Text.Json;

var http = new HttpClient();
http.DefaultRequestHeaders.Authorization = new System.Net.Http.Headers.AuthenticationHeaderValue(
    "Bearer", Environment.GetEnvironmentVariable("UJSZAMLA_API_KEY"));

var request = new HttpRequestMessage(HttpMethod.Post, "https://api.ujszamla.hu/api/v1/invoices");
request.Headers.Add("Idempotency-Key", "order-2026-987");
request.Content = JsonContent.Create(new
{
    external_id = "ORDER-2026-987",
    document_type = "INVOICE",
    document_block = "WEB",
    fulfillment = new { type = "DATE", date = "2026-10-01" },
    payment = new { method = "TRANSFER", due_date = "2026-10-09" },
    currency = new { code = "HUF" },
    customer = new
    {
        vat_status = "DOMESTIC",
        name = "Minta Kft.",
        tax_number = "12345678-2-43",
        address = new { country_code = "HU", postal_code = "1111", city = "Budapest", address_line = "Minta utca 1." },
        email = "szamla@minta.hu",
    },
    items = new[]
    {
        new { description = "Tanácsadás", quantity = "2", unit = "HOUR", unit_net_price = "25000", vat = new { type = "PERCENT", rate = "27" } },
    },
    send_email = false,
});

var response = await http.SendAsync(request);
response.EnsureSuccessStatusCode();
var invoice = await response.Content.ReadFromJsonAsync<JsonElement>();
Console.WriteLine(invoice.GetProperty("invoice_number").GetString());

Kérés törzse

Mező	Típus	Leírás
`external_id`	string opc.	A külső rendszer üzleti azonosítója; cégen és forráson belül egyedi.
`document_type`	enum	`INVOICE` \| `PROFORMA` \| `ADVANCE` kötelező
`document_block`	string	A cég aktív számlatömbjének előtagja (pl. `WEB`). kötelező
`issued_at`	date opc.	Kiállítás dátuma; elhagyva a szerver tölti ki.
`fulfillment.type`	enum	`DATE`
`fulfillment.date`	date	Teljesítés dátuma. kötelező
`payment.method`	enum	`TRANSFER` \| `CASH` \| `CARD`
`payment.due_date`	date	Fizetési határidő.
`payment.paid`	boolean	Alapérték: `false`.
`currency.code`	string	ISO pénznem (pl. `HUF`).
`currency.exchange_rate`	string opc.	Devizás számlához; elhagyva MNB árfolyam.
`customer.vat_status`	enum	`DOMESTIC` \| `PRIVATE_PERSON` \| `OTHER`
`customer.name`	string	Vevő neve.
`customer.tax_number`	string opc.	Adószám.
`customer.address.*`	object	`country_code`, `postal_code`, `city`, `address_line`.
`customer.email`	string opc.	Kötelező, ha `send_email: true`.
`items[]`	array	Legalább 1 tétel: `description`, `quantity`, `unit`, `unit_net_price`, `vat`.
`items[].vat.type`	enum	`PERCENT` (+`rate`) \| `EXEMPT`/`OTHER` (+ NAV `code`).
`send_email`	boolean	Alapérték: `false`. `true` esetén érvényes e-mail kötelező.
`note`	string opc.	Nyilvános megjegyzés a számlán.

Válaszok

201A számla létrejött

application/json

{
  "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
}

200Korábbi, azonos idempotenciájú kérés eredménye

Ugyanaz a séma, mint a 201-nél, de nem készül új számla: a válasz a korábbi eredmény, és idempotent_replay: true.

400 / 401 / 403 / 404 / 409 / 422Hibaválasz

Egységes hibaséma. Tipikus kódok: DOCUMENT_BLOCK_REQUIRED, IDEMPOTENCY_KEY_REUSED (409), EXTERNAL_ID_CONFLICT (409), INVOICE_VALIDATION_FAILED (422).

GET /api/v1/invoices/{id} #

Számla lekérése

A kulcs cégéhez tartozó számla adatai. Más cég számlája 404 INVOICE_NOT_FOUND.

🔒 API-kulcs

Paraméterek

Név	Típus	Leírás
`id` path, kötelező	integer	Belső számlaazonosító (pl. `1234`).

Példa kérés

cURL

curl https://api.ujszamla.hu/api/v1/invoices/1234 \
  -H "Authorization: Bearer ujsz_..."

<?php
require 'vendor/autoload.php';

$response = (new GuzzleHttp\Client([
    'base_uri' => 'https://api.ujszamla.hu',
    'headers'  => ['Authorization' => 'Bearer ' . getenv('UJSZAMLA_API_KEY')],
]))->get('/api/v1/invoices/1234');

$invoice = json_decode($response->getBody()->getContents(), true);

<?php
$ch = curl_init('https://api.ujszamla.hu/api/v1/invoices/1234');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . getenv('UJSZAMLA_API_KEY')],
]);
$invoice = json_decode(curl_exec($ch), true);
curl_close($ch);

const response = await fetch('https://api.ujszamla.hu/api/v1/invoices/1234', {
  headers: { 'Authorization': `Bearer ${process.env.UJSZAMLA_API_KEY}` },
});

const invoice = await response.json();

import os, requests

response = requests.get(
    'https://api.ujszamla.hu/api/v1/invoices/1234',
    headers={'Authorization': f"Bearer {os.environ['UJSZAMLA_API_KEY']}"},
    timeout=30,
)
invoice = response.json()

using System.Net.Http.Json;
using System.Text.Json;

var http = new HttpClient();
http.DefaultRequestHeaders.Authorization = new System.Net.Http.Headers.AuthenticationHeaderValue(
    "Bearer", Environment.GetEnvironmentVariable("UJSZAMLA_API_KEY"));

var invoice = await http.GetFromJsonAsync<JsonElement>("https://api.ujszamla.hu/api/v1/invoices/1234");

Válaszok

200A számla adatai

Ugyanaz az Invoice séma, mint a létrehozás válaszánál (201 példa).

401 / 404Hibaválasz

Érvénytelen vagy hiányzó kulcs, illetve nem létező / más céghez tartozó számla.

GET /api/v1/invoices/{id}/pdf #

Számla PDF letöltése

A véglegesített számla PDF-jét adja vissza binárisan. Ha még nem készült PDF, a válasz 404 PDF_NOT_FOUND.

🔒 API-kulcs

Példa kérés

cURL

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

<?php
require 'vendor/autoload.php';

$response = (new GuzzleHttp\Client([
    'base_uri' => 'https://api.ujszamla.hu',
    'headers'  => ['Authorization' => 'Bearer ' . getenv('UJSZAMLA_API_KEY')],
]))->get('/api/v1/invoices/1234/pdf');

file_put_contents('szamla-1234.pdf', $response->getBody()->getContents());

<?php
$ch = curl_init('https://api.ujszamla.hu/api/v1/invoices/1234/pdf');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . getenv('UJSZAMLA_API_KEY')],
]);
$pdf = curl_exec($ch);
curl_close($ch);
file_put_contents('szamla-1234.pdf', $pdf);

const response = await fetch('https://api.ujszamla.hu/api/v1/invoices/1234/pdf', {
  headers: { 'Authorization': `Bearer ${process.env.UJSZAMLA_API_KEY}` },
});

const pdf = Buffer.from(await response.arrayBuffer());
require('fs').writeFileSync('szamla-1234.pdf', pdf);

import os, requests

response = requests.get(
    'https://api.ujszamla.hu/api/v1/invoices/1234/pdf',
    headers={'Authorization': f"Bearer {os.environ['UJSZAMLA_API_KEY']}"},
    timeout=30,
)
open('szamla-1234.pdf', 'wb').write(response.content)

var http = new HttpClient();
http.DefaultRequestHeaders.Authorization = new System.Net.Http.Headers.AuthenticationHeaderValue(
    "Bearer", Environment.GetEnvironmentVariable("UJSZAMLA_API_KEY"));

var pdf = await http.GetByteArrayAsync("https://api.ujszamla.hu/api/v1/invoices/1234/pdf");
await File.WriteAllBytesAsync("szamla-1234.pdf", pdf);

Válaszok

200A számla PDF-je (application/pdf)

Bináris tartalom, Content-Type: application/pdf.

401 / 404Hibaválasz

Nincs jogosultság, vagy a PDF még nem elérhető.

POST /api/v1/invoices/{id}/send #

Számla e-mailben való küldése / újraküldése

A számla e-mailes kiküldését (újra)sorba állítja. Csak véglegesített számlához és érvényes vevői e-mail-címhez. A küldés aszinkron.

🔒 API-kulcs

Példa kérés

cURL

curl -X POST https://api.ujszamla.hu/api/v1/invoices/1234/send \
  -H "Authorization: Bearer ujsz_..."

<?php
require 'vendor/autoload.php';

$response = (new GuzzleHttp\Client([
    'base_uri' => 'https://api.ujszamla.hu',
    'headers'  => ['Authorization' => 'Bearer ' . getenv('UJSZAMLA_API_KEY')],
]))->post('/api/v1/invoices/1234/send');

$result = json_decode($response->getBody()->getContents(), true); // email_status: queued

<?php
$ch = curl_init('https://api.ujszamla.hu/api/v1/invoices/1234/send');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . getenv('UJSZAMLA_API_KEY')],
]);
$result = json_decode(curl_exec($ch), true);
curl_close($ch);

const response = await fetch('https://api.ujszamla.hu/api/v1/invoices/1234/send', {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${process.env.UJSZAMLA_API_KEY}` },
});

const result = await response.json(); // email_status: "queued"

import os, requests

response = requests.post(
    'https://api.ujszamla.hu/api/v1/invoices/1234/send',
    headers={'Authorization': f"Bearer {os.environ['UJSZAMLA_API_KEY']}"},
    timeout=30,
)

var http = new HttpClient();
http.DefaultRequestHeaders.Authorization = new System.Net.Http.Headers.AuthenticationHeaderValue(
    "Bearer", Environment.GetEnvironmentVariable("UJSZAMLA_API_KEY"));

var response = await http.PostAsync("https://api.ujszamla.hu/api/v1/invoices/1234/send", null);

Válaszok

202A küldés sorba állítva

application/json

{
  "id": 1234,
  "invoice_number": "WEB/2026/0042",
  "recipient": "szamla@minta.hu",
  "email_status": "queued"
}

401 / 404 / 409 / 422 / 429Hibaválasz

Jogosultság, hiányzó számla, nem megfelelő állapot, hiányzó vevői e-mail vagy forgalmi korlát.

GET /api/v1/invoices/{id}/payments #

Fizetések listája

A számlához rögzített fizetések, a bruttó végösszeg, a hátralék és az is_paid jelző.

🔒 API-kulcs

Példa kérés

cURL

curl https://api.ujszamla.hu/api/v1/invoices/1234/payments \
  -H "Authorization: Bearer ujsz_..."

<?php
require 'vendor/autoload.php';

$response = (new GuzzleHttp\Client([
    'base_uri' => 'https://api.ujszamla.hu',
    'headers'  => ['Authorization' => 'Bearer ' . getenv('UJSZAMLA_API_KEY')],
]))->get('/api/v1/invoices/1234/payments');

$payments = json_decode($response->getBody()->getContents(), true);

<?php
$ch = curl_init('https://api.ujszamla.hu/api/v1/invoices/1234/payments');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . getenv('UJSZAMLA_API_KEY')],
]);
$payments = json_decode(curl_exec($ch), true);
curl_close($ch);

const response = await fetch('https://api.ujszamla.hu/api/v1/invoices/1234/payments', {
  headers: { 'Authorization': `Bearer ${process.env.UJSZAMLA_API_KEY}` },
});

const payments = await response.json();

import os, requests

response = requests.get(
    'https://api.ujszamla.hu/api/v1/invoices/1234/payments',
    headers={'Authorization': f"Bearer {os.environ['UJSZAMLA_API_KEY']}"},
    timeout=30,
)
payments = response.json()

using System.Net.Http.Json;
using System.Text.Json;

var http = new HttpClient();
http.DefaultRequestHeaders.Authorization = new System.Net.Http.Headers.AuthenticationHeaderValue(
    "Bearer", Environment.GetEnvironmentVariable("UJSZAMLA_API_KEY"));

var payments = await http.GetFromJsonAsync<JsonElement>("https://api.ujszamla.hu/api/v1/invoices/1234/payments");

Válaszok

200Fizetések listája

application/json

{
  "invoice_id": 1234,
  "gross": "63500",
  "remaining": "62500",
  "is_paid": false,
  "payments": [
    {
      "id": 11,
      "date": "2026-10-02",
      "amount": "1000",
      "payment_method_id": 1,
      "payment_identifier": null,
      "created_at": "2026-10-02T10:15:00+02:00"
    }
  ]
}

401 / 404Hibaválasz

Jogosultság vagy nem létező számla.

POST /api/v1/invoices/{id}/payments #

Fizetés rögzítése

Fizetés rögzítése a számlához; utána a számla kiegyenlítettsége frissül.

🔒 API-kulcs

Kérés törzse

Mező	Típus	Leírás
`amount`	string	Pozitív összeg (a `,` tizedesjel elfogadott). kötelező
`date`	date opc.	Elhagyva a mai nap.
`payment_method_id`	integer opc.	Elhagyva a számla fizetési módja.
`payment_identifier`	string opc.	Belső azonosító / közlemény.

Példa kérés

cURL

curl -X POST https://api.ujszamla.hu/api/v1/invoices/1234/payments \
  -H "Authorization: Bearer ujsz_..." \
  -H "Content-Type: application/json" \
  -d '{ "amount": "1000", "date": "2026-10-02", "payment_method_id": 1 }'

<?php
require 'vendor/autoload.php';

$response = (new GuzzleHttp\Client([
    'base_uri' => 'https://api.ujszamla.hu',
    'headers'  => ['Authorization' => 'Bearer ' . getenv('UJSZAMLA_API_KEY')],
]))->post('/api/v1/invoices/1234/payments', [
    'json' => ['amount' => '1000', 'date' => '2026-10-02', 'payment_method_id' => 1],
]);

$result = json_decode($response->getBody()->getContents(), true);

<?php
$payload = ['amount' => '1000', 'date' => '2026-10-02', 'payment_method_id' => 1];

$ch = curl_init('https://api.ujszamla.hu/api/v1/invoices/1234/payments');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . getenv('UJSZAMLA_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode($payload),
]);
$result = json_decode(curl_exec($ch), true);
curl_close($ch);

const response = await fetch('https://api.ujszamla.hu/api/v1/invoices/1234/payments', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.UJSZAMLA_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ amount: '1000', date: '2026-10-02', payment_method_id: 1 }),
});

const result = await response.json();

import os, requests

response = requests.post(
    'https://api.ujszamla.hu/api/v1/invoices/1234/payments',
    headers={'Authorization': f"Bearer {os.environ['UJSZAMLA_API_KEY']}"},
    json={'amount': '1000', 'date': '2026-10-02', 'payment_method_id': 1},
    timeout=30,
)

using System.Net.Http.Json;

var http = new HttpClient();
http.DefaultRequestHeaders.Authorization = new System.Net.Http.Headers.AuthenticationHeaderValue(
    "Bearer", Environment.GetEnvironmentVariable("UJSZAMLA_API_KEY"));

var request = new HttpRequestMessage(HttpMethod.Post, "https://api.ujszamla.hu/api/v1/invoices/1234/payments")
{
    Content = JsonContent.Create(new { amount = "1000", date = "2026-10-02", payment_method_id = 1 }),
};

var response = await http.SendAsync(request);

Válaszok

201A fizetés rögzítve

application/json

{
  "payment": {
    "id": 11,
    "date": "2026-10-02",
    "amount": "1000",
    "payment_method_id": 1,
    "payment_identifier": null,
    "created_at": "2026-10-02T10:15:00+02:00"
  },
  "invoice": {
    "id": 1234,
    "is_paid": false,
    "remaining": "62500"
  }
}

400 / 401 / 404 / 409 / 422 / 429Hibaválasz

Hibás összeg, jogosultság, állapotütközés vagy forgalmi korlát.

GET /api/v1/invoices/{id}/chain #

A számlalánc állapota

A root számla adatai, a cancelled jelző, az aktuális láncverzió, az effektív fejléc és tételek, valamint a láncdokumentumok.

🔒 API-kulcs

Példa kérés

cURL

curl https://api.ujszamla.hu/api/v1/invoices/1234/chain \
  -H "Authorization: Bearer ujsz_..."

<?php
require 'vendor/autoload.php';

$response = (new GuzzleHttp\Client([
    'base_uri' => 'https://api.ujszamla.hu',
    'headers'  => ['Authorization' => 'Bearer ' . getenv('UJSZAMLA_API_KEY')],
]))->get('/api/v1/invoices/1234/chain');

$chain = json_decode($response->getBody()->getContents(), true);

<?php
$ch = curl_init('https://api.ujszamla.hu/api/v1/invoices/1234/chain');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . getenv('UJSZAMLA_API_KEY')],
]);
$chain = json_decode(curl_exec($ch), true);
curl_close($ch);

const response = await fetch('https://api.ujszamla.hu/api/v1/invoices/1234/chain', {
  headers: { 'Authorization': `Bearer ${process.env.UJSZAMLA_API_KEY}` },
});

const chain = await response.json();

import os, requests

response = requests.get(
    'https://api.ujszamla.hu/api/v1/invoices/1234/chain',
    headers={'Authorization': f"Bearer {os.environ['UJSZAMLA_API_KEY']}"},
    timeout=30,
)
chain = response.json()

using System.Net.Http.Json;
using System.Text.Json;

var http = new HttpClient();
http.DefaultRequestHeaders.Authorization = new System.Net.Http.Headers.AuthenticationHeaderValue(
    "Bearer", Environment.GetEnvironmentVariable("UJSZAMLA_API_KEY"));

var chain = await http.GetFromJsonAsync<JsonElement>("https://api.ujszamla.hu/api/v1/invoices/1234/chain");

Válaszok

200A lánc állapota

application/json

{
  "root": { "id": 1234, "invoice_number": "WEB/2026/0042", "document_type": "INVOICE" },
  "cancelled": false,
  "version": 1,
  "state": {
    "header": { "note_public": null },
    "items": [
      {
        "source_invoice_item_id": 9001,
        "item_name": "Tanácsadás",
        "qty": "2",
        "qty_unit": "HOUR",
        "price_unit_net": "25000",
        "vat_id": 1
      }
    ]
  },
  "documents": [
    { "id": 1234, "invoice_number": "WEB/2026/0042", "document_type": "INVOICE", "modification_index": 0 }
  ]
}

A state.items[].source_invoice_item_id a helyesbítéshez szükséges tétel-azonosító. A version értékét kell visszaküldeni a módosító műveleteknél (based_on_modification_index).

401 / 404 / 422Hibaválasz

Jogosultság, nem létező számla vagy nem láncolható állapot.

POST /api/v1/invoices/{id}/storno #

Sztornó számla létrehozása

A root számla sztornózása; a művelet a láncot új verzióval bővíti.

🔒 API-kulcs

Kérés törzse

Mező	Típus	Leírás
`reason`	string	A sztornó indoka. kötelező
`fulfillment_date`	date opc.	Teljesítés dátuma.
`based_on_modification_index`	integer opc.	A lánc `version` értéke; elavult verzió esetén `422 CHAIN_CHANGED`.

Példa kérés

cURL

curl -X POST https://api.ujszamla.hu/api/v1/invoices/1234/storno \
  -H "Authorization: Bearer ujsz_..." \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Téves kiállítás", "fulfillment_date": "2026-10-02", "based_on_modification_index": 0 }'

<?php
require 'vendor/autoload.php';

$response = (new GuzzleHttp\Client([
    'base_uri' => 'https://api.ujszamla.hu',
    'headers'  => ['Authorization' => 'Bearer ' . getenv('UJSZAMLA_API_KEY')],
]))->post('/api/v1/invoices/1234/storno', [
    'json' => [
        'reason' => 'Téves kiállítás',
        'fulfillment_date' => '2026-10-02',
        'based_on_modification_index' => 0,
    ],
]);

$storno = json_decode($response->getBody()->getContents(), true);

<?php
$payload = [
    'reason' => 'Téves kiállítás',
    'fulfillment_date' => '2026-10-02',
    'based_on_modification_index' => 0,
];

$ch = curl_init('https://api.ujszamla.hu/api/v1/invoices/1234/storno');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . getenv('UJSZAMLA_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode($payload),
]);
$storno = json_decode(curl_exec($ch), true);
curl_close($ch);

const response = await fetch('https://api.ujszamla.hu/api/v1/invoices/1234/storno', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.UJSZAMLA_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    reason: 'Téves kiállítás',
    fulfillment_date: '2026-10-02',
    based_on_modification_index: 0,
  }),
});

const storno = await response.json();

import os, requests

response = requests.post(
    'https://api.ujszamla.hu/api/v1/invoices/1234/storno',
    headers={'Authorization': f"Bearer {os.environ['UJSZAMLA_API_KEY']}"},
    json={
        'reason': 'Téves kiállítás',
        'fulfillment_date': '2026-10-02',
        'based_on_modification_index': 0,
    },
    timeout=30,
)

using System.Net.Http.Json;

var http = new HttpClient();
http.DefaultRequestHeaders.Authorization = new System.Net.Http.Headers.AuthenticationHeaderValue(
    "Bearer", Environment.GetEnvironmentVariable("UJSZAMLA_API_KEY"));

var request = new HttpRequestMessage(HttpMethod.Post, "https://api.ujszamla.hu/api/v1/invoices/1234/storno")
{
    Content = JsonContent.Create(new
    {
        reason = "Téves kiállítás",
        fulfillment_date = "2026-10-02",
        based_on_modification_index = 0,
    }),
};

var response = await http.SendAsync(request);

Válaszok

201A sztornó számla létrejött

Válasz: Invoice séma (lásd a 201 példát).

400 / 401 / 404 / 409 / 422 / 429Hibaválasz

Tipikusan 422 CHAIN_CHANGED vagy 422 CHAIN_CANCELLED.

POST /api/v1/invoices/{id}/corrections #

Helyesbítő számla létrehozása

A javított fejléc és tételek alapján helyesbítő dokumentumot hoz létre a láncon.

🔒 API-kulcs

Kérés törzse

Mező	Típus	Leírás
`based_on_modification_index`	integer	A lánc `version` értéke. kötelező
`reason`	string	A helyesbítés indoka. kötelező
`confirmed`	boolean	Alapérték: `false`.
`header`	object opc.	Módosított fejlécmezők (pl. `note_public`).
`items[]`	array opc.	Módosított tételek; a `source_invoice_item_id` a lánc állapotából.

Példa kérés

cURL

curl -X POST https://api.ujszamla.hu/api/v1/invoices/1234/corrections \
  -H "Authorization: Bearer ujsz_..." \
  -H "Content-Type: application/json" \
  -d '{
    "based_on_modification_index": 0,
    "reason": "Megjegyzés javítása",
    "confirmed": true,
    "header": { "note_public": "Javított megjegyzés" },
    "items": [
      { "source_invoice_item_id": 9001, "item_name": "Tanácsadás", "qty": "2", "qty_unit": "HOUR", "price_unit_net": "25000", "vat_id": 1 }
    ]
  }'

<?php
require 'vendor/autoload.php';

$response = (new GuzzleHttp\Client([
    'base_uri' => 'https://api.ujszamla.hu',
    'headers'  => ['Authorization' => 'Bearer ' . getenv('UJSZAMLA_API_KEY')],
]))->post('/api/v1/invoices/1234/corrections', [
    'json' => [
        'based_on_modification_index' => 0,
        'reason'    => 'Megjegyzés javítása',
        'confirmed' => true,
        'header'    => ['note_public' => 'Javított megjegyzés'],
        'items'     => [[
            'source_invoice_item_id' => 9001,
            'item_name'      => 'Tanácsadás',
            'qty'            => '2',
            'qty_unit'       => 'HOUR',
            'price_unit_net' => '25000',
            'vat_id'         => 1,
        ]],
    ],
]);

$correction = json_decode($response->getBody()->getContents(), true);

<?php
$payload = [
    'based_on_modification_index' => 0,
    'reason'    => 'Megjegyzés javítása',
    'confirmed' => true,
    'header'    => ['note_public' => 'Javított megjegyzés'],
    'items'     => [[
        'source_invoice_item_id' => 9001,
        'item_name'      => 'Tanácsadás',
        'qty'            => '2',
        'qty_unit'       => 'HOUR',
        'price_unit_net' => '25000',
        'vat_id'         => 1,
    ]],
];

$ch = curl_init('https://api.ujszamla.hu/api/v1/invoices/1234/corrections');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . getenv('UJSZAMLA_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode($payload),
]);
$correction = json_decode(curl_exec($ch), true);
curl_close($ch);

const response = await fetch('https://api.ujszamla.hu/api/v1/invoices/1234/corrections', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.UJSZAMLA_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    based_on_modification_index: 0,
    reason: 'Megjegyzés javítása',
    confirmed: true,
    header: { note_public: 'Javított megjegyzés' },
    items: [
      { source_invoice_item_id: 9001, item_name: 'Tanácsadás', qty: '2', qty_unit: 'HOUR', price_unit_net: '25000', vat_id: 1 },
    ],
  }),
});

const correction = await response.json();

import os, requests

response = requests.post(
    'https://api.ujszamla.hu/api/v1/invoices/1234/corrections',
    headers={'Authorization': f"Bearer {os.environ['UJSZAMLA_API_KEY']}"},
    json={
        'based_on_modification_index': 0,
        'reason': 'Megjegyzés javítása',
        'confirmed': True,
        'header': {'note_public': 'Javított megjegyzés'},
        'items': [{
            'source_invoice_item_id': 9001,
            'item_name': 'Tanácsadás', 'qty': '2', 'qty_unit': 'HOUR',
            'price_unit_net': '25000', 'vat_id': 1,
        }],
    },
    timeout=30,
)

using System.Net.Http.Json;

var http = new HttpClient();
http.DefaultRequestHeaders.Authorization = new System.Net.Http.Headers.AuthenticationHeaderValue(
    "Bearer", Environment.GetEnvironmentVariable("UJSZAMLA_API_KEY"));

var request = new HttpRequestMessage(HttpMethod.Post, "https://api.ujszamla.hu/api/v1/invoices/1234/corrections")
{
    Content = JsonContent.Create(new
    {
        based_on_modification_index = 0,
        reason = "Megjegyzés javítása",
        confirmed = true,
        header = new { note_public = "Javított megjegyzés" },
        items = new[]
        {
            new { source_invoice_item_id = 9001, item_name = "Tanácsadás", qty = "2", qty_unit = "HOUR", price_unit_net = "25000", vat_id = 1 },
        },
    }),
};

var response = await http.SendAsync(request);

Válaszok

201A helyesbítő számla létrejött

Válasz: Invoice séma (lásd a 201 példát).

400 / 401 / 404 / 409 / 422 / 429Hibaválasz

Tipikusan 422 CHAIN_CHANGED vagy 422 NO_CHANGE.

SYSTEM

Állapotellenőrzés

GET /api/v1/ping #

Állapotellenőrzés

Nem igényel kulcsot – jó első kapcsolatpróbának.

Nyilvános

Példa kérés

cURL

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

<?php
require 'vendor/autoload.php';

$response = (new GuzzleHttp\Client(['base_uri' => 'https://api.ujszamla.hu']))
    ->get('/api/v1/ping');

$status = json_decode($response->getBody()->getContents(), true);

<?php
$ch = curl_init('https://api.ujszamla.hu/api/v1/ping');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$status = json_decode(curl_exec($ch), true);
curl_close($ch);

const response = await fetch('https://api.ujszamla.hu/api/v1/ping');
const status = await response.json();

import requests

status = requests.get('https://api.ujszamla.hu/api/v1/ping', timeout=30).json()

using System.Net.Http.Json;
using System.Text.Json;

var http = new HttpClient();
var status = await http.GetFromJsonAsync<JsonElement>("https://api.ujszamla.hu/api/v1/ping");

Válaszok

200A szolgáltatás elérhető

application/json

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

SÉMÁK

Modellek

A válaszokban visszaadott objektumok mezői. A kérések sémáit az egyes végpontoknál találod.

Invoice

Mező	Típus	Leírás
`id`	integer	Belső számlaazonosító.
`invoice_number`	string	Kiállított számlaszám (pl. `WEB/2026/0042`).
`document_type`	string	`INVOICE` / `PROFORMA` / `ADVANCE`.
`external_id`	string	A külső rendszer azonosítója.
`status`	enum	`draft` \| `finalized`.
`issued_at`	date	Kiállítás dátuma.
`fulfillment_date`	date	Teljesítés dátuma.
`payment_deadline`	date	Fizetési határidő.
`currency`	string	Pénznem (pl. `HUF`).
`totals.net / vat / gross`	string	Összegek.
`email_status`	string	`not_requested` \| `queued` \| `failed`.
`nav_status`	string	NAV-adatszolgáltatás állapota.
`pdf_available`	boolean	Elérhető-e a PDF.
`idempotent_replay`	boolean	Korábbi kérés eredményének visszaadása.

Payment

Mező	Típus	Leírás
`id`	integer	Fizetés azonosítója.
`date`	date	Fizetés dátuma.
`amount`	string	Összeg.
`payment_method_id`	integer	Fizetési mód azonosítója.
`payment_identifier`	string	Belső azonosító / közlemény.
`created_at`	string	Rögzítés időpontja.

Error

Mező	Típus	Leírás
`type`	enum	`authentication_error`, `invalid_request`, `validation_error`, `not_found`, `conflict`, `rate_limit_error`, `server_error`.
`code`	string	Stabil hibakód (pl. `INVOICE_VALIDATION_FAILED`).
`message`	string	Emberi üzenet.
`request_id`	string	Kérés-azonosító (megegyezik az `X-Request-Id` fejléccel).
`errors[]`	array	`code`, `path`, `message`.

application/json

{
  "type": "validation_error",
  "code": "INVOICE_VALIDATION_FAILED",
  "message": "A számla adatai nem megfelelőek.",
  "request_id": "req_1a2b3c4d5e6f",
  "errors": [
    {
      "code": "DOCUMENT_BLOCK_REQUIRED",
      "path": "document_block",
      "message": "A számlatömb megadása kötelező."
    }
  ]
}

A további modellek (PaymentList, SendResult, ChainState, CreateInvoiceRequest, StornoRequest, CorrectionRequest) a nyers openapi.yaml-ban és a végpontok válaszpéldáiban szerepelnek.