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:

https://api.fiscon.hu/v1

A sandbox környezetben ehelyett a sandbox. aldomaint kell használni — lásd lent a Környezetek 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 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:

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

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

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:

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 oldallal, hogy megtudd, hogyan kell az API-kulcsodat a kérésekhez csatolni.