# Fiscon dokumentáció

> A Fiscon API teljes dokumentációja egyetlen Markdown fájlban, AI-ügynökök és nyelvi modellek számára.

---

Forrás: https://fiscon.hu/dokumentacio/bevezetes

# Bevezetés

 A Fiscon API-ja lehetővé teszi, hogy a pénztárgépes/kasszarendszered a NAV gépi nyugtaadat-szolgáltatás felé jelentendő nyugtaadatokat egyszerű JSON végpontokon keresztül küldje be, a NAV-integráció (hitelesítés, XML-generálás, napi jelentés-aggregáció, beküldés) minden részletét a Fiscon kezeli helyetted.

 
## Alap URL

 Minden API-kérést a dedikált API aldomainre kell küldeni, verziózott előtaggal:

 ```bash
https://api.fiscon.hu/v1
```

 A sandbox környezetben ehelyett a `sandbox.` aldomaint kell használni — lásd lent a [Környezetek](#kornyezetek) szakaszt. A használt aldomainnek mindig egyeznie kell az API-kulcsod környezetével: egy éles kulcs csak az `api.`, egy sandbox kulcs csak a `sandbox.` aldomainen fogadott el, ellenkező esetben a kérés `401 UNAUTHENTICATED` hibával elutasításra kerül.

 
## Kérés és válasz formátum

 Minden kérés törzsét és minden választ `application/json` formátumban küldünk/fogadunk. A sikeres válaszok a kért erőforrást (vagy erőforrás-listát) adják vissza, a hibák pedig egységes hibaborítékban érkeznek — lásd a [Hibakezelés](https://fiscon.hu/dokumentacio/hibakezeles) oldalt.

 Minden válasz (sikeres és hibás egyaránt) tartalmaz egy egyedi kérés-azonosítót is: sikeres válaszoknál az `X-Request-Id` fejlécben, hibás válaszoknál emellett a hibaboríték `request_id` mezőjében is. Támogatási megkeresésnél mindig add meg ezt az azonosítót.

 
## Lapozás

 A listázó végpontok (`GET /v1/receipts`, `/v1/taxpayers`, `/v1/reports`, `/v1/submissions`, `/v1/webhooks`, `/v1/events`) minden esetben a `limit` lekérdezési paramétert fogadják el az oldalméret beállítására (alapértelmezett: 25, maximum: 100). Nincs `per_page` alias.

 A `/v1/receipts` végpont oldalankénti (offset alapú) lapozást használ, a `page` paraméterrel:

 ```json
{
    "data": [ /* ... */ ],
    "links": { "first": null, "last": null, "prev": null, "next": "https://api.fiscon.hu/v1/receipts?page=2" },
    "meta": { "current_page": 1, "from": 1, "path": "https://api.fiscon.hu/v1/receipts", "per_page": 25, "to": 25 }
}
```

 Minden más listázó végpont (`taxpayers`, `reports`, `submissions`, `webhooks`, `events`) kurzor alapú lapozást használ — nincs `total`/`last_page` mező, a következő oldalt a `links.next` URL-en (vagy a `cursor` paraméterrel) kell lekérni:

 ```json
{
    "data": [ /* ... */ ],
    "links": { "first": null, "last": null, "prev": null, "next": "https://api.fiscon.hu/v1/taxpayers?cursor=eyJpZCI6NDJ9" },
    "meta": { "path": "https://api.fiscon.hu/v1/taxpayers", "per_page": 25, "next_cursor": "eyJpZCI6NDJ9", "prev_cursor": null }
}
```

 
## Sebességkorlátozás (rate limiting)

 A limit API-kulcsonként érvényes, mértéke pedig a szervezeted csomagjától függ:

 | Csomag | Limit |
| --- | --- |
| Starter | 60 kérés/perc |
| Business | 180 kérés/perc |
| Platform | 600 kérés/perc |

 A limit túllépésekor a kérés `429` státuszkóddal és `RATE_LIMITED` hibakóddal tér vissza, a válasz pedig a szokásos `X-RateLimit-Limit`/`X-RateLimit-Remaining` és `Retry-After` fejléceket is tartalmazza — ez utóbbi adja meg másodpercben, mennyit kell várni az újrapróbálkozás előtt. A csomagod aktuális kereteit és felhasználását az admin felület **Előfizetés** oldalán tekintheted meg.

 
## Környezetek

 Minden API-kulcs vagy **éles (live)**, vagy **sandbox** környezethez tartozik, és ez a hozzárendelés véglegesen rögzített a kulcs aldomainjéhez:

 | Környezet | Aldomain | Kulcs előtag | Viselkedés |
| --- | --- | --- | --- |
| Éles (live) | `api.fiscon.hu` | `fis_live_...` | Valós NAV adatszolgáltatás történik. |
| Sandbox | `sandbox.fiscon.hu` | `fis_sandbox_...` | A NAV-hívások szimuláltak, semmilyen valós adatszolgáltatás nem történik. |

 A sandbox környezetben az admin felület **Sandbox tesztelés** oldalán szabadon kiválaszthatod, hogy a NAV milyen válasszal reagáljon (elfogadás, elutasítás, hitelesítési hiba stb.), így a hibakezelő logikádat is tesztelheted anélkül, hogy valós adatot küldenél be.

 
## Következő lépés

 Kezdd a [Hitelesítés](https://fiscon.hu/dokumentacio/hitelesites) oldallal, hogy megtudd, hogyan kell az API-kulcsodat a kérésekhez csatolni.


---

Forrás: https://fiscon.hu/dokumentacio/hitelesites

# Hitelesítés

 Az API minden kérését Bearer tokennel kell hitelesíteni, az admin felületen generált API-kulccsal.

 
## API-kulcs formátuma

 Egy API-kulcs mindig a következő alakú:

 ```bash
fis_{live|sandbox}_<secret>
```

 Az előtag (`fis_live_` vagy `fis_sandbox_`) határozza meg, hogy a kulcs melyik környezethez tartozik. Ez a besorolás nem módosítható utólag — ha másik környezethez van szükséged, generálj egy új kulcsot.

 A kulcs egy szervezet (organization) egészéhez tartozik, nem egyetlen adóalanyhoz — egy kulccsal a szervezet összes adóalanyának adatai elérhetők. Ha adóalanyonként szeretnéd elkülöníteni a hozzáférést, hozz létre külön szervezetet adóalanyonként.

 A titkos érték (secret) csak létrehozáskor jelenik meg egyszer, visszafejtve tárolva sosem kérdezhető le újra — a Fiscon csak a hash-elt értéket tárolja. Ha elveszik, vonj vissza egy kulcsot és generálj helyette újat.

 
## Kérés hitelesítése

 Csatold a kulcsot minden kérés `Authorization` fejlécében:

    cURL   PHP   Laravel   JavaScript    ```bash
curl https://api.fiscon.hu/v1/receipts \
    -H "Authorization: Bearer fis_live_xxxxxxxxxxxxxxxx"
```

   ```php
$curl = curl_init('https://api.fiscon.hu/v1/receipts');

curl_setopt_array($curl, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer fis_live_xxxxxxxxxxxxxxxx',
    ],
]);

$response = curl_exec($curl);
curl_close($curl);
```

   ```php
use Illuminate\Support\Facades\Http;

$response = Http::withToken(config('services.fiscon.key'))
    ->get('https://api.fiscon.hu/v1/receipts');

$receipts = $response->json();
```

   ```javascript
const response = await fetch('https://api.fiscon.hu/v1/receipts', {
    headers: {
        Authorization: 'Bearer fis_live_xxxxxxxxxxxxxxxx',
    },
});

const receipts = await response.json();
```

   
## Aldomain és környezet egyezése

 A kulcs környezete rögzíti, melyik aldomainen fogadható el: egy `fis_live_...` kulcs csak az `api.fiscon.hu`, egy `fis_sandbox_...` kulcs csak a `sandbox.fiscon.hu` host felé küldött kérésekben érvényes. Ha a kettő nem egyezik, a kérés `401 UNAUTHENTICATED` hibával elutasításra kerül, még akkor is, ha maga a kulcs egyébként érvényes — ez a leggyakoribb hiba sandbox-integráció közben.

 
## Érvénytelen vagy hiányzó kulcs

 A kérés `401 UNAUTHENTICATED` választ kap az egységes hibaborítékban a következő esetekben:

 - Az `Authorization` fejléc hiányzik, vagy nem `Bearer fis_live_...`/`fis_sandbox_...` formátumú.
- A kulcs nem létezik (törölve vagy elgépelve).
- A kulcs vissza lett vonva (`revoked_at` ki van töltve).
- A kulcsnak lejárati dátuma van, és az már elmúlt.
- A kulcs környezete nem egyezik a hívott aldomainnel — lásd fent.

 Lásd a [Hibakezelés](https://fiscon.hu/dokumentacio/hibakezeles) oldalt a teljes hibaboríték formátumáért.

 
## Kulcskezelés

 Az API-kulcsokat az admin felület **API kulcsok** oldalán hozhatod létre, tekintheted meg és vonhatod vissza. Egy kulcs titkos értékét csak létrehozáskor mutatjuk meg egyszer — utána csak az előtag és az utolsó néhány karakter látható.

 Minden kulcshoz opcionálisan lejárati dátum is beállítható; lejárat után a kulcs automatikusan érvénytelenné válik, visszavonás nélkül is. A kulcs utolsó használatának időpontját (`last_used_at`) minden sikeres hitelesített kérés frissíti — ez segít beazonosítani a már nem használt, biztonságosan visszavonható kulcsokat.


---

Forrás: https://fiscon.hu/dokumentacio/hibakezeles

# Hibakezelés

 Minden hibás válasz egységes JSON borítékban érkezik, hogy a kliens kódod egyetlen helyen tudja feldolgozni a hibákat.

 
## Hibaboríték

 ```json
{
    "error": {
        "code": "VALIDATION_FAILED",
        "message": "A megadott adatok érvénytelenek.",
        "details": [
            {
                "field": "totals.0.vat_category",
                "code": "INVALID_VALUE",
                "message": "A megadott vat_category formátuma érvénytelen."
            }
        ],
        "request_id": "req_01hz3k9c8v0000000000000000"
    }
}
```

 
## Mezők

 | Mező | Leírás |
| --- | --- |
| `code` | Gépileg feldolgozható hibakód (lásd lent). |
| `message` | Emberi olvasásra szánt hibaüzenet. |
| `details` | Mezőszintű validációs hibák listája (`field`, `code`, `message` hármasokkal), vagy `null`, ha nem releváns. |
| `request_id` | Egyedi kérés-azonosító, ugyanaz mint a válasz `X-Request-Id` fejléce — hibajelentésnél mindig ezt add meg. |

 
## Hibakódok

 | HTTP státusz | Kód | Jelentés |
| --- | --- | --- |
| 401 | `UNAUTHENTICATED` | Hiányzó, érvénytelen, visszavont, lejárt API-kulcs, vagy a kulcs környezete nem egyezik a hívott aldomainnel — lásd [Hitelesítés](https://fiscon.hu/dokumentacio/hitelesites). |
| 403 | `FORBIDDEN` | A kulcs érvényes, de nincs jogosultsága a művelethez. |
| 403 | `PLAN_LIMIT_EXCEEDED` | A szervezeted csomagja szerinti keret betelt (pl. aktív adóalanyok száma vagy a havi nyugtakvóta) — válts magasabb csomagra az admin felület **Előfizetés** oldalán. |
| 404 | `RESOURCE_NOT_FOUND` | A hivatkozott erőforrás nem létezik ebben a szervezetben/környezetben. |
| 422 | `VALIDATION_FAILED` | A kérés törzse nem felel meg a validációs szabályoknak — lásd `details`. |
| 422 | `TAXPAYER_NOT_FOUND` | A hivatkozott `taxpayer_id` nem létezik vagy nem ehhez a szervezethez tartozik. |
| 422 | `CREDENTIALS_NOT_CONFIGURED` | Az adóalanyhoz még nincs NAV hitelesítő adat beállítva — lásd [Adóalanyok](https://fiscon.hu/dokumentacio/adoalanyok). |
| 422 | `CREDENTIALS_INVALID` | A beállított NAV hitelesítő adatok érvénytelenek. |
| 409 | `RECEIPT_ALREADY_AGGREGATED` | A nyugta már bekerült egy jelentésbe, a művelet már nem hajtható végre rajta. |
| 409 | `TAXPAYER_HAS_RECEIPTS` | Az adóalany nem törölhető, mert már tartoznak hozzá nyugták vagy jelentések. |
| 409 | `REPORT_NOT_READY` | A jelentés még nincs olyan állapotban, hogy a művelet elvégezhető legyen rajta. |
| 409 | `REPORT_ALREADY_SUBMITTED` | A jelentés már be lett küldve a NAV felé. |
| 409 | `REPORT_NOT_INVALIDATABLE` | A jelentés jelenlegi állapotában nem érvényteleníthető — lásd [Jelentések](https://fiscon.hu/dokumentacio/jelentesek). |
| 409 | `IDEMPOTENCY_CONFLICT` | Ugyanazzal az `Idempotency-Key`-jel, de eltérő kérés-törzzsel érkezett a kérés — lásd [Idempotencia](https://fiscon.hu/dokumentacio/idempotencia). |
| 429 | `RATE_LIMITED` | Túl sok kérés — próbáld újra a `Retry-After` fejlécben jelzett idő után. |
| 500 | `INTERNAL_ERROR` | Váratlan szerverhiba. Ha ismétlődik, jelezd a `request_id` megadásával. |

 
## NAV- és feldolgozási hibák

 A következő kódok a NAV felé történő háttér-feldolgozás során felmerülő hibákat jelölik. Ezek nem egy konkrét API-hívás válaszában jelennek meg, hanem a kapcsolódó [jelentés](https://fiscon.hu/dokumentacio/jelentesek) vagy [beküldés](https://fiscon.hu/dokumentacio/bekuldesek) `status`/hibamezőin, illetve [webhook eseményeken](https://fiscon.hu/dokumentacio/webhookok) keresztül kérdezhetők le:

 | Kód | Jelentés |
| --- | --- |
| `NAV_AUTHENTICATION_FAILED` | A NAV elutasította a technikai felhasználó hitelesítését. |
| `NAV_SCHEMA_VALIDATION_FAILED` | A NAV felé küldött XML nem felel meg a NAV séma-elvárásainak. |
| `NAV_SUBMISSION_REJECTED` | A NAV üzleti szabály alapján elutasította az adatszolgáltatást. |
| `UPSTREAM_UNAVAILABLE` | A NAV rendszere átmenetileg nem elérhető. |
| `UPSTREAM_TIMEOUT` | A NAV rendszere nem válaszolt időben. |
| `UPSTREAM_INVALID_RESPONSE` | A NAV rendszere értelmezhetetlen választ adott. |


---

Forrás: https://fiscon.hu/dokumentacio/idempotencia

# Idempotencia

 Nyugta beküldésekor hálózati hiba esetén biztonságosan újrapróbálkozhatsz anélkül, hogy véletlenül duplikált nyugtát hoznál létre.

 
## Idempotency-Key fejléc

 A `POST /v1/receipts` végpont kötelezően megköveteli az `Idempotency-Key` fejlécet — egy általad generált, kérésenként egyedi azonosítót (pl. UUID):

    cURL   PHP   Laravel   JavaScript    ```bash
curl -X POST https://api.fiscon.hu/v1/receipts \
    -H "Authorization: Bearer fis_live_xxxxxxxxxxxxxxxx" \
    -H "Idempotency-Key: 6f1e2c2a-2a3b-4d3e-9c1a-8b2f6e6c2b21" \
    -H "Content-Type: application/json" \
    -d '{ "...": "..." }'
```

   ```php
$curl = curl_init('https://api.fiscon.hu/v1/receipts');

curl_setopt_array($curl, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode(['...' => '...']),
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer fis_live_xxxxxxxxxxxxxxxx',
        'Idempotency-Key: '.Str::uuid(),
        'Content-Type: application/json',
    ],
]);

$response = curl_exec($curl);
curl_close($curl);
```

   ```php
use Illuminate\Support\Facades\Http;
use Illuminate\Support\Str;

$response = Http::withToken(config('services.fiscon.key'))
    ->withHeader('Idempotency-Key', (string) Str::uuid())
    ->post('https://api.fiscon.hu/v1/receipts', [
        // ...
    ]);
```

   ```javascript
const response = await fetch('https://api.fiscon.hu/v1/receipts', {
    method: 'POST',
    headers: {
        Authorization: 'Bearer fis_live_xxxxxxxxxxxxxxxx',
        'Idempotency-Key': crypto.randomUUID(),
        'Content-Type': 'application/json',
    },
    body: JSON.stringify({ /* ... */ }),
});
```

   
## Viselkedés

 - Ugyanazzal a kulccsal és **ugyanazzal** a kérés-törzzsel érkező ismételt kérés az eredeti válasszal tér vissza, új nyugta létrehozása nélkül.
- Ugyanazzal a kulccsal, de **eltérő** kérés-törzzsel érkező kérés `409 IDEMPOTENCY_CONFLICT` hibát ad.
- A kulcs hatóköre szervezet + környezet + végpont + kulcs kombinációra vonatkozik — más szervezet vagy környezet ugyanazt a kulcsot újra felhasználhatja.
- Az `Idempotency-Key` fejléc jelenleg csak a `POST /v1/receipts` végponton kötelező; hiányában a kérés `422 VALIDATION_FAILED` hibát ad.
- Egy idempotencia-rekord **24 óráig** érvényes a létrehozásától számítva. Ezután ugyanaz a kulcs újra felhasználható, és egy új, önálló nyugtát fog létrehozni.

 
## Javaslat

 Generálj egy új, egyedi `Idempotency-Key`-t minden logikai nyugta-beküldési kísérlethez (pl. egy fizikai tranzakcióhoz), és hálózati hiba vagy időtúllépés esetén ugyanazzal a kulccsal próbálkozz újra. Ne generálj új kulcsot minden újrapróbálkozáshoz — az pont a duplikáció-védelem célját hiúsítaná meg.


---

Forrás: https://fiscon.hu/dokumentacio/nyugtak

# Nyugták

 A nyugta végpontok kezelik a NAV felé jelentendő nyugtaadatokat. A beküldött nyugták a háttérben napi jelentésekbe ([Report](https://fiscon.hu/dokumentacio/jelentesek)) aggregálódnak, amelyeket a Fiscon küld be a NAV-nak.

 
## Nyugta létrehozása

    cURL   PHP   Laravel   JavaScript    ```bash
curl -X POST https://api.fiscon.hu/v1/receipts \
    -H "Authorization: Bearer fis_live_xxxxxxxxxxxxxxxx" \
    -H "Idempotency-Key: 6f1e2c2a-2a3b-4d3e-9c1a-8b2f6e6c2b21" \
    -H "Content-Type: application/json" \
    -d '{
        "external_id": "pos-2026-000123",
        "taxpayer_id": "txp_01hz3k9c8v0000000000000000",
        "receipt_number": "A/2026/00042",
        "series": "A",
        "document_type": "sale_document",
        "issued_at": "2026-09-02T14:30:00+02:00",
        "currency": "HUF",
        "totals": [
            { "vat_category": "27%", "gross": "1270.00" },
            { "vat_category": "AAM", "gross": "500.00" }
        ]
    }'
```

   ```php
$payload = [
    'external_id' => 'pos-2026-000123',
    'taxpayer_id' => 'txp_01hz3k9c8v0000000000000000',
    'receipt_number' => 'A/2026/00042',
    'series' => 'A',
    'document_type' => 'sale_document',
    'issued_at' => '2026-09-02T14:30:00+02:00',
    'currency' => 'HUF',
    'totals' => [
        ['vat_category' => '27%', 'gross' => '1270.00'],
        ['vat_category' => 'AAM', 'gross' => '500.00'],
    ],
];

$curl = curl_init('https://api.fiscon.hu/v1/receipts');

curl_setopt_array($curl, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode($payload),
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer fis_live_xxxxxxxxxxxxxxxx',
        'Idempotency-Key: 6f1e2c2a-2a3b-4d3e-9c1a-8b2f6e6c2b21',
        'Content-Type: application/json',
    ],
]);

$response = curl_exec($curl);
curl_close($curl);
```

   ```php
use Illuminate\Support\Facades\Http;
use Illuminate\Support\Str;

$response = Http::withToken(config('services.fiscon.key'))
    ->withHeader('Idempotency-Key', (string) Str::uuid())
    ->post('https://api.fiscon.hu/v1/receipts', [
        'external_id' => 'pos-2026-000123',
        'taxpayer_id' => 'txp_01hz3k9c8v0000000000000000',
        'receipt_number' => 'A/2026/00042',
        'series' => 'A',
        'document_type' => 'sale_document',
        'issued_at' => '2026-09-02T14:30:00+02:00',
        'currency' => 'HUF',
        'totals' => [
            ['vat_category' => '27%', 'gross' => '1270.00'],
            ['vat_category' => 'AAM', 'gross' => '500.00'],
        ],
    ]);

$receipt = $response->json();
```

   ```javascript
const response = await fetch('https://api.fiscon.hu/v1/receipts', {
    method: 'POST',
    headers: {
        Authorization: 'Bearer fis_live_xxxxxxxxxxxxxxxx',
        'Idempotency-Key': crypto.randomUUID(),
        'Content-Type': 'application/json',
    },
    body: JSON.stringify({
        external_id: 'pos-2026-000123',
        taxpayer_id: 'txp_01hz3k9c8v0000000000000000',
        receipt_number: 'A/2026/00042',
        series: 'A',
        document_type: 'sale_document',
        issued_at: '2026-09-02T14:30:00+02:00',
        currency: 'HUF',
        totals: [
            { vat_category: '27%', gross: '1270.00' },
            { vat_category: 'AAM', gross: '500.00' },
        ],
    }),
});

const receipt = await response.json();
```

   
### Mezők

 | Mező | Kötelező | Leírás |
| --- | --- | --- |
| `external_id` | igen | A te rendszered szerinti egyedi azonosító, max. 255 karakter. |
| `taxpayer_id` | igen | A nyugtát kibocsátó adóalany nyilvános azonosítója (`txp_...`), a szervezetedhez kell tartoznia. |
| `receipt_number` | igen | A nyugta sorszáma, max. 255 karakter. |
| `series` | nem | Nyugtasorozat kódja, max. 255 karakter. |
| `document_type` | nem | `sale_document` vagy `modifying_document`. Alapértelmezett: `sale_document`. |
| `issued_at` | igen | A nyugta kiállításának időpontja, ISO 8601 formátumban. |
| `currency` | igen | Pénznem-kód: `HUF`, `EUR` vagy `USD`. |
| `totals` | igen | ÁFA-kategóriánkénti bruttó összesítők listája, legalább 1 elemmel. Nincs felső korlát az elemszámra. |
| `totals[].vat_category` | igen | Max. 50 karakter, az adóalanyhoz szinkronizált NAV ÁFA-kategóriák egyike — lásd [Adóalanyok](https://fiscon.hu/dokumentacio/adoalanyok). |
| `totals[].gross` | igen | Bruttó összeg számként (stringként is elfogadva). |

 A végpont az [Idempotency-Key](https://fiscon.hu/dokumentacio/idempotencia) fejlécet kötelezően megköveteli.

 A havonta beküldhető nyugták száma a szervezeted csomagjától függően korlátozott (Starter: 10 000, Business: 100 000, Platform: korlátlan). A keret betelte esetén a kérés `403` státusszal és `PLAN_LIMIT_EXCEEDED` hibakóddal tér vissza — lásd [Hibakezelés](https://fiscon.hu/dokumentacio/hibakezeles).

 
## Válasz

 ```json
{
    "id": "rcp_01hz3k9c8v0000000000000000",
    "external_id": "pos-2026-000123",
    "status": "received",
    "created_at": "2026-09-02T14:30:05+02:00"
}
```

 
### Állapotok (status)

 | Érték | Jelentés |
| --- | --- |
| `received` | A nyugta beérkezett, feldolgozásra vár. |
| `validated` | A nyugta adatai ellenőrizve lettek. |
| `ready` | A nyugta készen áll rá, hogy bekerüljön egy napi jelentésbe. |
| `aggregated` | A nyugta bekerült egy [jelentésbe](https://fiscon.hu/dokumentacio/jelentesek) — ettől kezdve a nyugta már nem módosítható. |
| `invalid` | A nyugta adatai érvénytelenek, nem kerül bele jelentésbe. |

 
## Nyugták listázása

 A lista `taxpayer_id` és `status` szerint szűrhető, és oldalankénti (offset alapú) lapozást használ a `page` és `limit` paraméterekkel — lásd a [Lapozás](https://fiscon.hu/dokumentacio/bevezetes#lapozas) szakaszt a `meta`/`links` mezők leírásáért.

 ```bash
GET /v1/receipts?taxpayer_id=txp_01hz3k9c8v0000000000000000&status=aggregated&limit=50&page=2
```

    cURL   PHP   Laravel   JavaScript    ```bash
curl https://api.fiscon.hu/v1/receipts \
    -H "Authorization: Bearer fis_live_xxxxxxxxxxxxxxxx"
```

   ```php
$curl = curl_init('https://api.fiscon.hu/v1/receipts');

curl_setopt_array($curl, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer fis_live_xxxxxxxxxxxxxxxx',
    ],
]);

$response = curl_exec($curl);
curl_close($curl);
```

   ```php
use Illuminate\Support\Facades\Http;

$receipts = Http::withToken(config('services.fiscon.key'))
    ->get('https://api.fiscon.hu/v1/receipts')
    ->json();
```

   ```javascript
const response = await fetch('https://api.fiscon.hu/v1/receipts', {
    headers: {
        Authorization: 'Bearer fis_live_xxxxxxxxxxxxxxxx',
    },
});

const receipts = await response.json();
```


---

Forrás: https://fiscon.hu/dokumentacio/adoalanyok

# Adóalanyok

 Egy adóalany (taxpayer) egy NAV felé adatszolgáltatásra kötelezett vállalkozást képvisel. Minden nyugtát egy adóalanyhoz kell rendelni, és a NAV hitelesítő adatokat is adóalany-szinten tároljuk.

 
## Adóalany létrehozása

    cURL   PHP   Laravel   JavaScript    ```bash
curl -X POST https://api.fiscon.hu/v1/taxpayers \
    -H "Authorization: Bearer fis_live_xxxxxxxxxxxxxxxx" \
    -H "Content-Type: application/json" \
    -d '{
        "name": "Példa Kereskedelmi Kft.",
        "tax_number": "12345678-2-42",
        "country_code": "HU"
    }'
```

   ```php
$curl = curl_init('https://api.fiscon.hu/v1/taxpayers');

curl_setopt_array($curl, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode([
        'name' => 'Példa Kereskedelmi Kft.',
        'tax_number' => '12345678-2-42',
        'country_code' => 'HU',
    ]),
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer fis_live_xxxxxxxxxxxxxxxx',
        'Content-Type: application/json',
    ],
]);

$response = curl_exec($curl);
curl_close($curl);
```

   ```php
use Illuminate\Support\Facades\Http;

$taxpayer = Http::withToken(config('services.fiscon.key'))
    ->post('https://api.fiscon.hu/v1/taxpayers', [
        'name' => 'Példa Kereskedelmi Kft.',
        'tax_number' => '12345678-2-42',
        'country_code' => 'HU',
    ])
    ->json();
```

   ```javascript
const response = await fetch('https://api.fiscon.hu/v1/taxpayers', {
    method: 'POST',
    headers: {
        Authorization: 'Bearer fis_live_xxxxxxxxxxxxxxxx',
        'Content-Type': 'application/json',
    },
    body: JSON.stringify({
        name: 'Példa Kereskedelmi Kft.',
        tax_number: '12345678-2-42',
        country_code: 'HU',
    }),
});

const taxpayer = await response.json();
```

   Az aktív adóalanyok száma a szervezeted csomagjától függően korlátozott (Starter: 1, Business: 5, Platform: korlátlan). A keret betelte esetén a kérés `403` státusszal és `PLAN_LIMIT_EXCEEDED` hibakóddal tér vissza — lásd [Hibakezelés](https://fiscon.hu/dokumentacio/hibakezeles).

 
## Válasz

 ```json
{
    "id": "txp_01hz3k9c8v0000000000000000",
    "name": "Példa Kereskedelmi Kft.",
    "tax_number": "12345678-2-42",
    "country_code": "HU",
    "status": "active",
    "created_at": "2026-09-02T14:00:00+02:00",
    "updated_at": "2026-09-02T14:00:00+02:00"
}
```

 
### Állapotok (status)

 | Érték | Jelentés |
| --- | --- |
| `active` | Az adóalany aktív, nyugta küldhető rá. |
| `suspended` | Az adóalany felfüggesztve — nyugta beküldés nem lehetséges rá, amíg vissza nem kerül aktív állapotba. |

 
## Adóalanyok listázása

 A lista `status` szerint szűrhető, és — a nyugtákkal ellentétben — kurzor alapú lapozást használ (`limit`, valamint a `links.next` URL-ben szereplő `cursor` paraméter) — lásd a [Lapozás](https://fiscon.hu/dokumentacio/bevezetes#lapozas) szakaszt.

    cURL   PHP   Laravel   JavaScript    ```bash
curl "https://api.fiscon.hu/v1/taxpayers?status=active&limit=50" \
    -H "Authorization: Bearer fis_live_xxxxxxxxxxxxxxxx"
```

   ```php
$curl = curl_init('https://api.fiscon.hu/v1/taxpayers?status=active&limit=50');

curl_setopt_array($curl, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer fis_live_xxxxxxxxxxxxxxxx',
    ],
]);

$response = curl_exec($curl);
curl_close($curl);
```

   ```php
use Illuminate\Support\Facades\Http;

$taxpayers = Http::withToken(config('services.fiscon.key'))
    ->get('https://api.fiscon.hu/v1/taxpayers', [
        'status' => 'active',
        'limit' => 50,
    ])
    ->json();
```

   ```javascript
const response = await fetch('https://api.fiscon.hu/v1/taxpayers?status=active&limit=50', {
    headers: {
        Authorization: 'Bearer fis_live_xxxxxxxxxxxxxxxx',
    },
});

const taxpayers = await response.json();
```

   
## Adóalany lekérdezése

    cURL   PHP   Laravel   JavaScript    ```bash
curl https://api.fiscon.hu/v1/taxpayers/txp_01hz3k9c8v0000000000000000 \
    -H "Authorization: Bearer fis_live_xxxxxxxxxxxxxxxx"
```

   ```php
$curl = curl_init('https://api.fiscon.hu/v1/taxpayers/txp_01hz3k9c8v0000000000000000');

curl_setopt_array($curl, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer fis_live_xxxxxxxxxxxxxxxx',
    ],
]);

$response = curl_exec($curl);
curl_close($curl);
```

   ```php
use Illuminate\Support\Facades\Http;

$taxpayer = Http::withToken(config('services.fiscon.key'))
    ->get('https://api.fiscon.hu/v1/taxpayers/txp_01hz3k9c8v0000000000000000')
    ->json();
```

   ```javascript
const response = await fetch('https://api.fiscon.hu/v1/taxpayers/txp_01hz3k9c8v0000000000000000', {
    headers: {
        Authorization: 'Bearer fis_live_xxxxxxxxxxxxxxxx',
    },
});

const taxpayer = await response.json();
```

   
## Adóalany frissítése

 A végpont PATCH-szemantikájú: csak a ténylegesen megadott mezők módosulnak, a többi változatlan marad.

 | Mező | Leírás |
| --- | --- |
| `name` | Max. 255 karakter. |
| `tax_number` | A [nyugta-létrehozásnál](https://fiscon.hu/dokumentacio/nyugtak) ismertetett formátumban. |
| `country_code` | Jelenleg csak `HU` fogadható el. |
| `status` | `active` vagy `suspended`. |

    cURL   PHP   Laravel   JavaScript    ```bash
curl -X PATCH https://api.fiscon.hu/v1/taxpayers/txp_01hz3k9c8v0000000000000000 \
    -H "Authorization: Bearer fis_live_xxxxxxxxxxxxxxxx" \
    -H "Content-Type: application/json" \
    -d '{
        "name": "Példa Kereskedelmi Kft. II.",
        "tax_number": "12345678-2-42",
        "country_code": "HU",
        "status": "suspended"
    }'
```

   ```php
$curl = curl_init('https://api.fiscon.hu/v1/taxpayers/txp_01hz3k9c8v0000000000000000');

curl_setopt_array($curl, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'PATCH',
    CURLOPT_POSTFIELDS => json_encode([
        'name' => 'Példa Kereskedelmi Kft. II.',
        'tax_number' => '12345678-2-42',
        'country_code' => 'HU',
        'status' => 'suspended',
    ]),
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer fis_live_xxxxxxxxxxxxxxxx',
        'Content-Type: application/json',
    ],
]);

$response = curl_exec($curl);
curl_close($curl);
```

   ```php
use Illuminate\Support\Facades\Http;

$taxpayer = Http::withToken(config('services.fiscon.key'))
    ->patch('https://api.fiscon.hu/v1/taxpayers/txp_01hz3k9c8v0000000000000000', [
        'name' => 'Példa Kereskedelmi Kft. II.',
        'tax_number' => '12345678-2-42',
        'country_code' => 'HU',
        'status' => 'suspended',
    ])
    ->json();
```

   ```javascript
const response = await fetch('https://api.fiscon.hu/v1/taxpayers/txp_01hz3k9c8v0000000000000000', {
    method: 'PATCH',
    headers: {
        Authorization: 'Bearer fis_live_xxxxxxxxxxxxxxxx',
        'Content-Type': 'application/json',
    },
    body: JSON.stringify({
        name: 'Példa Kereskedelmi Kft. II.',
        tax_number: '12345678-2-42',
        country_code: 'HU',
        status: 'suspended',
    }),
});

const taxpayer = await response.json();
```

   
## NAV hitelesítő adatok

 Az adóalany NAV Online Számla technikai felhasználói hitelesítő adatait a `credentials` alvégponton lehet beállítani. Ezek mindig az **éles** NAV környezethez tartoznak — a sandbox környezetben nincs szükség valós hitelesítő adatra, mert a NAV-hívások szimuláltak.

 A beállítás sikeres válasza a hitelesítő adatok aktuális `status` mezőjét adja vissza, amit a [kapcsolat tesztelése](https://fiscon.hu/dokumentacio/adoalanyok#kapcsolat-tesztelese) végpont vagy egy tényleges nyugtabeküldés frissít:

 ```json
{
    "environment": "live",
    "credential_version": 1,
    "status": "pending",
    "last_verified_at": null
}
```

 | Érték | Jelentés |
| --- | --- |
| `pending` | A hitelesítő adatok be vannak állítva, de még nem lettek ellenőrizve a NAV felé. |
| `verified` | A hitelesítő adatok érvényesnek bizonyultak egy sikeres NAV-kapcsolat során. |
| `invalid` | A NAV elutasította a hitelesítő adatokat — nyugta beküldés előtt javítsd ki azokat. |

    cURL   PHP   Laravel   JavaScript    ```bash
curl -X PUT https://api.fiscon.hu/v1/taxpayers/txp_01hz3k9c8v0000000000000000/credentials \
    -H "Authorization: Bearer fis_live_xxxxxxxxxxxxxxxx" \
    -H "Content-Type: application/json" \
    -d '{
        "login": "...",
        "password": "...",
        "signing_key": "...",
        "exchange_key": "..."
    }'
```

   ```php
$curl = curl_init('https://api.fiscon.hu/v1/taxpayers/txp_01hz3k9c8v0000000000000000/credentials');

curl_setopt_array($curl, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'PUT',
    CURLOPT_POSTFIELDS => json_encode([
        'login' => '...',
        'password' => '...',
        'signing_key' => '...',
        'exchange_key' => '...',
    ]),
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer fis_live_xxxxxxxxxxxxxxxx',
        'Content-Type: application/json',
    ],
]);

$response = curl_exec($curl);
curl_close($curl);
```

   ```php
use Illuminate\Support\Facades\Http;

Http::withToken(config('services.fiscon.key'))
    ->put('https://api.fiscon.hu/v1/taxpayers/txp_01hz3k9c8v0000000000000000/credentials', [
        'login' => '...',
        'password' => '...',
        'signing_key' => '...',
        'exchange_key' => '...',
    ]);
```

   ```javascript
await fetch('https://api.fiscon.hu/v1/taxpayers/txp_01hz3k9c8v0000000000000000/credentials', {
    method: 'PUT',
    headers: {
        Authorization: 'Bearer fis_live_xxxxxxxxxxxxxxxx',
        'Content-Type': 'application/json',
    },
    body: JSON.stringify({
        login: '...',
        password: '...',
        signing_key: '...',
        exchange_key: '...',
    }),
});
```

   
## Kapcsolat tesztelése

 A beállított hitelesítő adatok érvényességét egy próbakapcsolattal ellenőrizheted, mielőtt éles nyugtát küldenél be:

    cURL   PHP   Laravel   JavaScript    ```bash
curl -X POST https://api.fiscon.hu/v1/taxpayers/txp_01hz3k9c8v0000000000000000/connection-test \
    -H "Authorization: Bearer fis_live_xxxxxxxxxxxxxxxx"
```

   ```php
$curl = curl_init('https://api.fiscon.hu/v1/taxpayers/txp_01hz3k9c8v0000000000000000/connection-test');

curl_setopt_array($curl, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer fis_live_xxxxxxxxxxxxxxxx',
    ],
]);

$response = curl_exec($curl);
curl_close($curl);
```

   ```php
use Illuminate\Support\Facades\Http;

$result = Http::withToken(config('services.fiscon.key'))
    ->post('https://api.fiscon.hu/v1/taxpayers/txp_01hz3k9c8v0000000000000000/connection-test')
    ->json();
```

   ```javascript
const response = await fetch('https://api.fiscon.hu/v1/taxpayers/txp_01hz3k9c8v0000000000000000/connection-test', {
    method: 'POST',
    headers: {
        Authorization: 'Bearer fis_live_xxxxxxxxxxxxxxxx',
    },
});

const result = await response.json();
```

   
## ÁFA-kategóriák

 A NAV-hoz beküldött nyugták ÁFA-összesítőiben csak az adóalanyhoz a NAV-nál regisztrált ÁFA-kategóriák (pl. `27%`, `AAM`, `TAM`) használhatók. Ezt a listát az admin felület **ÁFA kategóriák** oldalán szinkronizálhatod és tekintheted meg a beállított hitelesítő adatok alapján.


---

Forrás: https://fiscon.hu/dokumentacio/jelentesek

# Jelentések

 A beküldött nyugták adóalanyonként és napi bontásban jelentésekbe (report) aggregálódnak — ez felel meg a NAV gépi nyugtaadat-szolgáltatás napi összesítő adatszolgáltatásának. A jelentések csak olvashatók az API-n keresztül, létrehozásuk automatikus.

 
## Jelentések listázása

 A lista `taxpayer_id` és `status` szerint szűrhető, kurzor alapú lapozással — lásd a [Lapozás](https://fiscon.hu/dokumentacio/bevezetes#lapozas) szakaszt.

    cURL   PHP   Laravel   JavaScript    ```bash
curl https://api.fiscon.hu/v1/reports \
    -H "Authorization: Bearer fis_live_xxxxxxxxxxxxxxxx"
```

   ```php
$curl = curl_init('https://api.fiscon.hu/v1/reports');

curl_setopt_array($curl, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer fis_live_xxxxxxxxxxxxxxxx',
    ],
]);

$response = curl_exec($curl);
curl_close($curl);
```

   ```php
use Illuminate\Support\Facades\Http;

$reports = Http::withToken(config('services.fiscon.key'))
    ->get('https://api.fiscon.hu/v1/reports')
    ->json();
```

   ```javascript
const response = await fetch('https://api.fiscon.hu/v1/reports', {
    headers: {
        Authorization: 'Bearer fis_live_xxxxxxxxxxxxxxxx',
    },
});

const reports = await response.json();
```

   
## Egy jelentés lekérdezése

 ```json
{
    "id": "rpt_01hz3k9c8v0000000000000000",
    "taxpayer_id": "txp_01hz3k9c8v0000000000000000",
    "report_date": "2026-09-02",
    "currency": "HUF",
    "first_receipt_number": "A/2026/00001",
    "last_receipt_number": "A/2026/00042",
    "receipt_count": 42,
    "number_of_sale_document": 40,
    "number_of_modifying_document": 2,
    "total": "1834200.00",
    "revision": 1,
    "status": "accepted",
    "due_at": "2026-09-03T00:00:00+02:00",
    "submitted_at": "2026-09-02T23:58:00+02:00",
    "accepted_at": "2026-09-02T23:59:10+02:00",
    "invalidated_at": null,
    "totals": [
        { "vat_category": "27%", "gross": "1270000.00" },
        { "vat_category": "AAM", "gross": "564200.00" }
    ]
}
```

 
### Állapotok (status)

 | Érték | Jelentés |
| --- | --- |
| `building` | A jelentés még nyitott, aznapi nyugták folyamatosan kerülnek bele. |
| `ready` | A jelentés lezárva, beküldésre kész. |
| `scheduled` | A beküldés ütemezve van (jellemzően a nap végi feldolgozási ablakra). |
| `submitting` | A beküldés éppen folyamatban van a NAV felé. |
| `submitted` | A NAV fogadta a kérést, a végleges eredmény még nem ismert. |
| `accepted` | A NAV elfogadta a jelentést. |
| `retry_scheduled` | Átmeneti hiba történt, a Fiscon automatikusan újrapróbálja a beküldést. |
| `rejected` | A NAV elutasította — lásd a kapcsolódó [beküldést](https://fiscon.hu/dokumentacio/bekuldesek) a hiba részleteiért. |
| `invalidation_pending` | Az érvénytelenítés kérése el lett indítva, folyamatban van a NAV felé. |
| `invalidated` | A jelentés utólag érvénytelenítve lett. |
| `failed` | A beküldés véglegesen sikertelen, automatikus újrapróbálkozás nélkül. |

 A jelentés csak `ready` vagy annál későbbi állapotban **érvényteleníthető** — egy még `building` állapotú, illetve már folyamatban lévő érvénytelenítésű jelentésen az érvénytelenítés hívása `409 REPORT_NOT_INVALIDATABLE` hibát ad.

 
## Jelentés érvénytelenítése

 Egy már beküldött jelentés csak az érvénytelenítés végponton keresztül vonható vissza — ez egy helyesbítő adatszolgáltatást indít a NAV felé:

    cURL   PHP   Laravel   JavaScript    ```bash
curl -X POST https://api.fiscon.hu/v1/reports/rpt_01hz3k9c8v0000000000000000/invalidate \
    -H "Authorization: Bearer fis_live_xxxxxxxxxxxxxxxx"
```

   ```php
$curl = curl_init('https://api.fiscon.hu/v1/reports/rpt_01hz3k9c8v0000000000000000/invalidate');

curl_setopt_array($curl, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer fis_live_xxxxxxxxxxxxxxxx',
    ],
]);

$response = curl_exec($curl);
curl_close($curl);
```

   ```php
use Illuminate\Support\Facades\Http;

Http::withToken(config('services.fiscon.key'))
    ->post('https://api.fiscon.hu/v1/reports/rpt_01hz3k9c8v0000000000000000/invalidate');
```

   ```javascript
await fetch('https://api.fiscon.hu/v1/reports/rpt_01hz3k9c8v0000000000000000/invalidate', {
    method: 'POST',
    headers: {
        Authorization: 'Bearer fis_live_xxxxxxxxxxxxxxxx',
    },
});
```


---

Forrás: https://fiscon.hu/dokumentacio/bekuldesek

# Beküldések

 Egy beküldés (submission) egy [jelentés](https://fiscon.hu/dokumentacio/jelentesek) egy konkrét NAV felé történő beküldési kísérletét reprezentálja, a NAV gépi nyugtaadat-szolgáltatás felé küldött és onnan kapott válasz részleteivel együtt. Egy jelentéshez több beküldés is tartozhat, ha újrapróbálkozás történt.

 
## Beküldések listázása

 A lista `report_id`, `taxpayer_id` és `status` szerint szűrhető, kurzor alapú lapozással — lásd a [Lapozás](https://fiscon.hu/dokumentacio/bevezetes#lapozas) szakaszt.

    cURL   PHP   Laravel   JavaScript    ```bash
curl https://api.fiscon.hu/v1/submissions \
    -H "Authorization: Bearer fis_live_xxxxxxxxxxxxxxxx"
```

   ```php
$curl = curl_init('https://api.fiscon.hu/v1/submissions');

curl_setopt_array($curl, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer fis_live_xxxxxxxxxxxxxxxx',
    ],
]);

$response = curl_exec($curl);
curl_close($curl);
```

   ```php
use Illuminate\Support\Facades\Http;

$submissions = Http::withToken(config('services.fiscon.key'))
    ->get('https://api.fiscon.hu/v1/submissions')
    ->json();
```

   ```javascript
const response = await fetch('https://api.fiscon.hu/v1/submissions', {
    headers: {
        Authorization: 'Bearer fis_live_xxxxxxxxxxxxxxxx',
    },
});

const submissions = await response.json();
```

   
## Egy beküldés lekérdezése

 ```json
{
    "id": "sub_01hz3k9c8v0000000000000000",
    "report_id": "rpt_01hz3k9c8v0000000000000000",
    "gateway": "nav-online-invoice",
    "gateway_version": "3.0",
    "status": "accepted",
    "external_submission_id": "NAV-2026-000123456",
    "submitted_at": "2026-09-02T23:58:00+02:00",
    "completed_at": "2026-09-02T23:59:10+02:00",
    "last_error_code": null,
    "last_error_message": null
}
```

 
### Állapotok (status)

 | Érték | Jelentés |
| --- | --- |
| `pending` | A beküldés még nem indult el. |
| `submitting` | Folyamatban a NAV felé küldés. |
| `submitted` | A NAV fogadta a kérést, a feldolgozás eredménye még nem ismert. |
| `accepted` | A NAV elfogadta az adatszolgáltatást. |
| `rejected` | A NAV elutasította — a hiba részletei a `last_error_code`/`last_error_message` mezőkben. |
| `retry_scheduled` | Átmeneti hiba történt, a Fiscon automatikusan újrapróbálja. |
| `failed` | A beküldés véglegesen sikertelen, automatikus újrapróbálkozás nélkül. |
| `invalidated` | A mögöttes jelentés érvénytelenítve lett. |

 Sikertelen beküldésekről `submission.rejected` és `submission.failed` [webhook eseményeket](https://fiscon.hu/dokumentacio/webhookok) is küldünk, így nem szükséges aktívan lekérdezni az állapotot.


---

Forrás: https://fiscon.hu/dokumentacio/webhookok

# Webhookok

 A webhookok segítségével valós időben értesülhetsz a nyugtáid és beküldéseid állapotváltozásairól, anélkül hogy folyamatosan lekérdezéseket kellene indítanod.

 
## Végpont regisztrálása

    cURL   PHP   Laravel   JavaScript    ```bash
curl -X POST https://api.fiscon.hu/v1/webhooks \
    -H "Authorization: Bearer fis_live_xxxxxxxxxxxxxxxx" \
    -H "Content-Type: application/json" \
    -d '{ "url": "https://example.com/webhooks/fiscon" }'
```

   ```php
$curl = curl_init('https://api.fiscon.hu/v1/webhooks');

curl_setopt_array($curl, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode(['url' => 'https://example.com/webhooks/fiscon']),
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer fis_live_xxxxxxxxxxxxxxxx',
        'Content-Type: application/json',
    ],
]);

$response = curl_exec($curl);
curl_close($curl);
```

   ```php
use Illuminate\Support\Facades\Http;

$webhook = Http::withToken(config('services.fiscon.key'))
    ->post('https://api.fiscon.hu/v1/webhooks', [
        'url' => 'https://example.com/webhooks/fiscon',
    ])
    ->json();
```

   ```javascript
const response = await fetch('https://api.fiscon.hu/v1/webhooks', {
    method: 'POST',
    headers: {
        Authorization: 'Bearer fis_live_xxxxxxxxxxxxxxxx',
        'Content-Type': 'application/json',
    },
    body: JSON.stringify({ url: 'https://example.com/webhooks/fiscon' }),
});

const webhook = await response.json();
```

   ```json
{
    "id": "whk_01hz3k9c8v0000000000000000",
    "url": "https://example.com/webhooks/fiscon",
    "active": true,
    "created_at": "2026-09-02T14:00:00+02:00"
}
```

 
## Végpontok kezelése

 A regisztrált webhook-végpontok listája kurzor alapú lapozást használ — lásd a [Lapozás](https://fiscon.hu/dokumentacio/bevezetes#lapozas) szakaszt.

 
### Listázás

    cURL   PHP   Laravel   JavaScript    ```bash
curl https://api.fiscon.hu/v1/webhooks \
    -H "Authorization: Bearer fis_live_xxxxxxxxxxxxxxxx"
```

   ```php
$curl = curl_init('https://api.fiscon.hu/v1/webhooks');

curl_setopt_array($curl, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer fis_live_xxxxxxxxxxxxxxxx',
    ],
]);

$response = curl_exec($curl);
curl_close($curl);
```

   ```php
use Illuminate\Support\Facades\Http;

$webhooks = Http::withToken(config('services.fiscon.key'))
    ->get('https://api.fiscon.hu/v1/webhooks')
    ->json();
```

   ```javascript
const response = await fetch('https://api.fiscon.hu/v1/webhooks', {
    headers: {
        Authorization: 'Bearer fis_live_xxxxxxxxxxxxxxxx',
    },
});

const webhooks = await response.json();
```

   
### Frissítés

    cURL   PHP   Laravel   JavaScript    ```bash
curl -X PATCH https://api.fiscon.hu/v1/webhooks/whk_01hz3k9c8v0000000000000000 \
    -H "Authorization: Bearer fis_live_xxxxxxxxxxxxxxxx" \
    -H "Content-Type: application/json" \
    -d '{ "active": false }'
```

   ```php
$curl = curl_init('https://api.fiscon.hu/v1/webhooks/whk_01hz3k9c8v0000000000000000');

curl_setopt_array($curl, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'PATCH',
    CURLOPT_POSTFIELDS => json_encode(['active' => false]),
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer fis_live_xxxxxxxxxxxxxxxx',
        'Content-Type: application/json',
    ],
]);

$response = curl_exec($curl);
curl_close($curl);
```

   ```php
use Illuminate\Support\Facades\Http;

Http::withToken(config('services.fiscon.key'))
    ->patch('https://api.fiscon.hu/v1/webhooks/whk_01hz3k9c8v0000000000000000', [
        'active' => false,
    ]);
```

   ```javascript
await fetch('https://api.fiscon.hu/v1/webhooks/whk_01hz3k9c8v0000000000000000', {
    method: 'PATCH',
    headers: {
        Authorization: 'Bearer fis_live_xxxxxxxxxxxxxxxx',
        'Content-Type': 'application/json',
    },
    body: JSON.stringify({ active: false }),
});
```

   
### Törlés

    cURL   PHP   Laravel   JavaScript    ```bash
curl -X DELETE https://api.fiscon.hu/v1/webhooks/whk_01hz3k9c8v0000000000000000 \
    -H "Authorization: Bearer fis_live_xxxxxxxxxxxxxxxx"
```

   ```php
$curl = curl_init('https://api.fiscon.hu/v1/webhooks/whk_01hz3k9c8v0000000000000000');

curl_setopt_array($curl, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'DELETE',
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer fis_live_xxxxxxxxxxxxxxxx',
    ],
]);

$response = curl_exec($curl);
curl_close($curl);
```

   ```php
use Illuminate\Support\Facades\Http;

Http::withToken(config('services.fiscon.key'))
    ->delete('https://api.fiscon.hu/v1/webhooks/whk_01hz3k9c8v0000000000000000');
```

   ```javascript
await fetch('https://api.fiscon.hu/v1/webhooks/whk_01hz3k9c8v0000000000000000', {
    method: 'DELETE',
    headers: {
        Authorization: 'Bearer fis_live_xxxxxxxxxxxxxxxx',
    },
});
```

   
### Teszt esemény küldése

    cURL   PHP   Laravel   JavaScript    ```bash
curl -X POST https://api.fiscon.hu/v1/webhooks/whk_01hz3k9c8v0000000000000000/test \
    -H "Authorization: Bearer fis_live_xxxxxxxxxxxxxxxx"
```

   ```php
$curl = curl_init('https://api.fiscon.hu/v1/webhooks/whk_01hz3k9c8v0000000000000000/test');

curl_setopt_array($curl, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer fis_live_xxxxxxxxxxxxxxxx',
    ],
]);

$response = curl_exec($curl);
curl_close($curl);
```

   ```php
use Illuminate\Support\Facades\Http;

Http::withToken(config('services.fiscon.key'))
    ->post('https://api.fiscon.hu/v1/webhooks/whk_01hz3k9c8v0000000000000000/test');
```

   ```javascript
await fetch('https://api.fiscon.hu/v1/webhooks/whk_01hz3k9c8v0000000000000000/test', {
    method: 'POST',
    headers: {
        Authorization: 'Bearer fis_live_xxxxxxxxxxxxxxxx',
    },
});
```

   
## Aláírás ellenőrzése

 Minden webhook-kérés tartalmaz egy `Fiscon-Signature` fejlécet, amivel ellenőrizheted, hogy a kérés valóban a Fisconból érkezett:

 ```bash
Fiscon-Signature: t=1735826400,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd
```

 Az aláírás számítása: `hash_hmac('sha256', "{t}.{nyers_kérés_törzs}", webhook_secret)`, ahol `t` az aláírásban szereplő Unix időbélyeg. A `webhook_secret`-et a végpont regisztrálásakor kapod meg — csak egyszer jelenítjük meg.

    PHP   Laravel   JavaScript    ```php
[$t, $v1] = array_map(
    fn (string $part): string => explode('=', $part, 2)[1],
    explode(',', request()->header('Fiscon-Signature'))
);

$expected = hash_hmac('sha256', "{$t}.".request()->getContent(), $webhookSecret);

if (! hash_equals($expected, $v1)) {
    abort(401);
}
```

   ```php
use Illuminate\Http\Request;

Route::post('/webhooks/fiscon', function (Request $request) {
    $webhookSecret = config('services.fiscon.webhook_secret');

    [$t, $v1] = array_map(
        fn (string $part): string => explode('=', $part, 2)[1],
        explode(',', $request->header('Fiscon-Signature'))
    );

    $expected = hash_hmac('sha256', "{$t}.".$request->getContent(), $webhookSecret);

    abort_unless(hash_equals($expected, $v1), 401);

    // ... esemény feldolgozása ...
});
```

   ```javascript
import { createHmac, timingSafeEqual } from 'node:crypto';

function verifyFisconSignature(rawBody, signatureHeader, webhookSecret) {
    const parts = Object.fromEntries(
        signatureHeader.split(',').map((part) => part.split('=')),
    );

    const expected = createHmac('sha256', webhookSecret)
        .update(`${parts.t}.${rawBody}`)
        .digest('hex');

    return timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}
```

   Az ellenőrzés helyességéhez mindig a **nyers** (feldolgozatlan) kérés-törzset használd, és időzítés-alapú visszafejtés elleni védelemhez konstans idejű összehasonlítást (pl. PHP `hash_equals()`) alkalmazz.

 A Fiscon nem kényszerít ki tolerancia-ablakot az aláírásban szereplő `t` időbélyegre — ez kizárólag a fogadó fél felelőssége. Javasolt egy néhány perces (pl. 5 perces) toleranciát is ellenőrizni a `t` és a jelenlegi idő között, hogy egy lejárt, esetlegesen újrajátszott kérést el tudj utasítani.

 
## Esemény payload

 ```json
{
    "id": "evt_01hz3k9c8v0000000000000000",
    "type": "submission.accepted",
    "created_at": "2026-09-02T23:59:10+02:00",
    "data": {
        "submission_id": "sub_01hz3k9c8v0000000000000000",
        "report_id": "rpt_01hz3k9c8v0000000000000000",
        "status": "accepted"
    }
}
```

 
## Események lekérdezése

 A kiküldött eseményeket az API-n keresztül is visszakeresheted, ha egy webhook-kézbesítés kimaradt volna. A lista `type` szerint szűrhető, kurzor alapú lapozással — lásd a [Lapozás](https://fiscon.hu/dokumentacio/bevezetes#lapozas) szakaszt.

    cURL   PHP   Laravel   JavaScript    ```bash
curl https://api.fiscon.hu/v1/events \
    -H "Authorization: Bearer fis_live_xxxxxxxxxxxxxxxx"

curl https://api.fiscon.hu/v1/events/evt_01hz3k9c8v0000000000000000 \
    -H "Authorization: Bearer fis_live_xxxxxxxxxxxxxxxx"
```

   ```php
$curl = curl_init('https://api.fiscon.hu/v1/events');

curl_setopt_array($curl, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer fis_live_xxxxxxxxxxxxxxxx',
    ],
]);

$response = curl_exec($curl);
curl_close($curl);
```

   ```php
use Illuminate\Support\Facades\Http;

$events = Http::withToken(config('services.fiscon.key'))
    ->get('https://api.fiscon.hu/v1/events')
    ->json();

$event = Http::withToken(config('services.fiscon.key'))
    ->get('https://api.fiscon.hu/v1/events/evt_01hz3k9c8v0000000000000000')
    ->json();
```

   ```javascript
const events = await fetch('https://api.fiscon.hu/v1/events', {
    headers: { Authorization: 'Bearer fis_live_xxxxxxxxxxxxxxxx' },
}).then((response) => response.json());
```