{ "openapi": "3.0.3", "info": { "title": "KapuSegéd API", "version": "2.1.0", "description": "A KapuSegéd API-val a saját programod (könyvelőprogram, belső irodai eszköz, ügyfélportál) gépi úton\néri el ugyanazokat az adatokat és műveleteket, amelyeket a KapuSegéd felületén látsz: ügyfélkapuk,\nadózók, tárhely-üzenetek, bevallások, adófolyószámla, fizetési kötelezettségek, foglalkoztatási\nadatok és az iroda beállításai.\n\n## Alapok\n\n- **Cím:** minden végpont a `https://api.kapuseged.hu` alatt érhető el, HTTPS-en.\n- **Formátum:** a kérés és a válasz JSON (`Content-Type: application/json`, `Accept: application/json`).\n A fájlfeltöltések (importok) `multipart/form-data` kéréssel mennek, az exportok fájlt adnak vissza.\n- **Nincs burok:** a válasz maga az objektum vagy a lista, nincs `data` kulcs körülötte.\n- **Időpontok:** az időbélyegek (`created_at`, `updated_at`, `arrived_at` …) Unix-időbélyegek\n másodpercben (egész szám); a naptári dátumok `ÉÉÉÉ-HH-NN` alakú szövegek. Az időzóna Europe/Budapest.\n- **Nyelv:** a hibaüzenetek és a megnevezések magyarul jönnek.\n\n## Hitelesítés\n\nA végpontok (a belépés, a regisztráció, a jelszó-visszaállítás és a konfiguráció kivételével)\nhitelesítést kérnek: a kérés `Authorization` fejlécében egy **Bearer token** megy.\n\n```\nAuthorization: Bearer 12|AbCdEf…\n```\n\nKétféle token van, a végpontok mindkettőt elfogadják:\n\n1. **API-kulcs (ajánlott gépi kapcsolathoz).** A KapuSegédben a **Beállítások › API kulcsok** oldalon\n hozod létre (az oldalt az iroda menedzsere látja). A kulcs csak a létrehozáskor látszik, ezért\n azonnal tárold el biztonságos helyen. Addig érvényes, amíg nem törlöd.\n2. **Belépési token.** A `POST /login` végpont e-mail-címmel és jelszóval ad tokent (`access_token`).\n Ha a felhasználónál be van kapcsolva a kétfaktoros azonosítás, az első hívás\n `two_factor_required: true` választ ad, és a hívást a hitelesítő alkalmazás kódjával\n (`two_factor_code`) kell megismételni. A token a `POST /logout` hívásig érvényes.\n\nA token a **létrehozó felhasználó nevében** működik: ugyanazokat az adatokat látja, és ugyanazok a\nszerepkör-, adózói és előfizetési korlátok vonatkoznak rá, mint a felhasználóra a felületen. Egy\nkijelölt adózókra korlátozott felhasználó kulcsa például csak azokat az adózókat éri el.\n\n**Partner-azonosító (nem kötelező).** Ha a KapuSegédtől partner-azonosítót kaptál, a kéréseidben a\n`partner-token` fejlécben küldheted. Nem kötelező; ha küldöd, érvényesnek kell lennie (egy hibás\nazonosító `422` választ ad).\n\n## Listák, keresés, lapozás\n\n- A `GET /…` listák (például `GET /customer-portals`) **minden** elérhető rekordot visszaadnak, lapozás\n nélkül. Nagy állománynál használd a keresést.\n- A `POST /…/search` végpontok szűrnek és lapoznak. A kérésben: `search` (szabad szöveg),\n `limit` (1–200, alapból 200), `page` (1-től), `order_column` és `order_direction` (`asc` / `desc`),\n plusz a végpont saját szűrői. A válasz: `records` (a találatok), `count` (az összes találat száma),\n `page`, `max_page`, `order_column`, `order_direction`.\n- A `POST /…/export` végpontok ugyanazokkal a szűrőkkel Excel-fájlt (`.xlsx`) adnak vissza.\n- Az importok (`POST /…/import`) egy `import_file` mezőben várják az Excel-fájlt; a minta a\n `GET /…/download-import-sample` végponttal tölthető le.\n\n## Hibák\n\n| Kód | Jelentés | Válasz |\n|---|---|---|\n| `401` | Hiányzó vagy érvénytelen token | `{\"message\": \"Unauthenticated.\"}` |\n| `403` | A felhasználó szerepköre vagy az előfizetési csomag nem engedi | `{\"message\": \"…\"}` |\n| `404` | A rekord nem létezik, vagy a felhasználó nem éri el | `{\"message\": \"…\"}` |\n| `422` | Hibás adat | `{\"message\": \"…\", \"errors\": {\"mezo\": [\"…\"]}}` |\n| `429` | Túl sok kérés rövid idő alatt (egyes végpontoknál) | `{\"message\": \"…\"}` |\n\n## Változásnapló\n\n- **2.1.0 (2026-10-27):** a `partner-token` fejléc nem kötelező; a szabályok (`/actions`) azonosítója a\n szabályé (a lista minden szabályt tartalmaz, a nem módosítottakat alapbeállítással); új végpont:\n `GET /customer-portals/codes`; a teljes leírás pontosítva és kiegészítve.\n" }, "servers": [ { "url": "https://api.kapuseged.hu" } ], "tags": [ { "name": "Belépés és regisztráció", "description": "Belépés (token kérése), kilépés, regisztráció, meghívó elfogadása és jelszó-visszaállítás." }, { "name": "Konfiguráció", "description": "A felület működéséhez szükséges, bejelentkezés nélkül lekérhető beállítások." }, { "name": "Saját profil", "description": "A bejelentkezett felhasználó adatai." }, { "name": "Jelszócsere", "description": "A bejelentkezett felhasználó jelszavának módosítása." }, { "name": "Kétfaktoros azonosítás", "description": "A bejelentkezés kétfaktoros azonosításának be- és kikapcsolása." }, { "name": "API-kulcsok", "description": "A felhasználó saját API-kulcsai." }, { "name": "Iroda", "description": "Az iroda (a KapuSegéd-előfizető) adatai és beállításai." }, { "name": "Felhasználók", "description": "Az iroda munkatársai és ügyfelei: meghívás, szerepkör, adózói hozzáférés." }, { "name": "Előfizetési csomag", "description": "Az iroda előfizetési csomagja." }, { "name": "Számlák", "description": "Az iroda KapuSegéd-számlái és az aktuális díj." }, { "name": "Vezérlőpult", "description": "A vezérlőpult összesítő adatai." }, { "name": "Ügyfélkapuk", "description": "Az iroda ügyfélkapui (Ügyfélkapu+ / DÁP belépések), amelyeken keresztül a KapuSegéd az adózók adatait letölti." }, { "name": "Ügyfélkapu-összekapcsolás", "description": "Egy ügyfélkapu bekötése a KapuSegédbe (az ellenőrző kód megadásával)." }, { "name": "Cégkapuk", "description": "Az ügyfélkapukon elérhető cég- és hivatali tárhelyek." }, { "name": "Adózók", "description": "Az iroda által képviselt adózók: törzsadatok, adófolyószámla, önkormányzati adószámla, köztartozás, exportok és kiküldések." }, { "name": "Önkormányzatok", "description": "Önkormányzatok törzsadatai." }, { "name": "Tárhely-üzenetek", "description": "A NAV- és egyéb hivatali tárhelyekre érkezett üzenetek." }, { "name": "Üzenetstátuszok", "description": "Az iroda saját üzenetstátuszai (például Nyitott, Folyamatban, Lezárt)." }, { "name": "Szabályok", "description": "Dokumentumtípusonként mit tegyen a rendszer a beérkező tárhely-üzenettel (státusz, letöltés, e-mailes kiküldés, szín)." }, { "name": "Elküldött levelek", "description": "A KapuSegédből kiküldött e-mailek." }, { "name": "Bevallások", "description": "Az adózók benyújtott bevallásai." }, { "name": "Hiányzó bevallások", "description": "Az esedékes, de be nem nyújtott bevallások." }, { "name": "Bevallási kötelezettségek", "description": "Az adózók bevallási kötelezettségei éves, havi bontású táblázatban." }, { "name": "Adófolyószámla-lekérdezések", "description": "Adófolyószámla-lekérdezés indítása több adózóra, és az eredmények." }, { "name": "Adófolyószámla-lekérdezés adózónként", "description": "Egy adófolyószámla-lekérdezés adózónkénti eredményei." }, { "name": "Fizetési kötelezettségek", "description": "Az adózók fizetési kötelezettségei (NAV, önkormányzat, kézzel rögzített), éves táblázat és e-mailes kiküldés." }, { "name": "Biztosítottak", "description": "Az adózók biztosítotti jogviszonyai." }, { "name": "Alkalmi munkavállalók", "description": "Egyszerűsített foglalkoztatás (EFO) bejelentései." }, { "name": "Saját foglalkoztatók", "description": "Azok a foglalkoztatók, amelyeknél az adózó maga biztosított." }, { "name": "Adategyeztetések", "description": "A NAV adategyeztetési eljárásai." }, { "name": "PmtSegéd", "description": "Az összekapcsolt PmtSegéd-fiók kezelése." } ], "security": [ { "bearerAuth": [] }, { "bearerAuth": [], "PartnerToken": [] } ], "paths": { "/configs": { "get": { "tags": [ "Konfiguráció" ], "summary": "Konfigurációs adatok lekérdezése", "description": "A kliensek működéséhez szükséges, felhasználótól független konfigurációt adja vissza: a szerepkörök jogosultság-tábláját, az előfizetési csomagokat és összehasonlító táblázatukat, az adónemek listáját, az asztali alkalmazásban megnyitható portálokat és a NAV M2M-kapcsolat beállításához szükséges kliens-azonosítót. Bejelentkezés nélkül hívható.", "responses": { "200": { "description": "Sikeres művelet.", "content": { "application/json": { "schema": { "type": "object", "description": "Konfiguráció.", "properties": { "roles": { "type": "object", "description": "Szerepkörönként (`manager`, `accountant`, `trustee`) a jogosultságok táblája: jogosultság-kulcs → engedélyezett-e. Egy művelet akkor engedélyezett, ha a szerepkör ÉS az iroda csomagja is engedi (lásd `User.permissions` és `User.package_functions`).", "additionalProperties": { "type": "object", "additionalProperties": { "type": "boolean" } }, "example": { "manager": { "read_office": true, "invite_user": true }, "accountant": { "read_office": false, "invite_user": false } } }, "packages": { "type": "array", "description": "Az előfizetési csomagok a csomagválasztó megjelenítéséhez.", "items": { "type": "object", "description": "Egy csomag.", "properties": { "name": { "type": "string", "description": "A csomag azonosítója. `free` – Ingyenes, `basic` – Alap, `premium` – Prémium csomag.", "enum": [ "free", "basic", "premium" ] }, "label": { "type": "string", "description": "A csomag megjelenített neve.", "example": "Alap csomag" }, "description": { "type": "string", "description": "Rövid leírás." }, "price": { "type": "object", "description": "A csomag listaára forintban (nettó).", "properties": { "base": { "type": "integer", "description": "Havi alapdíj." }, "trustee": { "type": "integer", "description": "Aktív adózónkénti havi díj." } } }, "features": { "type": "array", "description": "A csomag funkciói felsorolásként.", "items": { "type": "object", "description": "Egy funkció.", "properties": { "label": { "type": "string", "description": "Megjelenítendő szöveg." }, "value": { "type": "boolean", "description": "Benne van-e a csomagban." }, "hint": { "type": "string", "description": "Magyarázó szöveg.", "nullable": true } } } } } } }, "package_table": { "type": "object", "description": "A csomagok összehasonlító táblázata.", "properties": { "packages": { "type": "array", "description": "Az oszlopok (csomagok).", "items": { "type": "object", "description": "Egy csomag fejléce.", "properties": { "name": { "type": "string", "description": "A csomag azonosítója.", "enum": [ "free", "basic", "premium" ] }, "label": { "type": "string", "description": "A csomag neve." }, "icon": { "type": "string", "description": "Ikonnév a megjelenítéshez." }, "description": { "type": "string", "description": "Rövid leírás." } } } }, "table": { "type": "array", "description": "A sorok (funkciók).", "items": { "type": "object", "description": "Egy funkció sora.", "properties": { "feature": { "type": "string", "description": "A funkció neve.", "example": "Max. adózók száma" }, "values": { "type": "object", "description": "Csomag-azonosító → érték: logikai (benne van-e), szám (korlát) vagy megjelenítendő szöveg (pl. „Korlátlan”).", "additionalProperties": true } } } } } }, "tax_types": { "type": "object", "description": "A NAV-adónemek: adónemkód → megnevezés és a befizetéshez használt NAV-számlaszám.", "additionalProperties": { "type": "object", "description": "Egy adónem.", "properties": { "name": { "type": "string", "description": "Az adónem megnevezése." }, "bank_account_number": { "type": "string", "description": "A NAV beszedési számlájának száma.", "example": "10032000-01076868" } } }, "example": { "104": { "name": "Általános forgalmi adó", "bank_account_number": "10032000-01076868" } } }, "desktop": { "type": "object", "description": "Az asztali alkalmazás beállításai.", "properties": { "portals": { "type": "array", "description": "Az asztali alkalmazásból ügyfélkapus belépéssel megnyitható portálok.", "items": { "type": "object", "description": "Egy portál.", "properties": { "name": { "type": "string", "description": "Azonosító. `tarhely` – NAV tárhely (Cégkapu/Ügyfélkapu tárhely), `upo` – NAV Online Ügyfélportál (ÜPO).", "enum": [ "tarhely", "upo" ] }, "label": { "type": "string", "description": "Megjelenített név.", "example": "ÜPO" } } } } } }, "m2m_client_id": { "type": "string", "description": "A KapuSegéd NAV M2M (gép-gép kapcsolati) kliens-azonosítója; a NAV-on az M2M-kulcs igénylésénél kell megadni.", "nullable": true } } } } } } }, "security": [] } }, "/register": { "post": { "tags": [ "Belépés és regisztráció" ], "summary": "Regisztráció (új iroda)", "description": "Új irodát és annak fő felhasználóját (menedzser szerepkör, `main: true`) hozza létre, majd azonnal be is jelentkeztet: a válasz a felhasználót és egy új hozzáférési tokent tartalmaz. Az iroda próbaidőszakkal (demó) indul; érvényes kuponkód vagy ajánlói kód kedvezményt adhat. Az iroda email-címe és a kiküldött levelek válaszcíme a regisztráló email-címe lesz. Bejelentkezés nélkül hívható.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "A felhasználó teljes neve.", "maxLength": 255, "example": "Kiss Elemér" }, "email": { "type": "string", "description": "Email-cím; a rendszerben egyedinek kell lennie. Ez lesz a belépési azonosító és az iroda email-címe is.", "format": "email", "maxLength": 255, "example": "elemer@kiss.hu" }, "phone": { "type": "string", "description": "Telefonszám.", "maxLength": 255, "example": "+36301234567" }, "password": { "type": "string", "description": "Jelszó, legalább 6 karakter.", "minLength": 6, "format": "password" }, "newsletter": { "type": "boolean", "description": "Kér-e hírlevelet.", "nullable": true, "default": false }, "coupon": { "type": "string", "description": "Kuponkód (kis- és nagybetű nem számít). Csak érvényes, le nem járt kupon fogadható el, különben 422.", "nullable": true }, "referral_code": { "type": "string", "description": "Egy másik iroda ajánlói kódja (`Office.token`). Ismeretlen kód esetén nincs hiba, csak nem érvényesül az ajánlás.", "nullable": true, "example": "AB12CD34" }, "utm_source": { "type": "string", "description": "Marketing-forrás (UTM) követéshez.", "nullable": true, "maxLength": 255 }, "utm_campaign": { "type": "string", "description": "UTM kampány.", "nullable": true, "maxLength": 255 }, "utm_medium": { "type": "string", "description": "UTM médium.", "nullable": true, "maxLength": 255 }, "utm_content": { "type": "string", "description": "UTM tartalom.", "nullable": true, "maxLength": 255 }, "utm_term": { "type": "string", "description": "UTM kulcsszó.", "nullable": true, "maxLength": 255 } }, "required": [ "name", "email", "phone", "password" ] } } } }, "responses": { "200": { "description": "Sikeres művelet.", "content": { "application/json": { "schema": { "type": "object", "description": "Bejelentkezett állapot: a felhasználó és az új hozzáférési token.", "properties": { "user": { "$ref": "#/components/schemas/User" }, "access_token": { "type": "string", "description": "Új hozzáférési token (bejelentkezési jogkörrel). A token „{azonosító}|{titok}” alakú; a további kéréseknél `Authorization: Bearer ` fejlécben kell küldeni. Csak ebben a válaszban látható, később nem kérhető le újra.", "example": "123|AbCdEfGhIjKlMnOpQrStUvWxYz0123456789abcd" }, "two_factor_required": { "type": "boolean", "description": "Itt mindig `false`." } }, "required": [ "user", "access_token", "two_factor_required" ] } } } }, "422": { "$ref": "#/components/responses/ValidationError" } }, "security": [] } }, "/invitation-register": { "post": { "tags": [ "Belépés és regisztráció" ], "summary": "Regisztráció meghívóval", "description": "Egy kolléga által meghívott (`status: invited`) felhasználó a meghívó emailben kapott tokennel beállítja a jelszavát. A fiók aktívvá válik, és a válasz azonnal bejelentkezett állapotot ad (felhasználó + új hozzáférési token). Ismeretlen token vagy már regisztrált felhasználó esetén 422. Bejelentkezés nélkül hívható.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "A meghívó emailben lévő regisztrációs link tokenje." }, "password": { "type": "string", "description": "Jelszó, legalább 6 karakter.", "minLength": 6, "format": "password" } }, "required": [ "token", "password" ] } } } }, "responses": { "200": { "description": "Sikeres művelet.", "content": { "application/json": { "schema": { "type": "object", "description": "Bejelentkezett állapot: a felhasználó és az új hozzáférési token.", "properties": { "user": { "$ref": "#/components/schemas/User" }, "access_token": { "type": "string", "description": "Új hozzáférési token (bejelentkezési jogkörrel). A token „{azonosító}|{titok}” alakú; a további kéréseknél `Authorization: Bearer ` fejlécben kell küldeni. Csak ebben a válaszban látható, később nem kérhető le újra.", "example": "123|AbCdEfGhIjKlMnOpQrStUvWxYz0123456789abcd" }, "two_factor_required": { "type": "boolean", "description": "Itt mindig `false`." } }, "required": [ "user", "access_token", "two_factor_required" ] } } } }, "422": { "$ref": "#/components/responses/ValidationError" } }, "security": [] } }, "/invitation-details": { "post": { "tags": [ "Belépés és regisztráció" ], "summary": "Meghívott felhasználó adatai a meghívó tokenjével", "description": "A meghívó emailben kapott token alapján visszaadja a meghívott felhasználó adatait (név, email, szerepkör…), hogy a regisztrációs űrlap előre kitölthető legyen. Ismeretlen token vagy már regisztrált felhasználó esetén 422. Bejelentkezés nélkül hívható.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "A meghívó emailben lévő regisztrációs link tokenje." } }, "required": [ "token" ] } } } }, "responses": { "200": { "description": "A meghívott felhasználó (a `trustees` mező nélkül).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } }, "422": { "$ref": "#/components/responses/ValidationError" } }, "security": [] } }, "/login": { "post": { "tags": [ "Belépés és regisztráció" ], "summary": "Bejelentkezés", "description": "Email-címmel és jelszóval bejelentkeztet, és új hozzáférési tokent ad. Ha a felhasználónál be van kapcsolva a kétlépcsős azonosítás (2FA), és a kérés nem tartalmaz `two_factor_code`-ot, a válasz `two_factor_required: true`, a `user` és az `access_token` pedig `null`: ilyenkor ugyanazt a kérést a hitelesítő alkalmazás aktuális 6 jegyű kódjával kell megismételni. Hibás email/jelszó esetén 401; hibás 2FA-kód, illetve még csak meghívott (a regisztrációt be nem fejezett) felhasználó esetén 422. Bejelentkezés nélkül hívható.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "A felhasználó email-címe.", "format": "email", "example": "elemer@kiss.hu" }, "password": { "type": "string", "description": "Jelszó.", "format": "password" }, "two_factor_code": { "type": "string", "description": "A hitelesítő alkalmazás aktuális 6 jegyű kódja; csak bekapcsolt 2FA esetén kell.", "nullable": true, "example": "123456" } }, "required": [ "email", "password" ] } } } }, "responses": { "200": { "description": "Sikeres bejelentkezés, vagy 2FA-kód szükséges (`two_factor_required: true`).", "content": { "application/json": { "schema": { "type": "object", "description": "Bejelentkezés eredménye.", "properties": { "user": { "allOf": [ { "$ref": "#/components/schemas/User" } ], "nullable": true, "description": "A bejelentkezett felhasználó; `null`, ha 2FA-kód szükséges." }, "access_token": { "type": "string", "description": "Új hozzáférési token; `null`, ha 2FA-kód szükséges. A token „{azonosító}|{titok}” alakú; a további kéréseknél `Authorization: Bearer ` fejlécben kell küldeni. Csak ebben a válaszban látható, később nem kérhető le újra.", "nullable": true }, "two_factor_required": { "type": "boolean", "description": "`true`, ha a felhasználónál be van kapcsolva a 2FA és a kérésből hiányzott a kód: a kérést a `two_factor_code`-dal meg kell ismételni." } }, "required": [ "user", "access_token", "two_factor_required" ] } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "422": { "$ref": "#/components/responses/ValidationError" } }, "security": [] } }, "/logout": { "post": { "tags": [ "Belépés és regisztráció" ], "summary": "Kijelentkezés", "description": "Érvényteleníti azt a hozzáférési tokent, amellyel a kérés érkezett; a felhasználó többi tokenje érvényben marad. Csak bejelentkezéssel kapott tokennel hívható, API-kulccsal 403-at ad (API-kulcsot a `DELETE /api-keys/{id}` von vissza).", "responses": { "200": { "description": "Sikeres művelet, üres választörzzsel." }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" } } } }, "/password/email": { "post": { "tags": [ "Belépés és regisztráció" ], "summary": "Jelszó-visszaállító link küldése", "description": "Jelszó-visszaállító linket küld emailben a megadott címre. A link korlátozott ideig érvényes, és csak egyszer használható. Ha a cím nem tartozik felhasználóhoz, vagy a felhasználó még csak meghívott, 422-t ad. Bejelentkezés nélkül hívható.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "A felhasználó email-címe.", "format": "email", "example": "elemer@kiss.hu" } }, "required": [ "email" ] } } } }, "responses": { "200": { "description": "A levél kiküldve, üres választörzzsel." }, "422": { "$ref": "#/components/responses/ValidationError" } }, "security": [] } }, "/password/reset": { "post": { "tags": [ "Belépés és regisztráció" ], "summary": "Jelszó visszaállítása", "description": "Beállítja az új jelszót a visszaállító emailben kapott tokennel; a token ezután nem használható újra. Érvénytelen, már felhasznált vagy lejárt token esetén 422. A felhasználó meglévő hozzáférési tokenjei és API-kulcsai érvényben maradnak. Bejelentkezés nélkül hívható.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "A jelszó-visszaállító emailben lévő link tokenje." }, "password": { "type": "string", "description": "Jelszó, legalább 6 karakter.", "minLength": 6, "format": "password" } }, "required": [ "token", "password" ] } } } }, "responses": { "200": { "description": "Sikeres művelet, üres választörzzsel." }, "422": { "$ref": "#/components/responses/ValidationError" } }, "security": [] } }, "/dashboard": { "get": { "tags": [ "Vezérlőpult" ], "summary": "Vezérlőpult összesítő adatai", "description": "A vezérlőpult összesített számait adja a bejelentkezett felhasználó szemszögéből: csak azokat az adózókat, ügyfélkapukat, üzeneteket és bevallásokat számolja, amelyekhez a felhasználónak joga van (`trustee_permission`). A `customer_portal_statuses` és `customer_portal_runs` csak ügyfélkapu-olvasási joggal (menedzser, könyvelő), az `unpaid_invoices` csak számla-olvasási joggal (menedzser) szerepel a válaszban. Egyes számok gyorsítótárból jönnek, ezért a legutóbbi változást késéssel követhetik.", "responses": { "200": { "description": "Sikeres művelet.", "content": { "application/json": { "schema": { "type": "object", "description": "Vezérlőpult-adatok.", "properties": { "missing_declarations": { "type": "object", "description": "Hiányzó bevallások (amelyeket az ÜPO hiányzóként mutat, és a rendszer még nem talált hozzájuk beadott bevallást) a határidő óta eltelt napok szerint.", "properties": { "max_7_days": { "type": "integer", "description": "Hiányzó bevallás, amelynek határideje óta eltelt idő, legfeljebb 7 napos." }, "min_8_max_15_days": { "type": "integer", "description": "Hiányzó bevallás, amelynek határideje óta eltelt idő, 8–15 napos." }, "min_16_days": { "type": "integer", "description": "Hiányzó bevallás, amelynek határideje óta eltelt idő, legalább 16 napos." }, "all_missing_declarations_on_upo": { "type": "integer", "description": "Az ÜPO-n hiányzóként szereplő összes bevallás, azokkal együtt, amelyekhez a rendszer azóta már talált beadott bevallást." } } }, "notified_declarations": { "type": "object", "description": "„Kiértesítve” állapotú bevallások (a NAV értesítést küldött róluk, pl. hibás adattartalom miatt; jellemzően teendő van velük) az első kapcsolódó tárhely-üzenet érkezése óta eltelt napok szerint.", "properties": { "max_7_days": { "type": "integer", "description": "Kiértesített bevallás, amelynek első üzenete óta eltelt idő, legfeljebb 7 napos." }, "min_8_max_15_days": { "type": "integer", "description": "Kiértesített bevallás, amelynek első üzenete óta eltelt idő, 8–15 napos." }, "min_16_days": { "type": "integer", "description": "Kiértesített bevallás, amelynek első üzenete óta eltelt idő, legalább 16 napos." } } }, "messages_max_7_days": { "type": "array", "description": "Az utolsó 7 napban (ma és az előző 6 nap) érkezett tárhely-üzenetek száma üzenetállapotonként, az iroda állapot-sorrendjében.", "items": { "type": "object", "description": "Egy üzenetállapot.", "properties": { "message_status_id": { "type": "integer", "description": "Az üzenetállapot azonosítója (lásd MessageStatus)." }, "name": { "type": "string", "description": "Az üzenetállapot neve.", "example": "Új" }, "count": { "type": "integer", "description": "Ilyen állapotú üzenetek száma." } } } }, "customer_portal_statuses": { "type": "object", "description": "Az ügyfélkapuk állapota. Csak ügyfélkapu-olvasási joggal szerepel.", "properties": { "active": { "type": "integer", "description": "Aktív ügyfélkapuk, működő kapcsolattal." }, "disconnected": { "type": "integer", "description": "Aktív ügyfélkapuk, amelyeknél megszakadt a kapcsolat: újra be kell jelentkezni." }, "inactive": { "type": "integer", "description": "Kikapcsolt (inaktív) ügyfélkapuk." } } }, "customer_portal_runs": { "type": "array", "description": "Az aktív ügyfélkapuk a folyamatban lévő szinkronjuk adataival. Csak ügyfélkapu-olvasási joggal szerepel.", "items": { "$ref": "#/components/schemas/CustomerPortal" } }, "trustees": { "type": "object", "description": "Az adózók száma.", "properties": { "active": { "type": "integer", "description": "Aktív adózók, adószám/adóazonosító jel szerint egyedileg számolva." }, "active_duplicated": { "type": "integer", "description": "Aktív adózók többszörös előfordulásai (ugyanaz az adózó több ügyfélkapuban is szerepel)." }, "inactive": { "type": "integer", "description": "Inaktív adózók." } } }, "unpaid_invoices": { "type": "array", "description": "Az iroda 14 napnál régebben kiállított, ki nem egyenlített előfizetési számlái. Csak számla-olvasási joggal (menedzser) szerepel.", "items": { "$ref": "#/components/schemas/Invoice" } }, "notifications": { "type": "array", "description": "A vezérlőpulton megjelenítendő rendszerértesítések (pl. karbantartás, szünetelő szolgáltatás, lejáró próbaidőszak).", "items": { "type": "object", "description": "Egy értesítés.", "properties": { "text": { "type": "string", "description": "Az értesítés szövege." }, "color": { "type": "string", "description": "Kiemelés színe. `success` – zöld (kedvező hír), `info` – kék (tájékoztatás), `warning` – narancs (figyelmeztetés), `danger` – piros (hiba).", "enum": [ "success", "info", "warning", "danger" ] } } } }, "surveys": { "type": "array", "description": "Kitöltendő vagy folyamatban lévő NAV-kérdőívek a látható adózóknál, az adózó adataival (`trustee`).", "items": { "$ref": "#/components/schemas/Survey" } } } } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" } } } }, "/office": { "get": { "tags": [ "Iroda" ], "summary": "Iroda adatainak lekérdezése", "description": "A bejelentkezett felhasználó irodájának adatait és beállításait adja vissza. Csak menedzser szerepkörrel hívható.", "responses": { "200": { "description": "Sikeres művelet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Office" } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" } } }, "put": { "tags": [ "Iroda" ], "summary": "Iroda számlázási adatainak módosítása", "description": "Az iroda számlázási adatait módosítja; ezekre a névre és címre állítja ki a rendszer az előfizetési számlákat. A név, város, irányítószám és cím kötelező, az adószám elhagyható (ekkor törlődik). Fizetős csomagra váltáshoz (próbaidőszakon kívül) a számlázási adatok megadása szükséges. Csak menedzser szerepkörrel hívható. A válasz a frissített iroda.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "billing_name": { "type": "string", "description": "Számlázási név (cég vagy magánszemély neve).", "maxLength": 255, "example": "Kiss Könyvelő Kft." }, "billing_city": { "type": "string", "description": "Számlázási cím: település.", "maxLength": 255, "example": "Budapest" }, "billing_zip": { "type": "integer", "description": "Számlázási cím: irányítószám.", "minimum": 1000, "maximum": 9999, "example": 1111 }, "billing_address": { "type": "string", "description": "Számlázási cím: közterület, házszám.", "maxLength": 255, "example": "Fő utca 1." }, "billing_tax_number": { "type": "string", "description": "Adószám (11 számjegy, kötőjelekkel vagy anélkül); a rendszer ellenőrzi a formátumot és az ellenőrző számjegyet.", "nullable": true, "example": "12345676-1-43" } }, "required": [ "billing_name", "billing_city", "billing_zip", "billing_address" ] } } } }, "responses": { "200": { "description": "Sikeres művelet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Office" } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/office/settings": { "post": { "tags": [ "Iroda" ], "summary": "Iroda beállításainak módosítása", "description": "Az iroda működési beállításait menti: új adózók és cégkapuk alapértelmezett aktivitása, értesítő levelek gyakorisága, a kiküldött levelek feladóneve és válaszcíme, fizetési kötelezettség-emlékeztetők. Teljes csere: minden mezőt el kell küldeni; a kihagyott `email_alias` törlődik, a kihagyott `payment_obligation_notification_days_before_due` üres listára áll. Csak menedzser szerepkörrel hívható. A válasz a frissített iroda.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tarhely_trustee_active_default": { "type": "boolean", "description": "Tárhely-üzenetben talált új, eddig ismeretlen adózó aktívként (`true`) vagy inaktívként kerüljön-e be." }, "upo_trustee_active_default": { "type": "boolean", "description": "Az ÜPO-n talált új, eddig ismeretlen adózó aktívként (`true`) vagy inaktívként kerüljön-e be." }, "mailbox_active_default": { "type": "boolean", "description": "A tárhelyen talált új, eddig ismeretlen cégkapu aktívként (`true`) vagy inaktívként kerüljön-e be." }, "summary_mail_interval_days": { "type": "integer", "description": "Hány naponta kapjanak a felhasználók összesítő emailt (hiányzó bevallások, adózói egyenlegek, törzsadat-változások, új adózók).", "minimum": 1, "maximum": 30, "example": 7 }, "trustee_debt_mail_interval_days": { "type": "integer", "description": "Hány naponta kapjanak hátralék-értesítő emailt azok az adózók, akiknél ez be van kapcsolva.", "minimum": 1, "maximum": 30, "example": 7 }, "email_alias": { "type": "string", "description": "A kiküldött levelek feladóneve; nem lehet email-cím. Üresen az alapértelmezett feladónév marad.", "nullable": true, "maxLength": 255, "example": "Kiss Könyvelőiroda" }, "reply_to_email": { "type": "string", "description": "A rendszer által kiküldött levelek válaszcíme: az adózó „Válasz” gombja erre a címre küld.", "format": "email", "maxLength": 255, "example": "iroda@kiss.hu" }, "payment_obligation_notification_days_before_due": { "type": "array", "description": "Hány nappal a fizetési kötelezettség esedékessége előtt menjen emlékeztető email az adózónak; több nap is megadható. Üres lista vagy `null`: nincs emlékeztető. A rendszer az ismétlődéseket kiszűri és csökkenő sorrendbe rendezi.", "items": { "type": "integer", "minimum": 0, "maximum": 30 }, "nullable": true, "example": [ 7, 1 ] } }, "required": [ "tarhely_trustee_active_default", "upo_trustee_active_default", "mailbox_active_default", "summary_mail_interval_days", "trustee_debt_mail_interval_days", "reply_to_email" ] } } } }, "responses": { "200": { "description": "Sikeres művelet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Office" } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/profile": { "get": { "tags": [ "Saját profil" ], "summary": "Saját felhasználói adatok lekérdezése", "description": "A bejelentkezett felhasználó adatait adja vissza a jogosultságaival és az iroda csomagjának funkcióival együtt. Minden szerepkör hívhatja. A `trustees` mező itt nem szerepel.", "responses": { "200": { "description": "Sikeres művelet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" } } }, "put": { "tags": [ "Saját profil" ], "summary": "Saját felhasználói adatok módosítása", "description": "A bejelentkezett felhasználó nevét és telefonszámát módosítja; mindkettő kötelező. Az email-cím és a szerepkör itt nem módosítható. Minden szerepkör hívhatja. A válasz a frissített felhasználó.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Teljes név.", "maxLength": 255, "example": "Kiss Elemér" }, "phone": { "type": "string", "description": "Telefonszám.", "maxLength": 255, "example": "+36301234567" } }, "required": [ "name", "phone" ] } } } }, "responses": { "200": { "description": "Sikeres művelet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/change-password": { "post": { "tags": [ "Jelszócsere" ], "summary": "Jelszó megváltoztatása", "description": "A bejelentkezett felhasználó jelszavát cseréli; a jelenlegi jelszót is meg kell adni (hibás jelenlegi jelszó esetén 422). A meglévő hozzáférési tokenek és API-kulcsok érvényben maradnak. Minden szerepkör hívhatja.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "current_password": { "type": "string", "description": "A jelenlegi jelszó.", "format": "password" }, "new_password": { "type": "string", "description": "Az új jelszó, legalább 6 karakter.", "minLength": 6, "format": "password" } }, "required": [ "current_password", "new_password" ] } } } }, "responses": { "200": { "description": "Sikeres művelet, üres választörzzsel." }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/two-factor/enable": { "post": { "tags": [ "Kétfaktoros azonosítás" ], "summary": "Kétlépcsős azonosítás (2FA) bekapcsolása", "description": "Bekapcsolja a TOTP-alapú kétlépcsős azonosítást a bejelentkezett felhasználónál. A kliens generál egy 32 karakteres Base32 titkot, megjeleníti QR-kódként, a felhasználó beolvassa egy hitelesítő alkalmazással (pl. Google Authenticator), és az alkalmazás aktuális kódjával együtt elküldi. Hibás kód esetén 422, már bekapcsolt 2FA esetén 403. Ezután a `/login` a kódot is kéri. A titkot a rendszer titkosítva tárolja, és semmilyen válaszban nem adja vissza (csak a `User.two_factor_enabled` jelzi az állapotot).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "secret": { "type": "string", "description": "A kliens által generált TOTP-titok, pontosan 32 karakter (Base32: A–Z, 2–7).", "minLength": 32, "maxLength": 32, "example": "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567" }, "code": { "type": "string", "description": "A hitelesítő alkalmazás által a titokból számolt aktuális 6 jegyű kód (csak számjegy).", "pattern": "^[0-9]+$", "example": "123456" } }, "required": [ "secret", "code" ] } } } }, "responses": { "200": { "description": "Sikeres művelet, üres választörzzsel." }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/two-factor/disable": { "post": { "tags": [ "Kétfaktoros azonosítás" ], "summary": "Kétlépcsős azonosítás (2FA) kikapcsolása", "description": "Kikapcsolja a bejelentkezett felhasználó kétlépcsős azonosítását, és törli a tárolt titkot. Ha a 2FA nincs bekapcsolva, 403.", "responses": { "200": { "description": "Sikeres művelet, üres választörzzsel." }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" } } } }, "/users": { "get": { "tags": [ "Felhasználók" ], "summary": "Az iroda felhasználóinak listája", "description": "Az iroda összes felhasználóját (a meghívottakat is) adja vissza azonosító szerint növekvő sorrendben, a hozzájuk rendelt adózókkal (`trustees`). Lapozás nincs. Csak menedzser szerepkörrel hívható.", "responses": { "200": { "description": "Sikeres művelet.", "content": { "application/json": { "schema": { "type": "array", "description": "Felhasználók.", "items": { "$ref": "#/components/schemas/User" } } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" } } } }, "/users/{userId}": { "get": { "tags": [ "Felhasználók" ], "summary": "Felhasználó lekérdezése", "description": "Az iroda egy felhasználóját adja vissza a hozzá rendelt adózókkal (`trustees`). Más iroda felhasználójára 404. Csak menedzser szerepkörrel hívható.", "parameters": [ { "name": "userId", "in": "path", "required": true, "description": "A felhasználó azonosítója (csak a saját iroda felhasználója).", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Sikeres művelet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "tags": [ "Felhasználók" ], "summary": "Felhasználó módosítása", "description": "Az iroda egy felhasználójának adatait, szerepkörét és adózói jogosultságát módosítja. Minden mezőt el kell küldeni (kivéve `trustee_ids`); az email-cím nem módosítható. `trustee_permission: specified` esetén a `trustee_ids` lista lecseréli a hozzárendelt adózókat. A fő felhasználó szerepköre csak menedzser lehet (különben 403). Csak menedzser szerepkörrel hívható. A válasz a frissített felhasználó.", "parameters": [ { "name": "userId", "in": "path", "required": true, "description": "A felhasználó azonosítója (csak a saját iroda felhasználója).", "schema": { "type": "integer", "minimum": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Teljes név.", "maxLength": 255 }, "phone": { "type": "string", "description": "Telefonszám.", "maxLength": 255 }, "role": { "type": "string", "description": "Szerepkör. `manager` – menedzser: az iroda minden beállítását, felhasználóit, számláit és előfizetését kezeli; `accountant` – könyvelő: az adózókkal, üzenetekkel, bevallásokkal dolgozik, az iroda beállításaihoz, a felhasználókhoz és a számlákhoz nem fér hozzá; `trustee` – adózó: az iroda ügyfele, a hozzá rendelt adózók adatait jellemzően csak olvashatja, ügyfélkapus beléptetőt nem használhat.", "enum": [ "manager", "accountant", "trustee" ] }, "can_login_portal": { "type": "boolean", "description": "Használhatja-e a felhasználó az ügyfélkapus beléptetőt (KAÜ-belépés az adózó nevében). Adózó szerepkörnél a beléptető ettől függetlenül nem elérhető." }, "trustee_permission": { "type": "string", "description": "Mely adózókhoz fér hozzá a felhasználó. `all` – az iroda összes adózójához; `specified` – csak a `trustee_ids`-ben kijelölt adózókhoz (és az azokhoz tartozó üzenetekhez, bevallásokhoz stb.).", "enum": [ "all", "specified" ] }, "trustee_ids": { "type": "array", "description": "A felhasználóhoz rendelt adózók azonosítói; csak `trustee_permission: specified` esetén számít, `all` esetén a hozzárendelés törlődik. Olyan azonosító, amely nem az iroda (nem törölt) ügyfélkapuihoz tartozó adózóé, hibaüzenet nélkül kimarad.", "items": { "type": "integer", "minimum": 1 }, "nullable": true, "example": [ 12, 34 ] } }, "required": [ "name", "phone", "role", "can_login_portal", "trustee_permission" ] } } } }, "responses": { "200": { "description": "Sikeres művelet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } }, "delete": { "tags": [ "Felhasználók" ], "summary": "Felhasználó törlése", "description": "Törli az iroda egy felhasználóját; a felhasználó ezután nem tud belépni. Más felhasználót menedzser szerepkörrel lehet törölni. Saját magát bármely szerepkör törölheti, de csak akkor, ha ő az iroda egyetlen felhasználója (különben 403). Az iroda utolsó felhasználójának törlésével az iroda is megszűnik; fizetős csomagnál ilyenkor elszámoló számla készül az addig eltelt időszakról.", "parameters": [ { "name": "userId", "in": "path", "required": true, "description": "A felhasználó azonosítója (csak a saját iroda felhasználója).", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Sikeres művelet, üres választörzzsel." }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/users/invite": { "post": { "tags": [ "Felhasználók" ], "summary": "Felhasználó meghívása", "description": "Új felhasználót hív meg az irodába: létrehozza meghívott (`invited`) állapotban, és meghívó emailt küld neki a regisztrációs linkkel (lásd `/invitation-register`). Az email-cím a teljes rendszerben egyedi kell legyen. Menedzser szerepkör és több felhasználót engedő (Prémium) csomag kell hozzá, különben 403.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Teljes név.", "maxLength": 255, "example": "Nagy Kálmán" }, "email": { "type": "string", "description": "Email-cím; erre megy a meghívó, és ez lesz a belépési azonosító.", "format": "email", "maxLength": 255, "example": "kalman@nagy.hu" }, "phone": { "type": "string", "description": "Telefonszám.", "maxLength": 255, "example": "+36207654321" }, "role": { "type": "string", "description": "Szerepkör. `manager` – menedzser: az iroda minden beállítását, felhasználóit, számláit és előfizetését kezeli; `accountant` – könyvelő: az adózókkal, üzenetekkel, bevallásokkal dolgozik, az iroda beállításaihoz, a felhasználókhoz és a számlákhoz nem fér hozzá; `trustee` – adózó: az iroda ügyfele, a hozzá rendelt adózók adatait jellemzően csak olvashatja, ügyfélkapus beléptetőt nem használhat.", "enum": [ "manager", "accountant", "trustee" ] }, "can_login_portal": { "type": "boolean", "description": "Használhatja-e a felhasználó az ügyfélkapus beléptetőt (KAÜ-belépés az adózó nevében). Adózó szerepkörnél a beléptető ettől függetlenül nem elérhető." }, "trustee_permission": { "type": "string", "description": "Mely adózókhoz fér hozzá a felhasználó. `all` – az iroda összes adózójához; `specified` – csak a `trustee_ids`-ben kijelölt adózókhoz (és az azokhoz tartozó üzenetekhez, bevallásokhoz stb.).", "enum": [ "all", "specified" ] }, "trustee_ids": { "type": "array", "description": "A felhasználóhoz rendelt adózók azonosítói; csak `trustee_permission: specified` esetén számít, `all` esetén a hozzárendelés törlődik. Olyan azonosító, amely nem az iroda (nem törölt) ügyfélkapuihoz tartozó adózóé, hibaüzenet nélkül kimarad.", "items": { "type": "integer", "minimum": 1 }, "nullable": true, "example": [ 12, 34 ] } }, "required": [ "name", "email", "phone", "role", "can_login_portal", "trustee_permission" ] } } } }, "responses": { "200": { "description": "A meghívó elküldve, üres választörzzsel." }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/users/{userId}/resend-invite": { "post": { "tags": [ "Felhasználók" ], "summary": "Meghívó újraküldése", "description": "Újra elküldi a meghívó emailt egy még meghívott (`invited`) állapotú felhasználónak. Már regisztrált felhasználónál, illetve meghívási jog (menedzser szerepkör és Prémium csomag) hiányában 403; más iroda felhasználójára 404.", "parameters": [ { "name": "userId", "in": "path", "required": true, "description": "A felhasználó azonosítója (csak a saját iroda felhasználója).", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "A meghívó elküldve, üres választörzzsel." }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/users/list-all-trustees": { "get": { "tags": [ "Felhasználók" ], "summary": "Adózók listája a felhasználói jogosultságok beállításához", "description": "Az iroda azon adózóit adja vissza név szerint rendezve (aktívakat és inaktívakat is), amelyeket a hívó felhasználó láthat: teljes adózói jogú felhasználónak az összeset, kijelölt adózós (`specified`) felhasználónak csak a hozzá rendelteket. A felhasználók `trustee_ids` mezőjének kitöltéséhez használható. Minden szerepkör hívhatja; lapozás nincs.", "responses": { "200": { "description": "Sikeres művelet.", "content": { "application/json": { "schema": { "type": "array", "description": "Adózók.", "items": { "$ref": "#/components/schemas/Trustee" } } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" } } } }, "/users/download-import-sample": { "get": { "tags": [ "Felhasználók" ], "summary": "Felhasználó-import mintafájl letöltése", "description": "Excel-mintafájlt ad a felhasználók tömeges felviteléhez (`felhasznalo_import_minta.xlsx`). Oszlopai: Név, Email, Telefonszám, Jogkör (`menedzser` vagy `könyvelő`), két példasorral.", "responses": { "200": { "description": "Az Excel-fájl.", "content": { "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" } } } }, "/users/import": { "post": { "tags": [ "Felhasználók" ], "summary": "Felhasználók importálása fájlból", "description": "Felhasználókat visz fel vagy frissít a mintafájl szerkezetű táblázatból. Az email-cím azonosít: ha az irodában már van ilyen felhasználó, a neve, telefonszáma és szerepköre frissül; ha nincs, meghívott felhasználóként jön létre (minden adózóhoz hozzáféréssel, beléptető-joggal), és meghívó emailt kap. Másik iroda felhasználójának címe hibát ad. A fájl egy egységként fut: bármely sor hibájánál semmi nem mentődik. Soronként a módosítási, illetve meghívási jog (menedzser szerepkör, új felhasználónál Prémium csomag is) kell, különben 403.", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "import_file" ], "properties": { "import_file": { "type": "string", "format": "binary", "description": "A kitöltött táblázat (xls, xlsx, csv vagy txt). Az első sor a fejléc (Név, Email, Telefonszám, Jogkör)." } } } } } }, "responses": { "200": { "description": "Az import lefutott, üres választörzzsel." }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/api-keys": { "get": { "tags": [ "API-kulcsok" ], "summary": "Saját API-kulcsok listája", "description": "A bejelentkezett felhasználó API-kulcsait adja vissza, a legújabbal kezdve. A kulcs titkos értékét nem tartalmazza. A bejelentkezéssel kapott tokenek nem szerepelnek a listában. Minden szerepkör hívhatja.", "responses": { "200": { "description": "Sikeres művelet.", "content": { "application/json": { "schema": { "type": "array", "description": "API-kulcsok.", "items": { "$ref": "#/components/schemas/ApiKey" } } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" } } }, "post": { "tags": [ "API-kulcsok" ], "summary": "API-kulcs létrehozása", "description": "Új API-kulcsot hoz létre a bejelentkezett felhasználónak, saját rendszerek (pl. irodai integráció) bekötéséhez. A kulcs a felhasználó nevében, az ő szerepkörével és adózói jogosultságával fér hozzá az API-hoz; nem jár le, amíg nem törlik. A kulcsot `Authorization: Bearer ` fejlécben kell küldeni. A titkos értéket csak ez a válasz tartalmazza, később nem kérhető le. Minden szerepkör hívhatja.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "A kulcs megnevezése (pl. melyik rendszer használja).", "maxLength": 255, "example": "Irodai integráció" } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "Sikeres művelet.", "content": { "application/json": { "schema": { "type": "object", "description": "Az új kulcs.", "properties": { "token": { "type": "string", "description": "Az API-kulcs teljes értéke „{azonosító}|{titok}” alakban. Csak itt látható.", "example": "124|ZyXwVuTsRqPoNmLkJiHgFeDcBa9876543210zyxw" } }, "required": [ "token" ] } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/api-keys/{id}": { "get": { "tags": [ "API-kulcsok" ], "summary": "API-kulcs lekérdezése", "description": "A bejelentkezett felhasználó egy API-kulcsának adatait adja vissza (a titkos érték nélkül). Más kulcsára 404.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Az API-kulcs azonosítója (csak a saját kulcsok közül).", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Sikeres művelet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKey" } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "tags": [ "API-kulcsok" ], "summary": "API-kulcs törlése (visszavonása)", "description": "Véglegesen visszavonja a bejelentkezett felhasználó egy API-kulcsát; a kulccsal ezután nem lehet hívni az API-t. Más kulcsára 404.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Az API-kulcs azonosítója (csak a saját kulcsok közül).", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Sikeres művelet, üres választörzzsel." }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/customer-portals": { "get": { "tags": [ "Ügyfélkapuk" ], "summary": "Ügyfélkapuk listázása", "description": "Az iroda összes ügyfélkapuját adja vissza azonosító szerint rendezve, lapozás nélkül, a frissítések állapotával együtt. „Kijelölt adózós\" felhasználó csak azokat az ügyfélkapukat látja, amelyeknek nincs adózója, vagy van olyan adózója, amely hozzá van rendelve. Szerepkör: menedzser vagy könyvelő (adózó szerepkörrel 403). A jelszót és a 2FA-titkot a válasz nem tartalmazza.", "responses": { "200": { "description": "Az ügyfélkapuk listája.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerPortal" } } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" } } }, "post": { "tags": [ "Ügyfélkapuk" ], "summary": "Ügyfélkapu létrehozása", "description": "Új ügyfélkaput vesz fel az irodába belépési adatok nélkül; a belépést utána a POST /customer-portal-connections végponttal kell összekapcsolni. Csak menedzser hívhatja; az előfizetési csomag korlátozhatja az ügyfélkapuk számát (ilyenkor 403, az indoklás a `message`-ben).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255, "description": "Az ügyfélkapu megnevezése.", "example": "Kiss Elemér" }, "active": { "type": "boolean", "description": "Aktív-e az ügyfélkapu." }, "emails": { "type": "array", "nullable": true, "items": { "type": "string", "format": "email" }, "description": "Értesítési e-mail címek (lásd CustomerPortal.emails). Hiányzó vagy null érték üres listát jelent.", "example": [ "elemer@kiss.hu" ] }, "note": { "type": "string", "nullable": true, "maxLength": 255, "description": "Belső megjegyzés." } }, "required": [ "name", "active" ] } } } }, "responses": { "200": { "description": "A létrehozott ügyfélkapu.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerPortal" } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/customer-portals/{customerPortalId}": { "get": { "tags": [ "Ügyfélkapuk" ], "summary": "Ügyfélkapu megtekintése", "description": "Egy ügyfélkapu adatai és a frissítések állapota (portálonként: utolsó és következő frissítés, összekapcsolás, azonnal indítható-e, futó frissítés haladása). A jelszót és a 2FA-titkot a válasz nem tartalmazza, csak az aktuális 6 jegyű kódot. Szerepkör: menedzser vagy könyvelő; más iroda vagy nem látható ügyfélkapu esetén 404.", "parameters": [ { "name": "customerPortalId", "in": "path", "required": true, "description": "Az ügyfélkapu azonosítója.", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Az ügyfélkapu.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerPortal" } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "tags": [ "Ügyfélkapuk" ], "summary": "Ügyfélkapu módosítása", "description": "Az ügyfélkapu megnevezésének, aktív állapotának, értesítési címeinek és megjegyzésének módosítása. Teljes csere: a kihagyott `emails`/`note` üres lesz. A belépési adatok itt nem módosíthatók (azokhoz új összekapcsolás kell: POST /customer-portal-connections). Az ügyfélkapu inaktívvá tétele megszünteti az élő portál-összekapcsolásokat. Csak menedzser hívhatja.", "parameters": [ { "name": "customerPortalId", "in": "path", "required": true, "description": "Az ügyfélkapu azonosítója.", "schema": { "type": "integer", "minimum": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255, "description": "Az ügyfélkapu megnevezése.", "example": "Kiss Elemér" }, "active": { "type": "boolean", "description": "Aktív-e az ügyfélkapu." }, "emails": { "type": "array", "nullable": true, "items": { "type": "string", "format": "email" }, "description": "Értesítési e-mail címek (lásd CustomerPortal.emails). Hiányzó vagy null érték üres listát jelent.", "example": [ "elemer@kiss.hu" ] }, "note": { "type": "string", "nullable": true, "maxLength": 255, "description": "Belső megjegyzés." } }, "required": [ "name", "active" ] } } } }, "responses": { "200": { "description": "A módosított ügyfélkapu.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerPortal" } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } }, "delete": { "tags": [ "Ügyfélkapuk" ], "summary": "Ügyfélkapu törlése", "description": "Törli az ügyfélkaput; ezután sem az ügyfélkapu, sem a hozzá tartozó adózók, cégkapuk és üzenetek nem jelennek meg, és frissítés sem fut rajta. Csak menedzser hívhatja.", "parameters": [ { "name": "customerPortalId", "in": "path", "required": true, "description": "Az ügyfélkapu azonosítója.", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Sikeres művelet, üres választörzs." }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/customer-portals/{customerPortalId}/instant-tarhely-run": { "post": { "tags": [ "Ügyfélkapuk" ], "summary": "Tárhely azonnali frissítése (elavult)", "description": "Elavult: ugyanaz, mint a POST /customer-portals/{customerPortalId}/instant-portal-run `portal=tarhely` értékkel; helyette azt érdemes használni. A tárhely-üzenetek frissítését a lehető leghamarabbra ütemezi.", "parameters": [ { "name": "customerPortalId", "in": "path", "required": true, "description": "Az ügyfélkapu azonosítója.", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Sikeres művelet, üres választörzs." }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" }, "404": { "$ref": "#/components/responses/NotFound" } }, "deprecated": true } }, "/customer-portals/{customerPortalId}/instant-portal-run": { "post": { "tags": [ "Ügyfélkapuk" ], "summary": "Ügyfélkapu azonnali frissítése egy portálon", "description": "A megadott portál frissítését a lehető leghamarabbra ütemezi (a frissítés a háttérben fut, a válasz nem várja meg). Ha a frissítés nem indítható (az ügyfélkapu inaktív, épp fut, nincs összekapcsolva a portállal, az előfizetési csomag nem tartalmazza az azonnali frissítést vagy a portált, ASP-nél a napi korlát), 403 a magyar indoklással; ugyanezt előre a CustomerPortal `portals.{portal}.instant_run` mezője mutatja. M2M-nél aktív M2M API kulcs nélkül a kérés hiba nélkül, de hatás nélkül tér vissza. Szerepkör: menedzser vagy könyvelő.", "parameters": [ { "name": "customerPortalId", "in": "path", "required": true, "description": "Az ügyfélkapu azonosítója.", "schema": { "type": "integer", "minimum": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "portal": { "type": "string", "enum": [ "tarhely", "upo", "asp", "m2m" ], "description": "A frissítendő portál: tarhely = tárhely-üzenetek; upo = NAV Online Ügyfélportál (bevallások, folyószámla, foglalkoztatottak…); asp = önkormányzati adóügyek; m2m = NAV M2M-kapcsolat (csak aktív M2M API kulccsal)." } }, "required": [ "portal" ] } } } }, "responses": { "200": { "description": "Sikeres művelet, üres választörzs." }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/customer-portals/{customerPortalId}/get-two-factor-authentication-secret": { "post": { "tags": [ "Ügyfélkapuk" ], "summary": "Ügyfélkapu+ hitelesítő kulcs lekérdezése", "description": "Kiadja az ügyfélkapuhoz tárolt Ügyfélkapu+ hitelesítő kulcsot (2FA-titok), hogy egy másik hitelesítő alkalmazásba is felvehető legyen. Ez az EGYETLEN végpont, amely a kulcsot visszaadja, és csak kettős megerősítéssel: a hívó felhasználó saját KapuSegéd-jelszava és az ügyfélkapu tárolt jelszava kell hozzá (bármelyik hibás → 422). Csak Ügyfélkapu+ hitelesítő alkalmazással összekapcsolt ügyfélkapunál működik (más belépési módnál 403). Az ügyfélkapu jelszavát a válasz nem adja vissza. Szerepkör: menedzser vagy könyvelő.", "parameters": [ { "name": "customerPortalId", "in": "path", "required": true, "description": "Az ügyfélkapu azonosítója.", "schema": { "type": "integer", "minimum": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kapuseged_password": { "type": "string", "format": "password", "description": "A hívó felhasználó jelenlegi KapuSegéd-jelszava." }, "customer_portal_password": { "type": "string", "format": "password", "description": "Az ügyfélkapu jelszava; egyeznie kell a tárolttal." } }, "required": [ "kapuseged_password", "customer_portal_password" ] } } } }, "responses": { "200": { "description": "A hitelesítő kulcs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "two_factor_authentication_secret": { "type": "string", "description": "A hitelesítő kulcs (Base32 szöveg, 16 karakter), amelyből a 6 jegyű kódok számolhatók.", "example": "JBSWY3DPEHPK3PXP" }, "qr_code": { "type": "string", "description": "otpauth:// URI a kulccsal; QR-kódként megjelenítve hitelesítő alkalmazással beolvasható.", "example": "otpauth://totp/felhasznalo@ugyfelkapu.gov.hu?secret=JBSWY3DPEHPK3PXP" } } } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/customer-portals/{customerPortalId}/login": { "post": { "tags": [ "Ügyfélkapuk" ], "summary": "KAÜ-belépés (csak asztali alkalmazásból)", "description": "Az ügyfélkapuval való belépést segíti egy kormányzati portálra. Csak a KapuSegéd asztali alkalmazásából érhető el (más kliensből 403). Feltétele a KAÜ-beléptető jogosultság (menedzser vagy könyvelő) és Ügyfélkapu+ vagy DÁP belépési mód.", "parameters": [ { "name": "customerPortalId", "in": "path", "required": true, "description": "Az ügyfélkapu azonosítója.", "schema": { "type": "integer", "minimum": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "portal": { "type": "string", "description": "A cél-portál azonosítója (az asztali alkalmazás listájából).", "example": "tarhely" } }, "required": [ "portal" ] } } } }, "responses": { "200": { "description": "Az asztali alkalmazás által feldolgozott belépési leírás.", "content": { "application/json": { "schema": { "type": "object", "description": "Csak az asztali alkalmazás belső használatára.", "properties": { "actions": { "type": "array", "items": { "type": "object" } }, "intervals": { "type": "array", "items": { "type": "object" } } } } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/customer-portals/{customerPortalId}/set-m2m-api-key": { "post": { "tags": [ "Ügyfélkapuk" ], "summary": "NAV M2M API kulcs megadása és aktiválása", "description": "A NAV-tól (a tárhelyre) kapott M2M API kulcsot aktiválja a NAV-nál, és siker esetén eltárolja az ügyfélkapuhoz; ezután a rendszer az M2M-kapcsolaton is frissíti az adatokat. A kulcs csak teljes siker esetén tárolódik. Ha a NAV elutasítja a kulcsot, vagy az lejárt / már aktivált, 422 a `m2m_api_key` mezőn magyar indoklással. Ha már aktív M2M-kapcsolat van, 403 (előbb törölni kell). A kulcsot a válasz nem adja vissza. Csak menedzser hívhatja; percenkénti kéréskorláttal.", "parameters": [ { "name": "customerPortalId", "in": "path", "required": true, "description": "Az ügyfélkapu azonosítója.", "schema": { "type": "integer", "minimum": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "m2m_api_key": { "type": "string", "maxLength": 255, "description": "A NAV által kiadott M2M API kulcs, változtatás nélkül bemásolva (a láthatatlan karaktereket, szóközöket a rendszer eltávolítja)." } }, "required": [ "m2m_api_key" ] } } } }, "responses": { "200": { "description": "Az ügyfélkapu, `portals.m2m.status = active` értékkel.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerPortal" } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "description": "Túl sok kérés rövid időn belül (a végpont percenkénti kéréskorláttal védett). Kis várakozás után újrapróbálható.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } } } } }, "/customer-portals/{customerPortalId}/delete-m2m-api-key": { "post": { "tags": [ "Ügyfélkapuk" ], "summary": "NAV M2M API kulcs törlése", "description": "Törli az ügyfélkapu M2M API kulcsát; az M2M-frissítés ezzel leáll. Csak aktív M2M-kapcsolatnál hívható (egyébként 403). Csak menedzser hívhatja; percenkénti kéréskorláttal.", "parameters": [ { "name": "customerPortalId", "in": "path", "required": true, "description": "Az ügyfélkapu azonosítója.", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Az ügyfélkapu, `portals.m2m.status = null` értékkel.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerPortal" } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "description": "Túl sok kérés rövid időn belül (a végpont percenkénti kéréskorláttal védett). Kis várakozás után újrapróbálható.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } } } } }, "/customer-portals/instant-portal-run-on-all": { "post": { "tags": [ "Ügyfélkapuk" ], "summary": "Összes ügyfélkapu azonnali frissítése egy portálon", "description": "A felhasználó által látható összes ügyfélkapun ütemezi a megadott portál azonnali frissítését. Azokat az ügyfélkapukat, amelyeken a frissítés nem indítható (lásd instant-portal-run), hiba nélkül kihagyja; a válasz nem mondja meg, melyik indult el. Szerepkör: menedzser vagy könyvelő (más szerepkörnél minden ügyfélkapu kimarad).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "portal": { "type": "string", "enum": [ "tarhely", "upo", "asp", "m2m" ], "description": "A frissítendő portál: tarhely = tárhely-üzenetek; upo = NAV Online Ügyfélportál (bevallások, folyószámla, foglalkoztatottak…); asp = önkormányzati adóügyek; m2m = NAV M2M-kapcsolat (csak aktív M2M API kulccsal)." } }, "required": [ "portal" ] } } } }, "responses": { "200": { "description": "Sikeres művelet, üres választörzs." }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/customer-portals/download-import-sample": { "get": { "tags": [ "Ügyfélkapuk" ], "summary": "Ügyfélkapu-import mintafájl letöltése", "description": "Excel-mintafájl a tömeges ügyfélkapu-felvételhez (oszlopok: Név, Aktív, Értesítési emailek, Megjegyzés), példasorokkal.", "responses": { "200": { "description": "Az .xlsx mintafájl.", "content": { "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" } } } }, "/customer-portals/import": { "post": { "tags": [ "Ügyfélkapuk" ], "summary": "Ügyfélkapuk importálása", "description": "Excel- vagy CSV-fájlból tömegesen vesz fel ügyfélkapukat (a mintafájl oszlopai szerint); minden sor ÚJ ügyfélkaput hoz létre, meglévőt nem módosít. Az ügyfélkapukat utána egyenként össze kell kapcsolni. Soronként menedzseri jogosultság és a csomag ügyfélkapu-korlátja kell (különben 403); hibás sorok esetén 422.", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "import_file" ], "properties": { "import_file": { "type": "string", "format": "binary", "description": "A kitöltött fájl (xls, xlsx, csv vagy txt)." } } } } } }, "responses": { "200": { "description": "Sikeres művelet, üres választörzs." }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/customer-portal-connections": { "post": { "tags": [ "Ügyfélkapu-összekapcsolás" ], "summary": "Ügyfélkapu-összekapcsolás indítása", "description": "Elindítja egy ügyfélkapu összekapcsolását a megadott belépési adatokkal: a rendszer belép a KAÜ-n, és siker esetén a belépési adatokat (mód, felhasználónév, jelszó, hitelesítő kulcs) az ügyfélkapura menti. A folyamat a háttérben fut; az állapotot a GET /customer-portal-connections/{customerPortalConnectionId} lekérdezésével kell követni, Ügyfélkapu+ e-mailes kódnál a kódot a set-confirmation-code végponton kell megadni. Ha az ügyfélkapu inaktív, a hívás aktívvá teszi. Ügyfélkapu+ módnál a `password` (és hitelesítő alkalmazásnál a `two_factor_authentication_secret`) elhagyható, ha az ügyfélkapuhoz már van tárolt érték — ilyenkor azt használja. A válasz a belépési adatokat nem tartalmazza. Csak menedzser hívhatja.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customer_portal_id": { "type": "integer", "description": "Az iroda (nem törölt) ügyfélkapujának azonosítója." }, "login_type": { "type": "string", "enum": [ "ugyfelkapu_plusz_authenticator", "ugyfelkapu_plusz_email", "dap" ], "description": "A belépés módja: ugyfelkapu_plusz_authenticator = Ügyfélkapu+ hitelesítő alkalmazással; ugyfelkapu_plusz_email = Ügyfélkapu+ e-mailes kóddal; dap = DÁP mobilalkalmazással (felhasználónév és jelszó nélkül)." }, "username": { "type": "string", "nullable": true, "maxLength": 255, "description": "Ügyfélkapus felhasználónév. Kötelező mindkét Ügyfélkapu+ módnál; DÁP-nál figyelmen kívül marad." }, "password": { "type": "string", "format": "password", "nullable": true, "maxLength": 255, "description": "Ügyfélkapus jelszó. Ügyfélkapu+ módnál kötelező, kivéve ha az ügyfélkapuhoz már van tárolt jelszó; DÁP-nál figyelmen kívül marad. A válasz soha nem adja vissza." }, "two_factor_authentication_secret": { "type": "string", "nullable": true, "minLength": 16, "maxLength": 16, "description": "Az Ügyfélkapu+ hitelesítő kulcs (a QR-kód mögötti 16 karakteres Base32 titok). Hitelesítő alkalmazásos módnál kötelező, kivéve ha az ügyfélkapuhoz már van tárolt kulcs; más módnál figyelmen kívül marad. A válasz soha nem adja vissza.", "example": "JBSWY3DPEHPK3PXP" } }, "required": [ "customer_portal_id", "login_type" ] } } } }, "responses": { "200": { "description": "Az elindított folyamat (`status = pending`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerPortalConnection" } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/customer-portal-connections/{customerPortalConnectionId}": { "get": { "tags": [ "Ügyfélkapu-összekapcsolás" ], "summary": "Ügyfélkapu-összekapcsolás állapota", "description": "Egy összekapcsolási folyamat aktuális állapota (ezt kell ismételten lekérdezni, amíg `completed` vagy `failed` nem lesz). Csak a felhasználó által látható ügyfélkapuk folyamatai érhetők el, más esetben 404. A válasz a belépési adatokat nem tartalmazza.", "parameters": [ { "name": "customerPortalConnectionId", "in": "path", "required": true, "description": "Az összekapcsolási folyamat azonosítója.", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Az összekapcsolási folyamat.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerPortalConnection" } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/customer-portal-connections/{customerPortalConnectionId}/set-confirmation-code": { "post": { "tags": [ "Ügyfélkapu-összekapcsolás" ], "summary": "Megerősítő kód megadása összekapcsoláskor", "description": "Ügyfélkapu+ e-mailes kódos összekapcsolásnál az e-mailben kapott 6 jegyű kód megadása. Csak `ugyfelkapu_plusz_email` módú, `confirmation` állapotú folyamatnál hívható (egyébként 403); a folyamat ezután `in_progress` állapotba lép.", "parameters": [ { "name": "customerPortalConnectionId", "in": "path", "required": true, "description": "Az összekapcsolási folyamat azonosítója.", "schema": { "type": "integer", "minimum": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "confirmation_code": { "type": "string", "pattern": "^\\d{6}$", "minLength": 6, "maxLength": 6, "description": "Az e-mailben kapott 6 számjegyű kód (az előtag nélkül).", "example": "123456" } }, "required": [ "confirmation_code" ] } } } }, "responses": { "200": { "description": "A folyamat új állapota.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerPortalConnection" } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/mailboxes": { "get": { "tags": [ "Cégkapuk" ], "summary": "Cégkapuk listázása", "description": "A felhasználó által látható ügyfélkapuk összes cégkapuja (tárhely-postafiókja) azonosító szerint, lapozás nélkül, a beágyazott ügyfélkapu alapadataival. Szerepkör: menedzser vagy könyvelő.", "responses": { "200": { "description": "A cégkapuk listája.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Mailbox" } } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" } } } }, "/mailboxes/{mailboxId}": { "get": { "tags": [ "Cégkapuk" ], "summary": "Cégkapu megtekintése", "description": "Egy cégkapu adatai a beágyazott ügyfélkapu alapadataival. Szerepkör: menedzser vagy könyvelő; nem látható cégkapunál 404.", "parameters": [ { "name": "mailboxId", "in": "path", "required": true, "description": "A cégkapu azonosítója.", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "A cégkapu.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Mailbox" } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "tags": [ "Cégkapuk" ], "summary": "Cégkapu módosítása", "description": "A cégkapu aktív állapotának és értesítési címeinek módosítása (más mező nem módosítható). Teljes csere: a kihagyott `emails` üres lesz. Csak menedzser hívhatja.", "parameters": [ { "name": "mailboxId", "in": "path", "required": true, "description": "A cégkapu azonosítója.", "schema": { "type": "integer", "minimum": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "active": { "type": "boolean", "description": "Aktív-e a cégkapu." }, "emails": { "type": "array", "nullable": true, "items": { "type": "string", "format": "email" }, "description": "Értesítési e-mail címek (lásd Mailbox.emails). Hiányzó vagy null érték üres listát jelent.", "example": [ "iroda@alfa.hu" ] } }, "required": [ "active" ] } } } }, "responses": { "200": { "description": "A módosított cégkapu.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Mailbox" } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/message-statuses": { "get": { "tags": [ "Üzenetstátuszok" ], "summary": "Üzenet-státuszok listázása", "description": "Az iroda tárhely-üzenet státuszai a beállított sorrendben, lapozás nélkül. Minden szerepkör hívhatja.", "responses": { "200": { "description": "A státuszok listája.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/MessageStatus" } } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" } } }, "post": { "tags": [ "Üzenetstátuszok" ], "summary": "Üzenet-státusz létrehozása", "description": "Új státuszt vesz fel a lista végére (nem lezárt státuszként). Csak menedzser hívhatja.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255, "description": "A státusz neve.", "example": "Ügyfélre vár" }, "color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$", "description": "A státusz színe #RRGGBB alakban (a kettőskereszt kötelező).", "example": "#FFCC00" } }, "required": [ "name", "color" ] } } } }, "responses": { "200": { "description": "A létrehozott státusz.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageStatus" } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/message-statuses/{messageStatusId}": { "get": { "tags": [ "Üzenetstátuszok" ], "summary": "Üzenet-státusz megtekintése", "description": "Egy státusz adatai. Minden szerepkör hívhatja; más iroda státuszánál 404.", "parameters": [ { "name": "messageStatusId", "in": "path", "required": true, "description": "Az üzenet-státusz azonosítója.", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "A státusz.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageStatus" } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "tags": [ "Üzenetstátuszok" ], "summary": "Üzenet-státusz módosítása", "description": "A státusz nevének és színének módosítása (mindkettő kötelező). A lezárt jelleg nem módosítható. Csak menedzser hívhatja.", "parameters": [ { "name": "messageStatusId", "in": "path", "required": true, "description": "Az üzenet-státusz azonosítója.", "schema": { "type": "integer", "minimum": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255, "description": "A státusz neve.", "example": "Ügyfélre vár" }, "color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$", "description": "A státusz színe #RRGGBB alakban (a kettőskereszt kötelező).", "example": "#FFCC00" } }, "required": [ "name", "color" ] } } } }, "responses": { "200": { "description": "A módosított státusz.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageStatus" } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } }, "delete": { "tags": [ "Üzenetstátuszok" ], "summary": "Üzenet-státusz törlése", "description": "Törli a státuszt; az ilyen státuszú üzenetek és szabálybeállítások az iroda lezárt státuszába kerülnek. A lezárt státusz nem törölhető (403). Csak menedzser hívhatja.", "parameters": [ { "name": "messageStatusId", "in": "path", "required": true, "description": "Az üzenet-státusz azonosítója.", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Sikeres művelet, üres választörzs." }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/message-statuses/update-order": { "post": { "tags": [ "Üzenetstátuszok" ], "summary": "Üzenet-státuszok sorrendjének beállítása", "description": "Beállítja a státuszok megjelenítési sorrendjét. Az iroda MINDEN státuszának azonosítóját meg kell adni, pontosan egyszer, a kívánt sorrendben (hiányzó, ismétlődő vagy idegen azonosító → 422). Csak menedzser hívhatja.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "message_status_ids": { "type": "array", "uniqueItems": true, "items": { "type": "integer" }, "description": "Az iroda összes státuszának azonosítója az új sorrendben.", "example": [ 3, 1, 2 ] } }, "required": [ "message_status_ids" ] } } } }, "responses": { "200": { "description": "Sikeres művelet, üres választörzs." }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/actions": { "get": { "tags": [ "Szabályok" ], "summary": "Szabálybeállítások listázása", "description": "Az iroda beállítása minden tárhely-szabályra (dokumentumtípusra), szabály-azonosító szerint, lapozás nélkül — a kikapcsolt szabályokkal együtt. A nem módosított szabály alapbeállítással szerepel (`updated_at = null`). A `document_id` mező a szabály kulcsa, ezt várja a POST /messages/search `valid_document` szűrője. Csak menedzser hívhatja.", "responses": { "200": { "description": "A szabálybeállítások listája.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Action" } } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" } } } }, "/actions/{actionId}": { "get": { "tags": [ "Szabályok" ], "summary": "Szabálybeállítás megtekintése", "description": "Az iroda beállítása egy szabályra (a nem módosítottnál az alapbeállítás). Ismeretlen szabály-azonosítónál 404. Csak menedzser hívhatja.", "parameters": [ { "name": "actionId", "in": "path", "required": true, "description": "A SZABÁLY azonosítója (a GET /actions lista `id` mezője).", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "A szabálybeállítás.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Action" } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "tags": [ "Szabályok" ], "summary": "Szabálybeállítás módosítása", "description": "Beállítja, mi történjen az iroda ÚJ tárhely-üzeneteivel ennél a szabálynál (státusz, elrejtés, letöltés, e-mailes kiküldés és címzettjei, szín, megjegyzés); a már meglévő üzeneteket nem érinti. Teljes csere: a kihagyott mezők null / false értéket kapnak. Ha a beállítás egyezik az alapbeállítással, az iroda eltérése megszűnik (`updated_at = null`). Azonnali kiküldés (`send_now`) csak olyan előfizetési csomagban állítható, amely engedi (különben 403). Csak menedzser hívhatja.", "parameters": [ { "name": "actionId", "in": "path", "required": true, "description": "A SZABÁLY azonosítója (a GET /actions lista `id` mezője).", "schema": { "type": "integer", "minimum": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "message_status_id": { "type": "integer", "description": "Az ilyen típusú új üzenet státusza; az iroda egyik státuszának azonosítója." }, "skip": { "type": "boolean", "description": "„Nem kell\": true = az ilyen üzenet nem jelenik meg, és nem történik vele semmi." }, "download_method": { "type": "string", "nullable": true, "enum": [ "download", "put_in_permanent_storage", null ], "description": "Mi történjen az ilyen üzenet fájljával. null = semmi (a rendszer nem tölti le); download = a rendszer letölti a fájlt (az üzenet ezzel a tárhelyen olvasottá válik); put_in_permanent_storage = a rendszer letölti és a tárhelyen tartós tárba helyezi." }, "send_method": { "type": "string", "nullable": true, "enum": [ "send_now", "send_later", null ], "description": "E-mailes kiküldés módja. null = nincs kiküldés; send_now = azonnal, amint a fájl letöltődött (csak olyan előfizetési csomagban állítható, amely engedi az azonnali küldést); send_later = később, összevont levélben." }, "send_to_customer_portal": { "type": "boolean", "nullable": true, "description": "Az ilyen üzenet menjen-e az ügyfélkapu értesítési címeire (CustomerPortal.emails). Hiányzó vagy null érték false-nak számít." }, "send_to_trustee": { "type": "boolean", "nullable": true, "description": "Menjen-e az adózó e-mail címeire. Hiányzó vagy null érték false-nak számít." }, "send_to_trustee_accountants": { "type": "boolean", "nullable": true, "description": "Menjen-e az adózó könyvelőinek címeire. Hiányzó vagy null érték false-nak számít." }, "send_to_trustee_payroll_accountants": { "type": "boolean", "nullable": true, "description": "Menjen-e az adózó bérszámfejtőinek címeire. Hiányzó vagy null érték false-nak számít." }, "send_to_trustee_tax_advisors": { "type": "boolean", "nullable": true, "description": "Menjen-e az adózó adótanácsadóinak címeire. Hiányzó vagy null érték false-nak számít." }, "send_to_mailboxes": { "type": "boolean", "nullable": true, "description": "Menjen-e a cégkapu értesítési címeire (Mailbox.emails). Hiányzó vagy null érték false-nak számít." }, "email_note": { "type": "string", "nullable": true, "maxLength": 65535, "description": "Megjegyzés a kiküldött e-mailben." }, "color": { "type": "string", "nullable": true, "pattern": "^#[0-9A-Fa-f]{6}$", "description": "Kiemelő szín #RRGGBB alakban, vagy null.", "example": "#FF9999" } }, "required": [ "message_status_id", "skip" ] } } } }, "responses": { "200": { "description": "A módosított szabálybeállítás.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Action" } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/actions/export": { "post": { "tags": [ "Szabályok" ], "summary": "Szabálybeállítások exportálása", "description": "Excel-fájlba exportálja az iroda beállítását az aktív szabályokra (szabálykulcs szerint). A fájl visszatölthető a POST /actions/import végponton. Kérés törzse nem kell. Csak menedzser hívhatja.", "responses": { "200": { "description": "Az .xlsx fájl.", "content": { "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" } } } }, "/actions/download-import-sample": { "get": { "tags": [ "Szabályok" ], "summary": "Szabály-import mintafájl letöltése", "description": "Excel-mintafájl a szabálybeállítások tömeges módosításához (oszlopok: Név, Nem kell, Státusz, Letöltés típusa, Email-ben kiküldés, Szín, Jegyzet, Küldés - Ügyfélkapu / Ügyfél / Könyvelő / Bérszámfejtő / Adótanácsadó / Cégkapu). Csak menedzser hívhatja.", "responses": { "200": { "description": "Az .xlsx mintafájl.", "content": { "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" } } } }, "/actions/import": { "post": { "tags": [ "Szabályok" ], "summary": "Szabálybeállítások importálása", "description": "Excel- vagy CSV-fájlból (pl. egy korábbi exportból) tömegesen állítja be a szabályokat. A sort a „Név\" oszlop (a szabály neve, kis- és nagybetűre nem érzékenyen; a korábbi nevek is) azonosítja; a már megszűnt szabály sora kimarad. A „Státusz\" az iroda egyik státuszának neve; a „Letöltés típusa\" értéke „letöltés\" vagy „tartósba\", az „Email-ben kiküldés\" értéke „azonnal\" vagy „reggel\" (azonnali kiküldést nem engedő csomagban az „azonnal\" is „reggel\" lesz). Ismeretlen szabálynév vagy státusz → 422. Csak menedzser hívhatja.", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "import_file" ], "properties": { "import_file": { "type": "string", "format": "binary", "description": "A kitöltött fájl (xls, xlsx, csv vagy txt)." } } } } } }, "responses": { "200": { "description": "Sikeres művelet, üres választörzs." }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/messages/{messageId}": { "get": { "tags": [ "Tárhely-üzenetek" ], "summary": "Tárhely-üzenet megtekintése", "description": "Egy tárhely-üzenet adatai a státusszal, az adózóval, a kapcsolódó bevallással és a továbbító e-mailekkel. Csak az aktív ügyfélkapuk aktív adózóinak megjelenített (szabály szerint nem elrejtett) üzenetei érhetők el; „kijelölt adózós\" felhasználónál csak a hozzá rendelt adózóké, és az előfizetési csomag korlátozhatja, milyen régi üzenetek láthatók. Nem elérhető üzenetnél 404. Minden szerepkör hívhatja.", "parameters": [ { "name": "messageId", "in": "path", "required": true, "description": "Az üzenet azonosítója.", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Az üzenet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "tags": [ "Tárhely-üzenetek" ], "summary": "Tárhely-üzenet módosítása", "description": "Az üzenet státuszának, letöltési kérésének és saját megjegyzésének módosítása. Teljes csere: a `message_status_id` kötelező, a kihagyott `download_method` / `user_note` null lesz. `download_method` megadásával a rendszer letölti az üzenet fájlját (ezzel az a tárhelyen olvasottá válik); ez nem lehetséges, ha a fájl már le van töltve vagy az üzenet 30 napnál régebben érkezett (403). Menedzser vagy könyvelő hívhatja.", "parameters": [ { "name": "messageId", "in": "path", "required": true, "description": "Az üzenet azonosítója.", "schema": { "type": "integer", "minimum": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "message_status_id": { "type": "integer", "description": "Az új státusz; az iroda egyik státuszának azonosítója." }, "download_method": { "type": "string", "nullable": true, "enum": [ "download", "put_in_permanent_storage", null ], "description": "Letöltési kérés: download = a rendszer letölti a fájlt; put_in_permanent_storage = letölti és tartós tárba helyezi; null = nincs kérés." }, "user_note": { "type": "string", "nullable": true, "maxLength": 255, "description": "Saját megjegyzés az üzenethez." } }, "required": [ "message_status_id" ] } } } }, "responses": { "200": { "description": "A módosított üzenet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/messages/search": { "post": { "tags": [ "Tárhely-üzenetek" ], "summary": "Tárhely-üzenetek keresése", "description": "Lapozott, szűrhető és rendezhető tárhely-üzenetlista. Csak az aktív ügyfélkapuk aktív adózóinak megjelenített (szabály szerint nem elrejtett) üzenetei érhetők el; „kijelölt adózós\" felhasználónál csak a hozzá rendelt adózóké, és az előfizetési csomag korlátozhatja, milyen régi üzenetek láthatók. Az IdomSoft BKSZ-üzenetek alapból kimaradnak (`show_idomsoft_bksz`). Minden szerepkör hívhatja.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "limit": { "type": "integer", "nullable": true, "minimum": 1, "maximum": 200, "description": "Lapméret (alapértelmezés: 200)." }, "page": { "type": "integer", "nullable": true, "minimum": 1, "description": "Lap sorszáma (alapértelmezés: 1)." }, "search": { "type": "string", "nullable": true, "description": "Szabad szavas keresés; minden szónak illeszkednie kell (részszó-egyezés) a dokumentumtípusra, leírásra, fájlnévre, feladóra, saját megjegyzésre, az adózó nevére / adószámára / adóazonosító jelére / megjegyzésére vagy a bevallás vonalkódjára. A cégforma-rövidítés a teljes formára is keres („Kft\" → „korlátolt felelősségű társaság\")." }, "order_column": { "type": "string", "nullable": true, "enum": [ "message_id", "download_method", "arrived_at", "sender_short_name", "tax_report_type", "created_at", "updated_at", "message_status_name", "legally_binding_deadline", null ], "description": "Rendezés oszlopa (alapértelmezés: arrived_at). message_id = tárhelybeli üzenet-azonosító; message_status_name = a státusz neve; legally_binding_deadline = jogerő napja. (A tax_report_type a kódban szerepel, de az üzeneteken nincs ilyen oszlop, lásd a megjegyzéseket.)" }, "order_direction": { "type": "string", "nullable": true, "enum": [ "asc", "desc", null ], "description": "Rendezés iránya (alapértelmezés: desc)." }, "customer_portal_id": { "type": "integer", "nullable": true, "minimum": 1, "description": "Csak ennek az ügyfélkapunak az üzenetei." }, "trustee_id": { "type": "integer", "nullable": true, "minimum": 1, "description": "Csak ennek az adózónak az üzenetei." }, "arrived_at_min": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 1893456000, "nullable": true, "description": "Érkezés (arrived_at) legkorábban, unix időbélyeg." }, "arrived_at_max": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 1893456000, "nullable": true, "description": "Érkezés legkésőbb, unix időbélyeg." }, "created_at_min": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 1893456000, "nullable": true, "description": "Rendszerbe kerülés (created_at) legkorábban, unix időbélyeg." }, "created_at_max": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 1893456000, "nullable": true, "description": "Rendszerbe kerülés legkésőbb, unix időbélyeg." }, "updated_at_min": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 1893456000, "nullable": true, "description": "Utolsó módosítás legkorábban, unix időbélyeg." }, "updated_at_max": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 1893456000, "nullable": true, "description": "Utolsó módosítás legkésőbb, unix időbélyeg." }, "downloaded_at_min": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 1893456000, "nullable": true, "description": "Első megnyitás (downloaded_at) legkorábban, unix időbélyeg." }, "downloaded_at_max": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 1893456000, "nullable": true, "description": "Első megnyitás legkésőbb, unix időbélyeg." }, "sender_name": { "type": "string", "nullable": true, "description": "Feladó teljes neve, pontos egyezéssel (a kód nem validálja, de alkalmazza)." }, "sender_short_name": { "type": "string", "nullable": true, "maxLength": 255, "description": "Feladó rövid neve, pontos egyezéssel (pl. NAV). A lehetséges értékeket a POST /messages/unique-values adja." }, "message_status_ids": { "type": "array", "nullable": true, "items": { "type": "integer" }, "description": "Csak ezekben a státuszokban lévő üzenetek (az iroda státuszainak azonosítói). Üres tömb = nincs szűrés." }, "downloaded": { "type": "boolean", "nullable": true, "description": "true = csak a rendszer által már letöltött fájlú üzenetek; false = csak a még le nem töltöttek." }, "has_valid_document": { "type": "boolean", "nullable": true, "description": "true = csak a valamely szabályra illeszkedő üzenetek; false = csak a szabály nélküliek." }, "has_sent_mail": { "type": "boolean", "nullable": true, "description": "true = csak az e-mailben már továbbított üzenetek; false = csak a nem továbbítottak." }, "read": { "type": "boolean", "nullable": true, "description": "Tárhelyen való megnyitás szerint: true = csak a megnyitott (downloaded_at kitöltött), false = csak az olvasatlan üzenetek. FIGYELEM: nem az üzenet `read` („Átnézve\") mezőjére szűr — arra a `reviewed` való." }, "reviewed": { "type": "boolean", "nullable": true, "description": "„Átnézve\" szerint (a lekérdező felhasználóé, ugyanaz a szabály, mint az üzenet `read` mezőjénél): true = csak az átnézettek, false = csak az át nem nézettek." }, "valid_document": { "type": "string", "nullable": true, "description": "Csak az erre a tárhely-szabályra illeszkedő üzenetek. Értéke a szabály kulcsa: a GET /actions lista `document_id` mezője (a szabályok listája változhat, ezért itt nincs felsorolva). Ismeretlen kulcs → 422.", "example": "ertesites_hibatlan_bevallas" }, "hide_acceptance_receipts": { "type": "boolean", "nullable": true, "description": "true = a NAV elfogadó nyugták kimaradnak." }, "show_idomsoft_bksz": { "type": "boolean", "nullable": true, "description": "Az IdomSoft BKSZ-üzenetek alapból KIMARADNAK a találatokból; true értékkel megjelennek." }, "only_legally_binding": { "type": "boolean", "nullable": true, "description": "true = csak a joghatással járó (jogerő-határidős) szabályokra illeszkedő üzenetek." }, "declaration_interval_min": { "type": "string", "format": "date", "nullable": true, "description": "A kapcsolódó bevallás időszakának kezdete legalább ez a nap (ÉÉÉÉ-HH-NN). Csak bevalláshoz kapcsolt üzenetek maradnak.", "example": "2026-01-01" }, "declaration_interval_max": { "type": "string", "format": "date", "nullable": true, "description": "A kapcsolódó bevallás időszakának vége legfeljebb ez a nap (ÉÉÉÉ-HH-NN).", "example": "2026-12-31" }, "declaration_barcode": { "type": "integer", "nullable": true, "minimum": 1000000000, "maximum": 9999999999, "description": "A kapcsolódó bevallás 10 jegyű vonalkódja (pontos egyezés).", "example": 2612345678 }, "declaration_tax_report_type": { "type": "string", "nullable": true, "maxLength": 255, "description": "A kapcsolódó bevallás nyomtatványa (pontos egyezés).", "example": "2508" } } } } } }, "responses": { "200": { "description": "A találatok egy lapja.", "content": { "application/json": { "schema": { "type": "object", "properties": { "records": { "type": "array", "items": { "$ref": "#/components/schemas/Message" }, "description": "Az aktuális lap üzenetei." }, "count": { "type": "integer", "description": "Az összes találat száma." }, "page": { "type": "integer", "description": "Az aktuális lap sorszáma." }, "max_page": { "type": "integer", "description": "Az utolsó lap sorszáma (0, ha nincs találat)." }, "order_column": { "type": "string", "description": "A ténylegesen alkalmazott rendezési oszlop." }, "order_direction": { "type": "string", "enum": [ "asc", "desc" ], "description": "A ténylegesen alkalmazott rendezési irány." } } } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/messages/export": { "post": { "tags": [ "Tárhely-üzenetek" ], "summary": "Tárhely-üzenetek exportálása", "description": "A POST /messages/search szűrőivel és rendezésével, lapozás nélkül Excel-fájlba exportálja az üzeneteket (adózó, feladó, dokumentum, státusz, fájl-hivatkozás, bevallás adatai, megjegyzések). Legfeljebb 50 000 üzenet exportálható egyszerre; efölött 422 a `search` mezőn. Minden szerepkör hívhatja.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "search": { "type": "string", "nullable": true, "description": "Szabad szavas keresés; minden szónak illeszkednie kell (részszó-egyezés) a dokumentumtípusra, leírásra, fájlnévre, feladóra, saját megjegyzésre, az adózó nevére / adószámára / adóazonosító jelére / megjegyzésére vagy a bevallás vonalkódjára. A cégforma-rövidítés a teljes formára is keres („Kft\" → „korlátolt felelősségű társaság\")." }, "order_column": { "type": "string", "nullable": true, "enum": [ "message_id", "download_method", "arrived_at", "sender_short_name", "tax_report_type", "created_at", "updated_at", "message_status_name", "legally_binding_deadline", null ], "description": "Rendezés oszlopa (alapértelmezés: arrived_at). message_id = tárhelybeli üzenet-azonosító; message_status_name = a státusz neve; legally_binding_deadline = jogerő napja. (A tax_report_type a kódban szerepel, de az üzeneteken nincs ilyen oszlop, lásd a megjegyzéseket.)" }, "order_direction": { "type": "string", "nullable": true, "enum": [ "asc", "desc", null ], "description": "Rendezés iránya (alapértelmezés: desc)." }, "customer_portal_id": { "type": "integer", "nullable": true, "minimum": 1, "description": "Csak ennek az ügyfélkapunak az üzenetei." }, "trustee_id": { "type": "integer", "nullable": true, "minimum": 1, "description": "Csak ennek az adózónak az üzenetei." }, "arrived_at_min": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 1893456000, "nullable": true, "description": "Érkezés (arrived_at) legkorábban, unix időbélyeg." }, "arrived_at_max": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 1893456000, "nullable": true, "description": "Érkezés legkésőbb, unix időbélyeg." }, "created_at_min": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 1893456000, "nullable": true, "description": "Rendszerbe kerülés (created_at) legkorábban, unix időbélyeg." }, "created_at_max": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 1893456000, "nullable": true, "description": "Rendszerbe kerülés legkésőbb, unix időbélyeg." }, "updated_at_min": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 1893456000, "nullable": true, "description": "Utolsó módosítás legkorábban, unix időbélyeg." }, "updated_at_max": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 1893456000, "nullable": true, "description": "Utolsó módosítás legkésőbb, unix időbélyeg." }, "downloaded_at_min": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 1893456000, "nullable": true, "description": "Első megnyitás (downloaded_at) legkorábban, unix időbélyeg." }, "downloaded_at_max": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 1893456000, "nullable": true, "description": "Első megnyitás legkésőbb, unix időbélyeg." }, "sender_name": { "type": "string", "nullable": true, "description": "Feladó teljes neve, pontos egyezéssel (a kód nem validálja, de alkalmazza)." }, "sender_short_name": { "type": "string", "nullable": true, "maxLength": 255, "description": "Feladó rövid neve, pontos egyezéssel (pl. NAV). A lehetséges értékeket a POST /messages/unique-values adja." }, "message_status_ids": { "type": "array", "nullable": true, "items": { "type": "integer" }, "description": "Csak ezekben a státuszokban lévő üzenetek (az iroda státuszainak azonosítói). Üres tömb = nincs szűrés." }, "downloaded": { "type": "boolean", "nullable": true, "description": "true = csak a rendszer által már letöltött fájlú üzenetek; false = csak a még le nem töltöttek." }, "has_valid_document": { "type": "boolean", "nullable": true, "description": "true = csak a valamely szabályra illeszkedő üzenetek; false = csak a szabály nélküliek." }, "has_sent_mail": { "type": "boolean", "nullable": true, "description": "true = csak az e-mailben már továbbított üzenetek; false = csak a nem továbbítottak." }, "read": { "type": "boolean", "nullable": true, "description": "Tárhelyen való megnyitás szerint: true = csak a megnyitott (downloaded_at kitöltött), false = csak az olvasatlan üzenetek. FIGYELEM: nem az üzenet `read` („Átnézve\") mezőjére szűr — arra a `reviewed` való." }, "reviewed": { "type": "boolean", "nullable": true, "description": "„Átnézve\" szerint (a lekérdező felhasználóé, ugyanaz a szabály, mint az üzenet `read` mezőjénél): true = csak az átnézettek, false = csak az át nem nézettek." }, "valid_document": { "type": "string", "nullable": true, "description": "Csak az erre a tárhely-szabályra illeszkedő üzenetek. Értéke a szabály kulcsa: a GET /actions lista `document_id` mezője (a szabályok listája változhat, ezért itt nincs felsorolva). Ismeretlen kulcs → 422.", "example": "ertesites_hibatlan_bevallas" }, "hide_acceptance_receipts": { "type": "boolean", "nullable": true, "description": "true = a NAV elfogadó nyugták kimaradnak." }, "show_idomsoft_bksz": { "type": "boolean", "nullable": true, "description": "Az IdomSoft BKSZ-üzenetek alapból KIMARADNAK a találatokból; true értékkel megjelennek." }, "only_legally_binding": { "type": "boolean", "nullable": true, "description": "true = csak a joghatással járó (jogerő-határidős) szabályokra illeszkedő üzenetek." }, "declaration_interval_min": { "type": "string", "format": "date", "nullable": true, "description": "A kapcsolódó bevallás időszakának kezdete legalább ez a nap (ÉÉÉÉ-HH-NN). Csak bevalláshoz kapcsolt üzenetek maradnak.", "example": "2026-01-01" }, "declaration_interval_max": { "type": "string", "format": "date", "nullable": true, "description": "A kapcsolódó bevallás időszakának vége legfeljebb ez a nap (ÉÉÉÉ-HH-NN).", "example": "2026-12-31" }, "declaration_barcode": { "type": "integer", "nullable": true, "minimum": 1000000000, "maximum": 9999999999, "description": "A kapcsolódó bevallás 10 jegyű vonalkódja (pontos egyezés).", "example": 2612345678 }, "declaration_tax_report_type": { "type": "string", "nullable": true, "maxLength": 255, "description": "A kapcsolódó bevallás nyomtatványa (pontos egyezés).", "example": "2508" } } } } } }, "responses": { "200": { "description": "Az .xlsx fájl.", "content": { "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/messages/unique-values": { "post": { "tags": [ "Tárhely-üzenetek" ], "summary": "Üzenetmezők egyedi értékei", "description": "A felhasználó által látható üzenetekben előforduló egyedi értékek (vagy értékkombinációk) a megadott mezőkre, az első mező szerint rendezve — pl. feladó-választólistához. Minden szerepkör hívhatja.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "fields": { "type": "array", "minItems": 1, "maxItems": 3, "items": { "type": "string", "enum": [ "sender_name", "sender_short_name", "addressee_name", "addressee_short_name", "document_type" ] }, "description": "A lekérdezett mezők (1–3). sender_name / sender_short_name = feladó teljes / rövid neve; addressee_name / addressee_short_name = címzett teljes / rövid neve; document_type = dokumentumtípus.", "example": [ "sender_short_name" ] } }, "required": [ "fields" ] } } } }, "responses": { "200": { "description": "Az egyedi értékek. Minden elem egy objektum a kért mezőkkel; a kód hibája miatt az elemekben `message_status`, `trustee`, `declaration`, `mailbox` (null) és `sent_mails` (üres tömb) kulcs is szerepel, ezeket figyelmen kívül kell hagyni.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "description": "A kért mezők értékei.", "properties": { "sender_name": { "type": "string", "nullable": true }, "sender_short_name": { "type": "string", "nullable": true }, "addressee_name": { "type": "string", "nullable": true }, "addressee_short_name": { "type": "string", "nullable": true }, "document_type": { "type": "string", "nullable": true } }, "additionalProperties": true }, "example": [ { "sender_short_name": "NAV" }, { "sender_short_name": "ONYF" } ] } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/messages/{messageId}/send-mail": { "post": { "tags": [ "Tárhely-üzenetek" ], "summary": "Tárhely-üzenet továbbítása e-mailben", "description": "Az üzenetet e-mailben továbbítja a megadott címekre (címenként külön levél, „{felhasználó neve} továbbított egy tárhely üzenetet\" tárggyal), a megadott megjegyzéssel. Ha a fájlt a rendszer már letöltötte és mérete belefér a mellékletkorlátba, mellékletként csatolja. A kiküldött levelek az elküldött e-mailek között (SentMail, `type = message`) jelennek meg. Minden szerepkör hívhatja, amely az üzenetet látja.", "parameters": [ { "name": "messageId", "in": "path", "required": true, "description": "Az üzenet azonosítója.", "schema": { "type": "integer", "minimum": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "emails": { "type": "array", "minItems": 1, "items": { "type": "string", "format": "email" }, "description": "A címzettek e-mail címei.", "example": [ "ugyfel@example.hu" ] }, "note": { "type": "string", "nullable": true, "description": "A levélbe kerülő kísérő megjegyzés." } }, "required": [ "emails" ] } } } }, "responses": { "200": { "description": "Sikeres művelet, üres választörzs." }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/messages/set-messages-read-at": { "post": { "tags": [ "Tárhely-üzenetek" ], "summary": "„Mindet átnéztem\" időpont beállítása", "description": "A hívó felhasználó „mindet átnéztem\" időpontjának beállítása: az ennél korábban a rendszerbe került üzenetek „Átnézve\" állapotúak lesznek (az üzenet `read` mezője). Csak előre léptethető: korábbi időpont megadása nem változtat semmit. Az időpont előtti, egyesével beállított átnézve-jelölések ezzel megszűnnek. Bármely bejelentkezett felhasználó hívhatja.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "messages_read_at": { "type": "integer", "format": "int64", "minimum": 1577836800, "maximum": 1893456000, "description": "Unix időbélyeg (mp), jellemzően a mostani idő.", "example": 1793088000 } }, "required": [ "messages_read_at" ] } } } }, "responses": { "200": { "description": "A hívó felhasználó adatai a frissített `messages_read_at` értékkel.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/declarations/{declarationId}": { "get": { "tags": [ "Bevallások" ], "summary": "Bevallás megtekintése", "description": "Egy bevallás adatai az adózóval és a bevalláshoz kapcsolt tárhely-üzenetekkel (pl. elfogadó nyugta, NAV-értesítés). A bevallás PDF- és XKR-fájljának hivatkozása a `file_pdf` / `file_xkr` mezőben jön. Jogosultság: minden szerepkör olvashatja; az ingyenes csomagban nem érhető el (403). Csak a hívó irodájának aktív ügyfélkapuihoz tartozó, aktív adózók adatai látszanak; „megadott adózók” hozzáférésű felhasználónál csak a hozzá rendelt adózóké. Más iroda vagy nem hozzáférhető adózó bevallására 404 a válasz.", "parameters": [ { "name": "declarationId", "in": "path", "required": true, "description": "A bevallás azonosítója (`id`).", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "A bevallás.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Declaration" } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/declarations/search": { "post": { "tags": [ "Bevallások" ], "summary": "Bevallások szűrése", "description": "Az adózók NAV-hoz beküldött bevallásainak lapozott, szűrhető, rendezhető listája (a felület Bevallások listája). Minden szűrő elhagyható; több szűrő esetén mindnek teljesülnie kell. Minden rekordban benne van az adózó és a kapcsolódó tárhely-üzenetek. Jogosultság: minden szerepkör; az ingyenes csomagban nem érhető el (403). Csak a hívó irodájának aktív ügyfélkapuihoz tartozó, aktív adózók adatai látszanak; „megadott adózók” hozzáférésű felhasználónál csak a hozzá rendelt adózóké.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 200, "nullable": true, "default": 200, "description": "Oldalméret: ennyi rekord jön egy oldalon. Alapértelmezés: 200." }, "page": { "type": "integer", "minimum": 1, "nullable": true, "default": 1, "description": "A kért oldal sorszáma (1-től). Alapértelmezés: 1." }, "order_column": { "type": "string", "nullable": true, "enum": [ null, "interval_start", "interval_end", "created_at", "first_message_arrived_at", "error_message_arrived_at", "trustee_name" ], "default": "created_at", "description": "Rendezési oszlop. `interval_start` / `interval_end`: a bevallási időszak kezdete / vége; `created_at`: a bevallás megjelenése a rendszerben; `first_message_arrived_at`: a befogadás dátuma (az első kapcsolódó tárhely-üzenet érkezése); `error_message_arrived_at`: a NAV „Értesítés - Intézkedés” üzenetének érkezése; `trustee_name`: az adózó neve. Ha üres, `created_at` szerint rendez." }, "order_direction": { "type": "string", "nullable": true, "enum": [ null, "asc", "desc" ], "default": "desc", "description": "Rendezési irány: `asc` növekvő, `desc` csökkenő. Ha üres: `desc`." }, "search": { "type": "string", "nullable": true, "description": "Szabadszöveges keresés. A szöveget szavakra bontja (szóköz, kötőjel, pont, zárójel stb. mentén); minden szónak illeszkednie kell valamelyik mezőre (részleges egyezés). Keresett mezők: vonalkód, nyomtatvány típusa, funkció, státusz, az adózó neve és adószáma. Cégforma-rövidítésre (pl. „Kft”) a teljes cégformát is megtalálja." }, "customer_portal_id": { "type": "integer", "minimum": 1, "nullable": true, "description": "Csak az ezen ügyfélkapuhoz tartozó adózók bevallásai." }, "trustee_id": { "type": "integer", "minimum": 1, "nullable": true, "description": "Csak ennek az adózónak a bevallásai." }, "barcode": { "type": "integer", "minimum": 1000000000, "maximum": 9999999999, "nullable": true, "description": "Pontos egyezés a bevallás 10 jegyű NAV-vonalkódjára.", "example": 2512345678 }, "interval_min": { "type": "string", "format": "date", "nullable": true, "example": "2026-01-01", "description": "A bevallási időszak kezdete legalább ez a nap (ÉÉÉÉ-HH-NN)." }, "interval_max": { "type": "string", "format": "date", "nullable": true, "example": "2026-03-31", "description": "A bevallási időszak vége legfeljebb ez a nap (ÉÉÉÉ-HH-NN)." }, "tax_report_type": { "type": "string", "maxLength": 255, "nullable": true, "example": "2608", "description": "Pontos egyezés a nyomtatvány típusára (pl. `2608`, `2665`)." }, "function": { "type": "string", "nullable": true, "enum": [ null, "ALAPBEVALLAS", "HELYESBITO_BEVALLAS", "JAVITO_BEVALLAS", "ONELLENORZES" ], "description": "A bevallás funkciója: `ALAPBEVALLAS` alapbevallás, `HELYESBITO_BEVALLAS` helyesbítő, `JAVITO_BEVALLAS` javító bevallás, `ONELLENORZES` önellenőrzés." }, "status": { "type": "string", "nullable": true, "enum": [ null, "ELINTÉZETT", "Feldolgozásra vár", "Feldolgozás alatt", "Feldolgozott", "Kiértesítve", "LEZÁRT/NAPLÓZOTT", "Törölt", "NYITOTT" ], "description": "A bevallás NAV szerinti állapota (pontos egyezés). Az értékek jelentését lásd a `Declaration.status` mezőnél." }, "has_unclosed_message": { "type": "boolean", "nullable": true, "description": "`true`: csak azok a bevallások, amelyekhez van látható, nem lezáró státuszú tárhely-üzenet (lezáratlan feladat); `false`: csak azok, amelyekhez nincs ilyen." }, "message_arrived_at_min": { "type": "integer", "minimum": 0, "maximum": 1893456000, "nullable": true, "example": 1767225600, "description": "Unix időbélyeg (másodperc): van a bevalláshoz legalább ekkor vagy később érkezett tárhely-üzenet." }, "message_arrived_at_max": { "type": "integer", "minimum": 0, "maximum": 1893456000, "nullable": true, "example": 1798761599, "description": "Unix időbélyeg (másodperc): van a bevalláshoz legkésőbb ekkor érkezett tárhely-üzenet. A két határ külön-külön is illeszkedhet más-más üzenetre." } } } } } }, "responses": { "200": { "description": "A szűrésnek megfelelő rekordok egy oldala.", "content": { "application/json": { "schema": { "type": "object", "required": [ "records", "count", "page", "max_page", "order_column", "order_direction" ], "properties": { "records": { "type": "array", "items": { "$ref": "#/components/schemas/Declaration" }, "description": "A bevallások (adózóval és tárhely-üzenetekkel)." }, "count": { "type": "integer", "description": "A szűrésnek megfelelő összes rekord száma." }, "page": { "type": "integer", "description": "Az aktuális oldal sorszáma." }, "max_page": { "type": "integer", "description": "Az utolsó oldal sorszáma (0, ha nincs találat)." }, "order_column": { "type": "string", "description": "A ténylegesen használt rendezési oszlop." }, "order_direction": { "type": "string", "enum": [ "asc", "desc" ], "description": "A ténylegesen használt rendezési irány." } } } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/declarations/export": { "post": { "tags": [ "Bevallások" ], "summary": "Bevallások exportálása", "description": "Ugyanazokkal a szűrőkkel, mint a `POST /declarations/search`, de lapozás nélkül, Excel-fájlban (.xlsx) adja vissza a találatokat. Oszlopok: vonalkód, adózó neve és adószáma, bevallás típusa, időszak, befogadás és hibaüzenet dátuma, funkció, státusz, valamint hivatkozás a PDF és XKR fájlra. Legfeljebb 50 000 rekord exportálható; efölött 422 hiba jön a `search` mezőre, ilyenkor szűkíteni kell. Jogosultság: mint a szűrésnél.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "order_column": { "type": "string", "nullable": true, "enum": [ null, "interval_start", "interval_end", "created_at", "first_message_arrived_at", "error_message_arrived_at", "trustee_name" ], "default": "created_at", "description": "Rendezési oszlop. `interval_start` / `interval_end`: a bevallási időszak kezdete / vége; `created_at`: a bevallás megjelenése a rendszerben; `first_message_arrived_at`: a befogadás dátuma (az első kapcsolódó tárhely-üzenet érkezése); `error_message_arrived_at`: a NAV „Értesítés - Intézkedés” üzenetének érkezése; `trustee_name`: az adózó neve. Ha üres, `created_at` szerint rendez." }, "order_direction": { "type": "string", "nullable": true, "enum": [ null, "asc", "desc" ], "default": "desc", "description": "Rendezési irány: `asc` növekvő, `desc` csökkenő. Ha üres: `desc`." }, "search": { "type": "string", "nullable": true, "description": "Szabadszöveges keresés. A szöveget szavakra bontja (szóköz, kötőjel, pont, zárójel stb. mentén); minden szónak illeszkednie kell valamelyik mezőre (részleges egyezés). Keresett mezők: vonalkód, nyomtatvány típusa, funkció, státusz, az adózó neve és adószáma. Cégforma-rövidítésre (pl. „Kft”) a teljes cégformát is megtalálja." }, "customer_portal_id": { "type": "integer", "minimum": 1, "nullable": true, "description": "Csak az ezen ügyfélkapuhoz tartozó adózók bevallásai." }, "trustee_id": { "type": "integer", "minimum": 1, "nullable": true, "description": "Csak ennek az adózónak a bevallásai." }, "barcode": { "type": "integer", "minimum": 1000000000, "maximum": 9999999999, "nullable": true, "description": "Pontos egyezés a bevallás 10 jegyű NAV-vonalkódjára.", "example": 2512345678 }, "interval_min": { "type": "string", "format": "date", "nullable": true, "example": "2026-01-01", "description": "A bevallási időszak kezdete legalább ez a nap (ÉÉÉÉ-HH-NN)." }, "interval_max": { "type": "string", "format": "date", "nullable": true, "example": "2026-03-31", "description": "A bevallási időszak vége legfeljebb ez a nap (ÉÉÉÉ-HH-NN)." }, "tax_report_type": { "type": "string", "maxLength": 255, "nullable": true, "example": "2608", "description": "Pontos egyezés a nyomtatvány típusára (pl. `2608`, `2665`)." }, "function": { "type": "string", "nullable": true, "enum": [ null, "ALAPBEVALLAS", "HELYESBITO_BEVALLAS", "JAVITO_BEVALLAS", "ONELLENORZES" ], "description": "A bevallás funkciója: `ALAPBEVALLAS` alapbevallás, `HELYESBITO_BEVALLAS` helyesbítő, `JAVITO_BEVALLAS` javító bevallás, `ONELLENORZES` önellenőrzés." }, "status": { "type": "string", "nullable": true, "enum": [ null, "ELINTÉZETT", "Feldolgozásra vár", "Feldolgozás alatt", "Feldolgozott", "Kiértesítve", "LEZÁRT/NAPLÓZOTT", "Törölt", "NYITOTT" ], "description": "A bevallás NAV szerinti állapota (pontos egyezés). Az értékek jelentését lásd a `Declaration.status` mezőnél." }, "has_unclosed_message": { "type": "boolean", "nullable": true, "description": "`true`: csak azok a bevallások, amelyekhez van látható, nem lezáró státuszú tárhely-üzenet (lezáratlan feladat); `false`: csak azok, amelyekhez nincs ilyen." }, "message_arrived_at_min": { "type": "integer", "minimum": 0, "maximum": 1893456000, "nullable": true, "example": 1767225600, "description": "Unix időbélyeg (másodperc): van a bevalláshoz legalább ekkor vagy később érkezett tárhely-üzenet." }, "message_arrived_at_max": { "type": "integer", "minimum": 0, "maximum": 1893456000, "nullable": true, "example": 1798761599, "description": "Unix időbélyeg (másodperc): van a bevalláshoz legkésőbb ekkor érkezett tárhely-üzenet. A két határ külön-külön is illeszkedhet más-más üzenetre." } } } } } }, "responses": { "200": { "description": "Az Excel-fájl (.xlsx), letöltésként (`Content-Disposition: attachment`).", "content": { "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/declarations/unique-values": { "post": { "tags": [ "Bevallások" ], "summary": "Bevallások mezőinek egyedi értékei", "description": "A hívó által látható bevallások megadott mezőinek egyedi érték-kombinációi, pl. a szűrők legördülő listáihoz (milyen nyomtatványtípusok, vonalkódok fordulnak elő). A sorrend az első kért mező szerint növekvő; az üres (`null`) érték is szerepelhet. Lapozás nincs, a teljes lista egyben jön. Csak a hívó irodájának aktív ügyfélkapuihoz tartozó, aktív adózók adatai látszanak; „megadott adózók” hozzáférésű felhasználónál csak a hozzá rendelt adózóké.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "fields": { "type": "array", "minItems": 1, "maxItems": 3, "items": { "type": "string", "enum": [ "barcode", "tax_report_type" ] }, "description": "A lekérdezett mezők: `barcode` (vonalkód), `tax_report_type` (nyomtatvány típusa).", "example": [ "tax_report_type" ] } }, "required": [ "fields" ] } } } }, "responses": { "200": { "description": "Az egyedi érték-kombinációk listája; minden elem csak a kért mezőket tartalmazza értékkel.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "barcode": { "type": "integer", "description": "Vonalkód (csak ha kérték)." }, "tax_report_type": { "type": "string", "nullable": true, "description": "Nyomtatvány típusa (csak ha kérték)." }, "trustee": { "nullable": true, "description": "Mindig `null`; a válaszban technikai okból szerepel, nem használandó.", "type": "object" }, "messages": { "type": "array", "items": { "type": "object" }, "description": "Mindig üres tömb; technikai okból szerepel, nem használandó." } } }, "example": [ { "tax_report_type": "2608", "trustee": null, "messages": [] }, { "tax_report_type": "2665", "trustee": null, "messages": [] } ] } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/trustees": { "get": { "tags": [ "Adózók" ], "summary": "Adózók listázása", "description": "A felhasználó által látható összes adózó (az aktívak és az inaktívak is) lapozás nélkül, név szerint rendezve. Csak az iroda aktív ügyfélkapuihoz tartozó adózók szerepelnek; „kijelölt adózók” jogkörű és adózó szerepkörű felhasználó csak a hozzá rendelt adózókat kapja. Minden elem a teljes `Trustee` objektum (egyenlegek, törzsadat, önkormányzati számlák, köztartozás; a csomag és a jogosultság szerint). Jogosultság: bármely szerepkör (menedzser, könyvelő, adózó), bármely csomag. Nagy irodánál a válasz nagy és lassú lehet: listázáshoz a lapozott `POST /trustees/search` ajánlott.", "responses": { "200": { "description": "Az adózók tömbje.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Trustee" } } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" } } } }, "/trustees/{trusteeId}": { "get": { "tags": [ "Adózók" ], "summary": "Adózó megtekintése", "description": "Egy adózó teljes adatlapja: alapadatok, értesítési címek, NAV-egyenleg adónemenként, és a jogosultság és a csomag szerint a törzsadatok, az önkormányzati (ASP) adószámlák és a végrehajtható köztartozások. Inaktív adózó is lekérhető. Jogosultság: bármely szerepkör, bármely csomag; „kijelölt adózók” jogkörű és adózó szerepkörű felhasználó csak a hozzá rendelt adózót.", "parameters": [ { "name": "trusteeId", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "Az adózó azonosítója (`Trustee.id`). Csak a hívó irodájának aktív ügyfélkapuihoz tartozó, a felhasználó által látható adózó adható meg (inaktív adózó is), különben 404.", "example": 121622 } ], "responses": { "200": { "description": "Az adózó.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Trustee" } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "tags": [ "Adózók" ], "summary": "Adózó módosítása", "description": "Az adózó irodai beállításainak módosítása: aktivitás, a négy értesítésicím-lista, hátralék-értesítés, ASP-képviselő adószáma, megjegyzés és az önkormányzatok listája. A NAV-tól származó adatok (név, adószám, adózás módja stb.) nem módosíthatók. Teljes csere: az `active` és a `debt_notification` kötelező, az elhagyott címlista üres listára, az elhagyott `note` `null`-ra áll; csak a `municipality_ids` hagyható el változtatás nélkül. Jogosultság: menedzser és könyvelő szerepkör (adózó szerepkör: 403), bármely csomag. Adózót létrehozni és törölni az API-n nem lehet; az adózókat a rendszer az ügyfélkapukból veszi fel. A válasz a módosított adózó.", "parameters": [ { "name": "trusteeId", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "Az adózó azonosítója (`Trustee.id`). Csak a hívó irodájának aktív ügyfélkapuihoz tartozó, a felhasználó által látható adózó adható meg (inaktív adózó is), különben 404.", "example": 121622 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "active", "debt_notification" ], "properties": { "active": { "type": "boolean", "description": "Aktív-e az adózó. Csak aktív adózóval dolgozik a rendszer (üzenetek, bevallások, egyenlegek, hátralék-értesítés), és az előfizetés díja is az aktív adózók számától függ. Aktiváláskor, ha a csomag aktív-adózó korlátja (Ingyenes csomag) betelt, 403 a válasz." }, "emails": { "type": "array", "nullable": true, "items": { "type": "string", "format": "email" }, "example": [ "ugyfel@example.hu" ], "description": "Az adózó saját értesítési címei („Üzenet küldési e-mail”). Ide megy a hátralék-értesítő, és a tárhely-szabályokban az „Adózó” címzett is ezt jelenti. `null` vagy elhagyva üres listát ment." }, "accountant_emails": { "type": "array", "nullable": true, "items": { "type": "string", "format": "email" }, "description": "A könyvelő címei (a szabályokban a „Könyvelő” címzett). `null` vagy elhagyva üres listát ment." }, "payroll_accountant_emails": { "type": "array", "nullable": true, "items": { "type": "string", "format": "email" }, "description": "A bérszámfejtő címei (a szabályokban a „Bérszámfejtő” címzett). `null` vagy elhagyva üres listát ment." }, "tax_advisor_emails": { "type": "array", "nullable": true, "items": { "type": "string", "format": "email" }, "description": "Az adótanácsadó címei (a szabályokban az „Adótanácsadó” címzett). `null` vagy elhagyva üres listát ment." }, "debt_notification": { "type": "boolean", "description": "Hátralék-értesítés: ha igaz, az adózó a saját címeire (`emails`) automatikus levelet kap, ha a NAV-nál, az önkormányzatnál (ASP) vagy végrehajtható köztartozásként tartozása van (a csomagban elérhető adatkörök szerint, az iroda beállította gyakorisággal)." }, "asp_represented_tax_number": { "type": "string", "nullable": true, "example": "12345678-2-42", "description": "ASP – képviselő cég adószáma: ha az adózót az önkormányzati (ASP) rendszerben egy cég (pl. a könyvelőiroda) képviseli, annak 11 jegyű adószáma, kötőjellel vagy anélkül. Ellenőrzött (érvényes adószám kell). A válaszban kötőjel nélküli egész számként jön vissza." }, "note": { "type": "string", "nullable": true, "maxLength": 255, "description": "Belső megjegyzés az adózóhoz (az iroda saját feljegyzése). Elhagyva vagy `null` értékkel TÖRLŐDIK." }, "municipality_ids": { "type": "array", "nullable": true, "items": { "type": "integer" }, "example": [ 2658 ], "description": "Az adózó önkormányzatainak (`Municipality.id`, lásd `GET /municipalities`) TELJES listája, amelyeknél a rendszer az önkormányzati (ASP) adószámlát letölti. A listából kimaradt önkormányzatok a hozzájuk letöltött adószámlákkal együtt lekerülnek, az újak felkerülnek; változás esetén a rendszer az ügyfélkapu önkormányzati adatait teljesen újra letölti. Elhagyva vagy `null` értékkel az önkormányzatok nem változnak. Minden azonosítónak létező önkormányzatnak kell lennie." } } } } } }, "responses": { "200": { "description": "A módosított adózó.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Trustee" } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/trustees/{trusteeId}/export-roles": { "post": { "tags": [ "Adózók" ], "summary": "Adózó törzsadatainak letöltése Excelben", "description": "Az adózó NAV-nyilvántartás szerinti törzsadatai XLSX-fájlban. Törzsadat-lapanként egy munkalap (`CÉG`, illetve `MAGÁNSZEMÉLY`), soronként a törzsadat-címke (a hierarchiát behúzás jelzi), az aktuális és az előző érték, így a legutóbbi változás is látszik. Fájlnév: az adózó nevéből képzett `{nev}_torzsadat.xlsx`. Kérés törzse nincs. Jogosultság: bármely szerepkör, aki látja az adózót; 403, ha az adózónak nincs törzsadata.", "parameters": [ { "name": "trusteeId", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "Az adózó azonosítója (`Trustee.id`). Csak a hívó irodájának aktív ügyfélkapuihoz tartozó, a felhasználó által látható adózó adható meg (inaktív adózó is), különben 404.", "example": 121622 } ], "responses": { "200": { "description": "A törzsadat XLSX-fájl (letöltésként, `Content-Disposition: attachment`).", "content": { "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/trustees/{trusteeId}/export-app-csv": { "post": { "tags": [ "Adózók" ], "summary": "Adózó havi EFO-kimutatása APP CSV formátumban", "description": "Az adózó egyszerűsített foglalkoztatottjai (EFO) a megadott időszakra, CSV-fájlban: azok, akiknek a foglalkoztatása átfedi az időszakot, név szerint. Oszlopok: munkáltató adószáma, név, születési név, nem, adóazonosító, TAJ-szám, állampolgárság, anyja neve, születési hely és idő (a ki nem töltött oszlopokban „-” vagy üres), foglalkoztatás jele (`06` alkalmi munka, `03` mezőgazdasági idénymunka, `05` turisztikai idénymunka, `07` filmipari statiszta), hó naptól, hó napig, napok száma összesen (az időszakra eső napok), kifizetett bruttó bér („-”). Formátum: pontosvessző-elválasztás, idézőjelek nélkül, Windows-1252 kódolás, BOM nélkül. Fájlnév: `{nev}_{ÉÉÉÉ}_{HH}.csv` (az időszak kezdete szerint). Jogosultság: bármely szerepkör, aki látja az adózót, bármely csomag.", "parameters": [ { "name": "trusteeId", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "Az adózó azonosítója (`Trustee.id`). Csak a hívó irodájának aktív ügyfélkapuihoz tartozó, a felhasználó által látható adózó adható meg (inaktív adózó is), különben 404.", "example": 121622 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "period_start", "period_end" ], "properties": { "period_start": { "type": "string", "format": "date", "example": "2026-10-01", "description": "Az időszak első napja (ÉÉÉÉ-HH-NN), jellemzően a hónap első napja." }, "period_end": { "type": "string", "format": "date", "example": "2026-10-31", "description": "Az időszak utolsó napja (ÉÉÉÉ-HH-NN), jellemzően a hónap utolsó napja." } } } } } }, "responses": { "200": { "description": "A CSV-fájl (letöltésként). Ha az időszakban nincs EFO, csak a fejléc.", "content": { "text/csv": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/trustees/{trusteeId}/export-ebev-xlsx": { "post": { "tags": [ "Adózók" ], "summary": "Adózó havi EFO-kimutatása eBEV XLSX formátumban", "description": "Az adózó egyszerűsített foglalkoztatottjai (EFO) a megadott időszakra, XLSX-fájlban (azok, akiknek a foglalkoztatása átfedi az időszakot, név szerint). Oszlopok: munkavállaló, adóazonosítója, bejelentés napja, bejelentés jellege, adatlap típusa, kezdés napja (az időszakon belül), foglalkoztatás jellege, munkanapok száma (az időszakra eső napok), TAJ száma, máshol biztosított, nyilatkozat létszámról, nyilatkozat adótartozásról (ez utóbbi három mindig „nem”), adatlap feldolgozottsági státusza, adatlap nyilvántartási száma. Fájlnév: `{nev}_{ÉÉÉÉ}_{HH}.xlsx`. Jogosultság: bármely szerepkör, aki látja az adózót, bármely csomag.", "parameters": [ { "name": "trusteeId", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "Az adózó azonosítója (`Trustee.id`). Csak a hívó irodájának aktív ügyfélkapuihoz tartozó, a felhasználó által látható adózó adható meg (inaktív adózó is), különben 404.", "example": 121622 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "period_start", "period_end" ], "properties": { "period_start": { "type": "string", "format": "date", "example": "2026-10-01", "description": "Az időszak első napja (ÉÉÉÉ-HH-NN), jellemzően a hónap első napja." }, "period_end": { "type": "string", "format": "date", "example": "2026-10-31", "description": "Az időszak utolsó napja (ÉÉÉÉ-HH-NN), jellemzően a hónap utolsó napja." } } } } } }, "responses": { "200": { "description": "Az XLSX-fájl (letöltésként). Ha az időszakban nincs EFO, csak a fejléc.", "content": { "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/trustees/search": { "post": { "tags": [ "Adózók" ], "summary": "Adózók keresése és szűrése (lapozva)", "description": "Az adózók lapozott, szűrhető, rendezhető listája. Minden elem a teljes `Trustee` objektum, ugyanúgy, mint a `GET /trustees/{trusteeId}` válaszában. A szűrők ÉS kapcsolatban állnak; minden mező elhagyható. Az `active` szűrő nélkül az inaktív adózók is benne vannak. Jogosultság: bármely szerepkör, bármely csomag; a felhasználó csak a számára látható adózókat kapja.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 200, "nullable": true, "default": 200, "description": "Oldalméret (legfeljebb 200, alapérték 200)." }, "page": { "type": "integer", "minimum": 1, "nullable": true, "default": 1, "description": "Az oldal sorszáma 1-től." }, "order_column": { "type": "string", "nullable": true, "enum": [ "name", "sum_debt", "sum_municipality_debt", "sum_public_debt", "unclosed_messages_count", "relationship_week_hours" ], "default": "name", "description": "Rendezési oszlop: `name` név (alapérték), `sum_debt` NAV-egyenleg, `sum_municipality_debt` tárgyévi önkormányzati egyenleg, `sum_public_debt` végrehajtható köztartozás, `unclosed_messages_count` le nem zárt tárhely-üzenetek száma, `relationship_week_hours` heti munkaóra a saját foglalkoztatóknál." }, "order_direction": { "type": "string", "nullable": true, "enum": [ "asc", "desc" ], "default": "asc", "description": "Rendezési irány: `asc` növekvő (alapérték), `desc` csökkenő." }, "search": { "type": "string", "nullable": true, "example": "alfa kft", "description": "Szabad szavas keresés. A szöveget szavakra bontja (szóköz, kötőjel, pont, vessző stb. mentén), és minden szónak szerepelnie kell az alábbiak valamelyikében: név, adószám, adóazonosító jel, adózás módja, áfa-gyakoriság, ASP-képviselő adószáma, megjegyzés. Cégforma-rövidítésnél a teljes formára is keres („Kft” a „korlátolt felelősségű társaság” nevet is megtalálja)." }, "customer_portal_id": { "type": "integer", "nullable": true, "description": "Csak ennek az ügyfélkapunak (`CustomerPortal.id`) az adózói. A hívó irodájához kell tartoznia, különben 422." }, "active": { "type": "boolean", "nullable": true, "description": "`true`: csak aktív, `false`: csak inaktív adózók. Elhagyva mindkettő (az API alapból az inaktív adózókat is visszaadja, a felület listájával ellentétben)." }, "has_simplified_employee_from": { "type": "string", "format": "date", "nullable": true, "example": "2026-10-01", "description": "Csak azok az adózók, akiknek van olyan egyszerűsített foglalkoztatottja (EFO), akinek a foglalkoztatása ezen a napon vagy később kezdődött (ÉÉÉÉ-HH-NN). A `has_simplified_employee_to` mezővel együtt intervallum." }, "has_simplified_employee_to": { "type": "string", "format": "date", "nullable": true, "example": "2026-10-31", "description": "Csak azok az adózók, akiknek van olyan EFO-ja, akinek a foglalkoztatása ezen a napon vagy korábban kezdődött (ÉÉÉÉ-HH-NN)." }, "has_simplified_employee": { "type": "boolean", "nullable": true, "description": "`true`: csak akinek van egyszerűsített foglalkoztatottja (EFO), `false`: csak akinek nincs." }, "has_employee": { "type": "boolean", "nullable": true, "description": "`true`: csak akinek van biztosítottja (bejelentett foglalkoztatottja), `false`: csak akinek nincs." }, "taxation_type": { "type": "string", "nullable": true, "enum": [ "VSZJA", "Átalányadó", "Új KATA", "Társasági adó", "KIVA" ], "description": "Szűrés az adózás módjára. Az adózás módja a NAV-törzsadat alapján: `VSZJA` (vállalkozói személyi jövedelemadó; ez az alapérték, ha a törzsadatból más nem olvasható ki), `Átalányadó` (egyéni vállalkozói átalányadó), `Új KATA` (kisadózó vállalkozások tételes adója), `Társasági adó`, `KIVA` (kisvállalati adó)." }, "vat_period": { "type": "string", "nullable": true, "enum": [ "Havi", "Negyedéves", "Éves" ], "description": "Szűrés az áfabevallás gyakoriságára (`Havi`, `Negyedéves`, `Éves`)." }, "upo_available": { "type": "boolean", "nullable": true, "description": "`true`: csak akik szerepelnek az ügyfélkapu meghatalmazói között a NAV Online Ügyfélportálon (ÜPO), `false`: csak akik már nem (pl. megszűnt a megbízás)." }, "koma_status": { "type": "string", "nullable": true, "enum": [ "included_qualified", "included_not_qualified", "in_progress", "not_included_qualified", "not_included_not_qualified" ], "description": "Szűrés a törzsadatok KOMA-állapotára (legalább egy törzsadat-lapnak ilyen az állapota). A Köztartozásmentes Adózói Adatbázis (KOMA) szerinti állapot: `included_qualified` szerepel, minősített; `included_not_qualified` szerepel, nem minősített; `in_progress` a felvételi kérelem beküldése vagy feldolgozása folyamatban; `not_included_qualified` nem szerepel, minősített; `not_included_not_qualified` nem szerepel, nem minősített." } } } } } }, "responses": { "200": { "description": "A találatok egy oldala.", "content": { "application/json": { "schema": { "type": "object", "properties": { "records": { "type": "array", "items": { "$ref": "#/components/schemas/Trustee" }, "description": "Az oldal adózói." }, "count": { "type": "integer", "description": "A feltételeknek megfelelő adózók száma összesen." }, "page": { "type": "integer", "description": "Az aktuális oldal sorszáma." }, "max_page": { "type": "integer", "description": "Az utolsó oldal sorszáma (0, ha nincs találat)." }, "order_column": { "type": "string", "description": "A ténylegesen alkalmazott rendezési oszlop." }, "order_direction": { "type": "string", "enum": [ "asc", "desc" ], "description": "A ténylegesen alkalmazott rendezési irány." } } } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/trustees/export": { "post": { "tags": [ "Adózók" ], "summary": "Adózók letöltése Excelben", "description": "A keresésnek és a szűrőknek megfelelő adózók egyetlen XLSX-táblázatban (`adozo.xlsx`), lapozás nélkül, legfeljebb 50 000 sor (felette 422). Oszlopok: azonosító, név, adószám, adóazonosító, aktív, hátralék-értesítés, ASP-képviselő adószáma, adózás módja, áfa-gyakoriság, munkavégzés jellege, NAV-egyenleg, önkormányzati egyenleg, végrehajtható köztartozás, heti munkaóra, a négy értesítésicím-lista, megjegyzés, ÜPO-n szerepel, az adófolyószámla PDF/XLSX/XML hivatkozása és az önkormányzatok (zölddel, ahol van letöltött adószámla). Logikai értéknél „X” jelöli az igazat. Ez a fájl (az `Azonosító` oszloppal) a `POST /trustees/import` kiinduló táblázata. Jogosultság: bármely szerepkör, bármely csomag.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "order_column": { "type": "string", "nullable": true, "enum": [ "name", "sum_debt", "sum_municipality_debt", "sum_public_debt", "unclosed_messages_count", "relationship_week_hours" ], "default": "name", "description": "Rendezési oszlop: `name` név (alapérték), `sum_debt` NAV-egyenleg, `sum_municipality_debt` tárgyévi önkormányzati egyenleg, `sum_public_debt` végrehajtható köztartozás, `unclosed_messages_count` le nem zárt tárhely-üzenetek száma, `relationship_week_hours` heti munkaóra a saját foglalkoztatóknál." }, "order_direction": { "type": "string", "nullable": true, "enum": [ "asc", "desc" ], "default": "asc", "description": "Rendezési irány: `asc` növekvő (alapérték), `desc` csökkenő." }, "search": { "type": "string", "nullable": true, "example": "alfa kft", "description": "Szabad szavas keresés. A szöveget szavakra bontja (szóköz, kötőjel, pont, vessző stb. mentén), és minden szónak szerepelnie kell az alábbiak valamelyikében: név, adószám, adóazonosító jel, adózás módja, áfa-gyakoriság, ASP-képviselő adószáma, megjegyzés. Cégforma-rövidítésnél a teljes formára is keres („Kft” a „korlátolt felelősségű társaság” nevet is megtalálja)." }, "customer_portal_id": { "type": "integer", "nullable": true, "description": "Csak ennek az ügyfélkapunak (`CustomerPortal.id`) az adózói. A hívó irodájához kell tartoznia, különben 422." }, "active": { "type": "boolean", "nullable": true, "description": "`true`: csak aktív, `false`: csak inaktív adózók. Elhagyva mindkettő (az API alapból az inaktív adózókat is visszaadja, a felület listájával ellentétben)." }, "has_simplified_employee_from": { "type": "string", "format": "date", "nullable": true, "example": "2026-10-01", "description": "Csak azok az adózók, akiknek van olyan egyszerűsített foglalkoztatottja (EFO), akinek a foglalkoztatása ezen a napon vagy később kezdődött (ÉÉÉÉ-HH-NN). A `has_simplified_employee_to` mezővel együtt intervallum." }, "has_simplified_employee_to": { "type": "string", "format": "date", "nullable": true, "example": "2026-10-31", "description": "Csak azok az adózók, akiknek van olyan EFO-ja, akinek a foglalkoztatása ezen a napon vagy korábban kezdődött (ÉÉÉÉ-HH-NN)." }, "has_simplified_employee": { "type": "boolean", "nullable": true, "description": "`true`: csak akinek van egyszerűsített foglalkoztatottja (EFO), `false`: csak akinek nincs." }, "has_employee": { "type": "boolean", "nullable": true, "description": "`true`: csak akinek van biztosítottja (bejelentett foglalkoztatottja), `false`: csak akinek nincs." }, "taxation_type": { "type": "string", "nullable": true, "enum": [ "VSZJA", "Átalányadó", "Új KATA", "Társasági adó", "KIVA" ], "description": "Szűrés az adózás módjára. Az adózás módja a NAV-törzsadat alapján: `VSZJA` (vállalkozói személyi jövedelemadó; ez az alapérték, ha a törzsadatból más nem olvasható ki), `Átalányadó` (egyéni vállalkozói átalányadó), `Új KATA` (kisadózó vállalkozások tételes adója), `Társasági adó`, `KIVA` (kisvállalati adó)." }, "vat_period": { "type": "string", "nullable": true, "enum": [ "Havi", "Negyedéves", "Éves" ], "description": "Szűrés az áfabevallás gyakoriságára (`Havi`, `Negyedéves`, `Éves`)." }, "upo_available": { "type": "boolean", "nullable": true, "description": "`true`: csak akik szerepelnek az ügyfélkapu meghatalmazói között a NAV Online Ügyfélportálon (ÜPO), `false`: csak akik már nem (pl. megszűnt a megbízás)." }, "koma_status": { "type": "string", "nullable": true, "enum": [ "included_qualified", "included_not_qualified", "in_progress", "not_included_qualified", "not_included_not_qualified" ], "description": "Szűrés a törzsadatok KOMA-állapotára (legalább egy törzsadat-lapnak ilyen az állapota). A Köztartozásmentes Adózói Adatbázis (KOMA) szerinti állapot: `included_qualified` szerepel, minősített; `included_not_qualified` szerepel, nem minősített; `in_progress` a felvételi kérelem beküldése vagy feldolgozása folyamatban; `not_included_qualified` nem szerepel, minősített; `not_included_not_qualified` nem szerepel, nem minősített." } } } } } }, "responses": { "200": { "description": "Az XLSX-fájl (letöltésként).", "content": { "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/trustees/trustee-role-labels": { "get": { "tags": [ "Adózók" ], "summary": "Törzsadat-címkék listája", "description": "A NAV-törzsadatokban előforduló mezőnevek (címkék, pl. „Székhelycíme”, „KIVA adóalanyiság kezdete”) ábécérendben. Ezekből választható ki, mely törzsadat-mezőket gyűjtse ki a `POST /trustees/bulk-roles-query`. A lista minden irodának azonos. Jogosultság: bármely bejelentkezett felhasználó.", "responses": { "200": { "description": "A címkék tömbje.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TrusteeRoleLabel" } } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" } } } }, "/trustees/download-import-sample": { "get": { "tags": [ "Adózók" ], "summary": "Adózó-import mintatáblázat letöltése", "description": "Az adózó-import oszlopait mutató minta XLSX (`adozo_import_minta.xlsx`), két példasorral. Oszlopok: Név (csak tájékoztató, importáláskor figyelmen kívül marad), Aktív, Hátralék értesítés, ASP - Képviselő cég adószáma, Értesítési emailek, Könyvelői emailek, Bérszámfejtő emailek, Adótanácsadó emailek, Megjegyzés. Figyelem: a mintából hiányzik a kötelező `Azonosító` oszlop; importhoz a `POST /trustees/export` fájlját érdemes kiindulásnak venni. Jogosultság: bármely bejelentkezett felhasználó.", "responses": { "200": { "description": "A minta XLSX-fájl (letöltésként).", "content": { "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" } } } }, "/trustees/import": { "post": { "tags": [ "Adózók" ], "summary": "Adózók tömeges módosítása táblázatból", "description": "Meglévő adózók irodai beállításainak tömeges módosítása egy XLSX/XLS/CSV-fájlból (az első sor a fejléc). Új adózót nem hoz létre. Sorai az `Azonosító` (az adózó `id`-ja, kötelező, egyedi) alapján frissítik az adózót, és a sor MINDEN oszlopa felülír: Aktív és Hátralék értesítés (bármely nem üres cella igaz, például „X”; üres cella hamis), ASP - Képviselő cég adószáma, a négy címlista vesszővel elválasztva (az érvénytelen címek kimaradnak), Megjegyzés; a Név oszlop figyelmen kívül marad. Az egész fájl egy tranzakció: bármely hibás sornál semmi nem mentődik. Ha egy azonosító nem a felhasználó által látható adózóé, a válasz 403 („Adózót nem lehet manuálisan létrehozni”). Jogosultság: menedzser és könyvelő szerepkör (adózó szerepkör: 403), bármely csomag; aktiválásnál a csomag aktív-adózó korlátja is érvényes.", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "import_file" ], "properties": { "import_file": { "type": "string", "format": "binary", "description": "Az importálandó fájl (xls, xlsx vagy csv)." } } } } } }, "responses": { "200": { "description": "Sikeres import, üres válasz." }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/trustees/{trusteeId}/send-roles-mail": { "post": { "tags": [ "Adózók" ], "summary": "Adózó törzsadatainak elküldése emailben", "description": "Az adózó NAV-törzsadatait küldi el a megadott címekre. Tárgy: „{felhasználó neve} továbbította {adózó neve} törzsadatait”; a levélben a megjegyzés és az adózó neve, mellékletként a törzsadat XLSX (`{nev}_torzsadat.xlsx`, ugyanaz, mint a `POST /trustees/{trusteeId}/export-roles` fájlja). A levél az iroda beállított feladónevével és válaszcímével megy ki, címenként külön levélként, és megjelenik az Elküldött levelek között (`/sent-mails`). Jogosultság: törzsadat-olvasási jog (menedzser, könyvelő, adózó szerepkör) az Alap vagy Prémium csomagban; 403, ha az adózónak nincs törzsadata. Üres választ ad.", "parameters": [ { "name": "trusteeId", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "Az adózó azonosítója (`Trustee.id`). Csak a hívó irodájának aktív ügyfélkapuihoz tartozó, a felhasználó által látható adózó adható meg (inaktív adózó is), különben 404.", "example": 121622 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "emails" ], "properties": { "emails": { "type": "array", "items": { "type": "string", "format": "email" }, "example": [ "ugyfel@example.hu" ], "minItems": 1, "description": "A címzett email címek (legalább egy). Minden címre külön levél megy. Tetszőleges cím megadható; a felület alapból az adózó értesítési címeit (`emails`) ajánlja." }, "note": { "type": "string", "nullable": true, "example": "Kérlek, rendezd a hónap végéig.", "description": "Szabad szöveges megjegyzés, amely a levél elején „Megjegyzés:” címkével jelenik meg (sortörések megmaradnak)." } } } } } }, "responses": { "200": { "description": "A levelek kiküldése elindult, üres válasz." }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/trustees/{trusteeId}/send-tax-types-mail": { "post": { "tags": [ "Adózók" ], "summary": "Adózó NAV-egyenlegének elküldése emailben", "description": "Az adózó NAV-adófolyószámlájának adónemenkénti egyenlegét küldi el a megadott címekre (pl. magának az adózónak). Tárgy: „{összeg} NAV adótartozás áll fenn - {adózó neve}” (túlfizetésnél „NAV túlfizetés”). A levélben a megjegyzés, adónemenként az egyenleg (+ tartozás / − túlfizetés), az utolsó kötelezettség dátuma és a befizetési számlaszám, az összesen sor, és hogy mikor frissültek az adatok. Mellékletek: az egyenleg XLSX-ben (`{nev}_nav_egyenleg_ÉÉÉÉ_HH_NN.xlsx`), és ha van, a legutóbbi NAV-adófolyószámla PDF. A levél az iroda beállított feladónevével és válaszcímével megy ki, címenként külön levélként, és megjelenik az Elküldött levelek között (`/sent-mails`). Jogosultság: bármely szerepkör, aki látja az adózót, bármely csomag. Üres választ ad.", "parameters": [ { "name": "trusteeId", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "Az adózó azonosítója (`Trustee.id`). Csak a hívó irodájának aktív ügyfélkapuihoz tartozó, a felhasználó által látható adózó adható meg (inaktív adózó is), különben 404.", "example": 121622 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "emails" ], "properties": { "emails": { "type": "array", "items": { "type": "string", "format": "email" }, "example": [ "ugyfel@example.hu" ], "minItems": 1, "description": "A címzett email címek (legalább egy). Minden címre külön levél megy. Tetszőleges cím megadható; a felület alapból az adózó értesítési címeit (`emails`) ajánlja." }, "note": { "type": "string", "nullable": true, "example": "Kérlek, rendezd a hónap végéig.", "description": "Szabad szöveges megjegyzés, amely a levél elején „Megjegyzés:” címkével jelenik meg (sortörések megmaradnak)." } } } } } }, "responses": { "200": { "description": "A levelek kiküldése elindult, üres válasz." }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/trustees/{trusteeId}/send-public-debts-mail": { "post": { "tags": [ "Adózók" ], "summary": "Adózó végrehajtható köztartozásainak elküldése emailben", "description": "Az adózó végrehajtható köztartozásait küldi el a megadott címekre. Tárgy: „{összeg} végrehajtható köztartozás áll fenn - {adózó neve}”. A levélben a megjegyzés, jogcímenként a jogcím neve, kódja és a tartozás, az összesen sor, és hogy mikor frissültek az adatok. Melléklet nincs. A levél az iroda beállított feladónevével és válaszcímével megy ki, címenként külön levélként, és megjelenik az Elküldött levelek között (`/sent-mails`). Jogosultság: bármely szerepkör, aki látja az adózót, csak Prémium csomagban (más csomagban 403). Üres választ ad.", "parameters": [ { "name": "trusteeId", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "Az adózó azonosítója (`Trustee.id`). Csak a hívó irodájának aktív ügyfélkapuihoz tartozó, a felhasználó által látható adózó adható meg (inaktív adózó is), különben 404.", "example": 121622 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "emails" ], "properties": { "emails": { "type": "array", "items": { "type": "string", "format": "email" }, "example": [ "ugyfel@example.hu" ], "minItems": 1, "description": "A címzett email címek (legalább egy). Minden címre külön levél megy. Tetszőleges cím megadható; a felület alapból az adózó értesítési címeit (`emails`) ajánlja." }, "note": { "type": "string", "nullable": true, "example": "Kérlek, rendezd a hónap végéig.", "description": "Szabad szöveges megjegyzés, amely a levél elején „Megjegyzés:” címkével jelenik meg (sortörések megmaradnak)." } } } } } }, "responses": { "200": { "description": "A levelek kiküldése elindult, üres válasz." }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/trustees/{trusteeId}/send-municipalities-mail": { "post": { "tags": [ "Adózók" ], "summary": "Adózó önkormányzati adószámláinak elküldése emailben", "description": "Az adózó tárgyévi önkormányzati (ASP) adószámláinak egyenlegét küldi el a megadott címekre. Tárgy: „{összeg} önkormányzati adótartozás áll fenn - {adózó neve}” (túlfizetésnél „önkormányzati túlfizetés”). A levélben a megjegyzés, önkormányzatonként és adónemenként az egyenleg (+ tartozás / − túlfizetés) és a befizetési számlaszám, az összesen sor, és hogy mikor frissültek az adatok. Mellékletek: az egyenleg XLSX-ben (`{nev}_onkormanyzati_egyenleg_ÉÉÉÉ_HH_NN.xlsx`) és minden tárgyévi önkormányzati adószámla-kivonat (PDF). A levél az iroda beállított feladónevével és válaszcímével megy ki, címenként külön levélként, és megjelenik az Elküldött levelek között (`/sent-mails`). Jogosultság: bármely szerepkör, aki látja az adózót, csak Prémium csomagban (más csomagban 403). Üres választ ad.", "parameters": [ { "name": "trusteeId", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "Az adózó azonosítója (`Trustee.id`). Csak a hívó irodájának aktív ügyfélkapuihoz tartozó, a felhasználó által látható adózó adható meg (inaktív adózó is), különben 404.", "example": 121622 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "emails" ], "properties": { "emails": { "type": "array", "items": { "type": "string", "format": "email" }, "example": [ "ugyfel@example.hu" ], "minItems": 1, "description": "A címzett email címek (legalább egy). Minden címre külön levél megy. Tetszőleges cím megadható; a felület alapból az adózó értesítési címeit (`emails`) ajánlja." }, "note": { "type": "string", "nullable": true, "example": "Kérlek, rendezd a hónap végéig.", "description": "Szabad szöveges megjegyzés, amely a levél elején „Megjegyzés:” címkével jelenik meg (sortörések megmaradnak)." } } } } } }, "responses": { "200": { "description": "A levelek kiküldése elindult, üres válasz." }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/trustees/bulk-export-tax-files": { "post": { "tags": [ "Adózók" ], "summary": "Adózók adófolyószámlájának csoportos letöltése vagy kiküldése", "description": "Az adózók legutóbbi NAV-adófolyószámla fájljai a választott formátumban, ZIP-be csomagolva. A ZIP-ben a fájlok az eredeti (letöltéskori) nevükön vannak. A művelet a keresésnek és a szűrőknek megfelelő adózókra fut (ugyanazok a mezők, mint a `POST /trustees/search` kérésében, lapozás nélkül; az `active` szűrő nélkül az inaktív adózók is). Két mód van. (1) `emails` nélkül a válasz maga a ZIP-fájl (`application/zip`), adózónként egy fájllal; legfeljebb 5 adózó esetén, felette 422 azzal, hogy az emailes küldést kell választani. (2) Ha `emails` meg van adva, a válasz üres 200, és a ZIP-et a rendszer emailben küldi el minden megadott címre (címenként külön levél): tárgy „Exportálás kész: {n} adózó adófolyószámlája {format} formátumban”, szöveg „A művelet sikeresen lefutott, az eredményt a csatolmányok között találod.”, a ZIP mellékletként; 5 adózónként részletekre bontva, ilyenkor több levél megy („ - 1/3 részlet” a tárgyban). A levél az iroda feladónevével és válaszcímével megy ki, és megjelenik az Elküldött levelek között. Ha egy adózó sem felel meg (vagy egyiknél sincs meg a kért adat), 422. A ZIP neve: „{n} adózó adófolyószámlája {format} formátumban ÉÉÉÉ-HH-NN.zip”. Jogosultság: bármely szerepkör, csak Prémium csomagban (csoportos műveletek; más csomagban 403).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "pdf", "xlsx", "xml" ], "description": "Az adófolyószámla formátuma: `pdf`, `xlsx` vagy `xml`. Csak azok az adózók kerülnek bele, akiknél van ilyen formátumú fájl." }, "emails": { "type": "array", "items": { "type": "string", "format": "email" }, "example": [ "ugyfel@example.hu" ], "nullable": true, "description": "Ha legalább egy címet megadsz, az eredmény nem a válaszban jön, hanem emailben megy ezekre a címekre (címenként külön levél). Üresen vagy elhagyva a válasz maga a ZIP-fájl." }, "order_column": { "type": "string", "nullable": true, "enum": [ "name", "sum_debt", "sum_municipality_debt", "sum_public_debt", "unclosed_messages_count", "relationship_week_hours" ], "default": "name", "description": "Rendezési oszlop: `name` név (alapérték), `sum_debt` NAV-egyenleg, `sum_municipality_debt` tárgyévi önkormányzati egyenleg, `sum_public_debt` végrehajtható köztartozás, `unclosed_messages_count` le nem zárt tárhely-üzenetek száma, `relationship_week_hours` heti munkaóra a saját foglalkoztatóknál." }, "order_direction": { "type": "string", "nullable": true, "enum": [ "asc", "desc" ], "default": "asc", "description": "Rendezési irány: `asc` növekvő (alapérték), `desc` csökkenő." }, "search": { "type": "string", "nullable": true, "example": "alfa kft", "description": "Szabad szavas keresés. A szöveget szavakra bontja (szóköz, kötőjel, pont, vessző stb. mentén), és minden szónak szerepelnie kell az alábbiak valamelyikében: név, adószám, adóazonosító jel, adózás módja, áfa-gyakoriság, ASP-képviselő adószáma, megjegyzés. Cégforma-rövidítésnél a teljes formára is keres („Kft” a „korlátolt felelősségű társaság” nevet is megtalálja)." }, "customer_portal_id": { "type": "integer", "nullable": true, "description": "Csak ennek az ügyfélkapunak (`CustomerPortal.id`) az adózói. A hívó irodájához kell tartoznia, különben 422." }, "active": { "type": "boolean", "nullable": true, "description": "`true`: csak aktív, `false`: csak inaktív adózók. Elhagyva mindkettő (az API alapból az inaktív adózókat is visszaadja, a felület listájával ellentétben)." }, "has_simplified_employee_from": { "type": "string", "format": "date", "nullable": true, "example": "2026-10-01", "description": "Csak azok az adózók, akiknek van olyan egyszerűsített foglalkoztatottja (EFO), akinek a foglalkoztatása ezen a napon vagy később kezdődött (ÉÉÉÉ-HH-NN). A `has_simplified_employee_to` mezővel együtt intervallum." }, "has_simplified_employee_to": { "type": "string", "format": "date", "nullable": true, "example": "2026-10-31", "description": "Csak azok az adózók, akiknek van olyan EFO-ja, akinek a foglalkoztatása ezen a napon vagy korábban kezdődött (ÉÉÉÉ-HH-NN)." }, "has_simplified_employee": { "type": "boolean", "nullable": true, "description": "`true`: csak akinek van egyszerűsített foglalkoztatottja (EFO), `false`: csak akinek nincs." }, "has_employee": { "type": "boolean", "nullable": true, "description": "`true`: csak akinek van biztosítottja (bejelentett foglalkoztatottja), `false`: csak akinek nincs." }, "taxation_type": { "type": "string", "nullable": true, "enum": [ "VSZJA", "Átalányadó", "Új KATA", "Társasági adó", "KIVA" ], "description": "Szűrés az adózás módjára. Az adózás módja a NAV-törzsadat alapján: `VSZJA` (vállalkozói személyi jövedelemadó; ez az alapérték, ha a törzsadatból más nem olvasható ki), `Átalányadó` (egyéni vállalkozói átalányadó), `Új KATA` (kisadózó vállalkozások tételes adója), `Társasági adó`, `KIVA` (kisvállalati adó)." }, "vat_period": { "type": "string", "nullable": true, "enum": [ "Havi", "Negyedéves", "Éves" ], "description": "Szűrés az áfabevallás gyakoriságára (`Havi`, `Negyedéves`, `Éves`)." }, "upo_available": { "type": "boolean", "nullable": true, "description": "`true`: csak akik szerepelnek az ügyfélkapu meghatalmazói között a NAV Online Ügyfélportálon (ÜPO), `false`: csak akik már nem (pl. megszűnt a megbízás)." }, "koma_status": { "type": "string", "nullable": true, "enum": [ "included_qualified", "included_not_qualified", "in_progress", "not_included_qualified", "not_included_not_qualified" ], "description": "Szűrés a törzsadatok KOMA-állapotára (legalább egy törzsadat-lapnak ilyen az állapota). A Köztartozásmentes Adózói Adatbázis (KOMA) szerinti állapot: `included_qualified` szerepel, minősített; `included_not_qualified` szerepel, nem minősített; `in_progress` a felvételi kérelem beküldése vagy feldolgozása folyamatban; `not_included_qualified` nem szerepel, minősített; `not_included_not_qualified` nem szerepel, nem minősített." } }, "required": [ "format" ] } } } }, "responses": { "200": { "description": "`emails` nélkül: a ZIP-fájl (letöltésként). `emails` megadásával: üres válasz, az eredmény emailben megy.", "content": { "application/zip": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/trustees/bulk-export-roles": { "post": { "tags": [ "Adózók" ], "summary": "Adózók törzsadatainak csoportos letöltése vagy kiküldése", "description": "Az adózók NAV-törzsadatai adózónként egy XLSX-fájlban (ugyanaz, mint a `POST /trustees/{trusteeId}/export-roles` fájlja), ZIP-be csomagolva. Csak a törzsadattal rendelkező adózók kerülnek bele. A ZIP-ben a fájlok neve „{adózó neve} - Törzsadatok.xlsx” (azonos nevű adózóknál „ (2)” stb. utótaggal). A művelet a keresésnek és a szűrőknek megfelelő adózókra fut (ugyanazok a mezők, mint a `POST /trustees/search` kérésében, lapozás nélkül; az `active` szűrő nélkül az inaktív adózók is). Két mód van. (1) `emails` nélkül a válasz maga a ZIP-fájl (`application/zip`), adózónként egy fájllal; legfeljebb 2000 adózó esetén, felette 422 azzal, hogy az emailes küldést kell választani. (2) Ha `emails` meg van adva, a válasz üres 200, és a ZIP-et a rendszer emailben küldi el minden megadott címre (címenként külön levél): tárgy „Exportálás kész: {n} adózó törzsadata”, szöveg „A művelet sikeresen lefutott, az eredményt a csatolmányok között találod.”, a ZIP mellékletként; 2000 adózónként részletekre bontva, ilyenkor több levél megy („ - 1/3 részlet” a tárgyban). A levél az iroda feladónevével és válaszcímével megy ki, és megjelenik az Elküldött levelek között. Ha egy adózó sem felel meg (vagy egyiknél sincs meg a kért adat), 422. A ZIP neve: „{n} adózó törzsadata ÉÉÉÉ-HH-NN.zip”. Jogosultság: bármely szerepkör, csak Prémium csomagban (csoportos műveletek; más csomagban 403).", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "emails": { "type": "array", "items": { "type": "string", "format": "email" }, "example": [ "ugyfel@example.hu" ], "nullable": true, "description": "Ha legalább egy címet megadsz, az eredmény nem a válaszban jön, hanem emailben megy ezekre a címekre (címenként külön levél). Üresen vagy elhagyva a válasz maga a ZIP-fájl." }, "order_column": { "type": "string", "nullable": true, "enum": [ "name", "sum_debt", "sum_municipality_debt", "sum_public_debt", "unclosed_messages_count", "relationship_week_hours" ], "default": "name", "description": "Rendezési oszlop: `name` név (alapérték), `sum_debt` NAV-egyenleg, `sum_municipality_debt` tárgyévi önkormányzati egyenleg, `sum_public_debt` végrehajtható köztartozás, `unclosed_messages_count` le nem zárt tárhely-üzenetek száma, `relationship_week_hours` heti munkaóra a saját foglalkoztatóknál." }, "order_direction": { "type": "string", "nullable": true, "enum": [ "asc", "desc" ], "default": "asc", "description": "Rendezési irány: `asc` növekvő (alapérték), `desc` csökkenő." }, "search": { "type": "string", "nullable": true, "example": "alfa kft", "description": "Szabad szavas keresés. A szöveget szavakra bontja (szóköz, kötőjel, pont, vessző stb. mentén), és minden szónak szerepelnie kell az alábbiak valamelyikében: név, adószám, adóazonosító jel, adózás módja, áfa-gyakoriság, ASP-képviselő adószáma, megjegyzés. Cégforma-rövidítésnél a teljes formára is keres („Kft” a „korlátolt felelősségű társaság” nevet is megtalálja)." }, "customer_portal_id": { "type": "integer", "nullable": true, "description": "Csak ennek az ügyfélkapunak (`CustomerPortal.id`) az adózói. A hívó irodájához kell tartoznia, különben 422." }, "active": { "type": "boolean", "nullable": true, "description": "`true`: csak aktív, `false`: csak inaktív adózók. Elhagyva mindkettő (az API alapból az inaktív adózókat is visszaadja, a felület listájával ellentétben)." }, "has_simplified_employee_from": { "type": "string", "format": "date", "nullable": true, "example": "2026-10-01", "description": "Csak azok az adózók, akiknek van olyan egyszerűsített foglalkoztatottja (EFO), akinek a foglalkoztatása ezen a napon vagy később kezdődött (ÉÉÉÉ-HH-NN). A `has_simplified_employee_to` mezővel együtt intervallum." }, "has_simplified_employee_to": { "type": "string", "format": "date", "nullable": true, "example": "2026-10-31", "description": "Csak azok az adózók, akiknek van olyan EFO-ja, akinek a foglalkoztatása ezen a napon vagy korábban kezdődött (ÉÉÉÉ-HH-NN)." }, "has_simplified_employee": { "type": "boolean", "nullable": true, "description": "`true`: csak akinek van egyszerűsített foglalkoztatottja (EFO), `false`: csak akinek nincs." }, "has_employee": { "type": "boolean", "nullable": true, "description": "`true`: csak akinek van biztosítottja (bejelentett foglalkoztatottja), `false`: csak akinek nincs." }, "taxation_type": { "type": "string", "nullable": true, "enum": [ "VSZJA", "Átalányadó", "Új KATA", "Társasági adó", "KIVA" ], "description": "Szűrés az adózás módjára. Az adózás módja a NAV-törzsadat alapján: `VSZJA` (vállalkozói személyi jövedelemadó; ez az alapérték, ha a törzsadatból más nem olvasható ki), `Átalányadó` (egyéni vállalkozói átalányadó), `Új KATA` (kisadózó vállalkozások tételes adója), `Társasági adó`, `KIVA` (kisvállalati adó)." }, "vat_period": { "type": "string", "nullable": true, "enum": [ "Havi", "Negyedéves", "Éves" ], "description": "Szűrés az áfabevallás gyakoriságára (`Havi`, `Negyedéves`, `Éves`)." }, "upo_available": { "type": "boolean", "nullable": true, "description": "`true`: csak akik szerepelnek az ügyfélkapu meghatalmazói között a NAV Online Ügyfélportálon (ÜPO), `false`: csak akik már nem (pl. megszűnt a megbízás)." }, "koma_status": { "type": "string", "nullable": true, "enum": [ "included_qualified", "included_not_qualified", "in_progress", "not_included_qualified", "not_included_not_qualified" ], "description": "Szűrés a törzsadatok KOMA-állapotára (legalább egy törzsadat-lapnak ilyen az állapota). A Köztartozásmentes Adózói Adatbázis (KOMA) szerinti állapot: `included_qualified` szerepel, minősített; `included_not_qualified` szerepel, nem minősített; `in_progress` a felvételi kérelem beküldése vagy feldolgozása folyamatban; `not_included_qualified` nem szerepel, minősített; `not_included_not_qualified` nem szerepel, nem minősített." } } } } } }, "responses": { "200": { "description": "`emails` nélkül: a ZIP-fájl (letöltésként). `emails` megadásával: üres válasz, az eredmény emailben megy.", "content": { "application/zip": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/trustees/bulk-export-app-csv": { "post": { "tags": [ "Adózók" ], "summary": "Adózók havi EFO APP CSV-jének csoportos letöltése vagy kiküldése", "description": "Az adózók egyszerűsített foglalkoztatottjai (EFO) a megadott időszakra, adózónként egy APP CSV-fájlban (ugyanaz a formátum, mint a `POST /trustees/{trusteeId}/export-app-csv` fájlja), ZIP-be csomagolva. Minden szűrt adózó belekerül (EFO nélkül csak fejléccel). A ZIP-ben a fájlok neve „{adózó neve} - (EFO) App - ÉÉÉÉ.HH hó.csv” (az időszak kezdete szerint). A művelet a keresésnek és a szűrőknek megfelelő adózókra fut (ugyanazok a mezők, mint a `POST /trustees/search` kérésében, lapozás nélkül; az `active` szűrő nélkül az inaktív adózók is). Két mód van. (1) `emails` nélkül a válasz maga a ZIP-fájl (`application/zip`), adózónként egy fájllal; legfeljebb 2000 adózó esetén, felette 422 azzal, hogy az emailes küldést kell választani. (2) Ha `emails` meg van adva, a válasz üres 200, és a ZIP-et a rendszer emailben küldi el minden megadott címre (címenként külön levél): tárgy „Exportálás kész: {n} adózó APP CSV”, szöveg „A művelet sikeresen lefutott, az eredményt a csatolmányok között találod.”, a ZIP mellékletként; 2000 adózónként részletekre bontva, ilyenkor több levél megy („ - 1/3 részlet” a tárgyban). A levél az iroda feladónevével és válaszcímével megy ki, és megjelenik az Elküldött levelek között. Ha egy adózó sem felel meg (vagy egyiknél sincs meg a kért adat), 422. A ZIP neve: „{n} adózó APP CSV ÉÉÉÉ-HH-NN.zip”. Jogosultság: bármely szerepkör, csak Prémium csomagban (csoportos műveletek; más csomagban 403).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "period_start": { "type": "string", "format": "date", "example": "2026-10-01", "description": "Az időszak első napja (ÉÉÉÉ-HH-NN), jellemzően a hónap első napja." }, "period_end": { "type": "string", "format": "date", "example": "2026-10-31", "description": "Az időszak utolsó napja (ÉÉÉÉ-HH-NN), jellemzően a hónap utolsó napja." }, "emails": { "type": "array", "items": { "type": "string", "format": "email" }, "example": [ "ugyfel@example.hu" ], "nullable": true, "description": "Ha legalább egy címet megadsz, az eredmény nem a válaszban jön, hanem emailben megy ezekre a címekre (címenként külön levél). Üresen vagy elhagyva a válasz maga a ZIP-fájl." }, "order_column": { "type": "string", "nullable": true, "enum": [ "name", "sum_debt", "sum_municipality_debt", "sum_public_debt", "unclosed_messages_count", "relationship_week_hours" ], "default": "name", "description": "Rendezési oszlop: `name` név (alapérték), `sum_debt` NAV-egyenleg, `sum_municipality_debt` tárgyévi önkormányzati egyenleg, `sum_public_debt` végrehajtható köztartozás, `unclosed_messages_count` le nem zárt tárhely-üzenetek száma, `relationship_week_hours` heti munkaóra a saját foglalkoztatóknál." }, "order_direction": { "type": "string", "nullable": true, "enum": [ "asc", "desc" ], "default": "asc", "description": "Rendezési irány: `asc` növekvő (alapérték), `desc` csökkenő." }, "search": { "type": "string", "nullable": true, "example": "alfa kft", "description": "Szabad szavas keresés. A szöveget szavakra bontja (szóköz, kötőjel, pont, vessző stb. mentén), és minden szónak szerepelnie kell az alábbiak valamelyikében: név, adószám, adóazonosító jel, adózás módja, áfa-gyakoriság, ASP-képviselő adószáma, megjegyzés. Cégforma-rövidítésnél a teljes formára is keres („Kft” a „korlátolt felelősségű társaság” nevet is megtalálja)." }, "customer_portal_id": { "type": "integer", "nullable": true, "description": "Csak ennek az ügyfélkapunak (`CustomerPortal.id`) az adózói. A hívó irodájához kell tartoznia, különben 422." }, "active": { "type": "boolean", "nullable": true, "description": "`true`: csak aktív, `false`: csak inaktív adózók. Elhagyva mindkettő (az API alapból az inaktív adózókat is visszaadja, a felület listájával ellentétben)." }, "has_simplified_employee_from": { "type": "string", "format": "date", "nullable": true, "example": "2026-10-01", "description": "Csak azok az adózók, akiknek van olyan egyszerűsített foglalkoztatottja (EFO), akinek a foglalkoztatása ezen a napon vagy később kezdődött (ÉÉÉÉ-HH-NN). A `has_simplified_employee_to` mezővel együtt intervallum." }, "has_simplified_employee_to": { "type": "string", "format": "date", "nullable": true, "example": "2026-10-31", "description": "Csak azok az adózók, akiknek van olyan EFO-ja, akinek a foglalkoztatása ezen a napon vagy korábban kezdődött (ÉÉÉÉ-HH-NN)." }, "has_simplified_employee": { "type": "boolean", "nullable": true, "description": "`true`: csak akinek van egyszerűsített foglalkoztatottja (EFO), `false`: csak akinek nincs." }, "has_employee": { "type": "boolean", "nullable": true, "description": "`true`: csak akinek van biztosítottja (bejelentett foglalkoztatottja), `false`: csak akinek nincs." }, "taxation_type": { "type": "string", "nullable": true, "enum": [ "VSZJA", "Átalányadó", "Új KATA", "Társasági adó", "KIVA" ], "description": "Szűrés az adózás módjára. Az adózás módja a NAV-törzsadat alapján: `VSZJA` (vállalkozói személyi jövedelemadó; ez az alapérték, ha a törzsadatból más nem olvasható ki), `Átalányadó` (egyéni vállalkozói átalányadó), `Új KATA` (kisadózó vállalkozások tételes adója), `Társasági adó`, `KIVA` (kisvállalati adó)." }, "vat_period": { "type": "string", "nullable": true, "enum": [ "Havi", "Negyedéves", "Éves" ], "description": "Szűrés az áfabevallás gyakoriságára (`Havi`, `Negyedéves`, `Éves`)." }, "upo_available": { "type": "boolean", "nullable": true, "description": "`true`: csak akik szerepelnek az ügyfélkapu meghatalmazói között a NAV Online Ügyfélportálon (ÜPO), `false`: csak akik már nem (pl. megszűnt a megbízás)." }, "koma_status": { "type": "string", "nullable": true, "enum": [ "included_qualified", "included_not_qualified", "in_progress", "not_included_qualified", "not_included_not_qualified" ], "description": "Szűrés a törzsadatok KOMA-állapotára (legalább egy törzsadat-lapnak ilyen az állapota). A Köztartozásmentes Adózói Adatbázis (KOMA) szerinti állapot: `included_qualified` szerepel, minősített; `included_not_qualified` szerepel, nem minősített; `in_progress` a felvételi kérelem beküldése vagy feldolgozása folyamatban; `not_included_qualified` nem szerepel, minősített; `not_included_not_qualified` nem szerepel, nem minősített." } }, "required": [ "period_start", "period_end" ] } } } }, "responses": { "200": { "description": "`emails` nélkül: a ZIP-fájl (letöltésként). `emails` megadásával: üres válasz, az eredmény emailben megy.", "content": { "application/zip": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/trustees/bulk-export-ebev-xlsx": { "post": { "tags": [ "Adózók" ], "summary": "Adózók havi EFO eBEV XLSX-ének csoportos letöltése vagy kiküldése", "description": "Az adózók egyszerűsített foglalkoztatottjai (EFO) a megadott időszakra, adózónként egy eBEV XLSX-fájlban (ugyanaz a formátum, mint a `POST /trustees/{trusteeId}/export-ebev-xlsx` fájlja), ZIP-be csomagolva. Minden szűrt adózó belekerül (EFO nélkül csak fejléccel). A ZIP-ben a fájlok neve „{adózó neve} - (EFO) EBEV - ÉÉÉÉ.HH hó.xlsx”. A művelet a keresésnek és a szűrőknek megfelelő adózókra fut (ugyanazok a mezők, mint a `POST /trustees/search` kérésében, lapozás nélkül; az `active` szűrő nélkül az inaktív adózók is). Két mód van. (1) `emails` nélkül a válasz maga a ZIP-fájl (`application/zip`), adózónként egy fájllal; legfeljebb 2000 adózó esetén, felette 422 azzal, hogy az emailes küldést kell választani. (2) Ha `emails` meg van adva, a válasz üres 200, és a ZIP-et a rendszer emailben küldi el minden megadott címre (címenként külön levél): tárgy „Exportálás kész: {n} adózó EBEV XLSX”, szöveg „A művelet sikeresen lefutott, az eredményt a csatolmányok között találod.”, a ZIP mellékletként; 2000 adózónként részletekre bontva, ilyenkor több levél megy („ - 1/3 részlet” a tárgyban). A levél az iroda feladónevével és válaszcímével megy ki, és megjelenik az Elküldött levelek között. Ha egy adózó sem felel meg (vagy egyiknél sincs meg a kért adat), 422. A ZIP neve: „{n} adózó EBEV XLSX ÉÉÉÉ-HH-NN.zip”. Jogosultság: bármely szerepkör, csak Prémium csomagban (csoportos műveletek; más csomagban 403).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "period_start": { "type": "string", "format": "date", "example": "2026-10-01", "description": "Az időszak első napja (ÉÉÉÉ-HH-NN), jellemzően a hónap első napja." }, "period_end": { "type": "string", "format": "date", "example": "2026-10-31", "description": "Az időszak utolsó napja (ÉÉÉÉ-HH-NN), jellemzően a hónap utolsó napja." }, "emails": { "type": "array", "items": { "type": "string", "format": "email" }, "example": [ "ugyfel@example.hu" ], "nullable": true, "description": "Ha legalább egy címet megadsz, az eredmény nem a válaszban jön, hanem emailben megy ezekre a címekre (címenként külön levél). Üresen vagy elhagyva a válasz maga a ZIP-fájl." }, "order_column": { "type": "string", "nullable": true, "enum": [ "name", "sum_debt", "sum_municipality_debt", "sum_public_debt", "unclosed_messages_count", "relationship_week_hours" ], "default": "name", "description": "Rendezési oszlop: `name` név (alapérték), `sum_debt` NAV-egyenleg, `sum_municipality_debt` tárgyévi önkormányzati egyenleg, `sum_public_debt` végrehajtható köztartozás, `unclosed_messages_count` le nem zárt tárhely-üzenetek száma, `relationship_week_hours` heti munkaóra a saját foglalkoztatóknál." }, "order_direction": { "type": "string", "nullable": true, "enum": [ "asc", "desc" ], "default": "asc", "description": "Rendezési irány: `asc` növekvő (alapérték), `desc` csökkenő." }, "search": { "type": "string", "nullable": true, "example": "alfa kft", "description": "Szabad szavas keresés. A szöveget szavakra bontja (szóköz, kötőjel, pont, vessző stb. mentén), és minden szónak szerepelnie kell az alábbiak valamelyikében: név, adószám, adóazonosító jel, adózás módja, áfa-gyakoriság, ASP-képviselő adószáma, megjegyzés. Cégforma-rövidítésnél a teljes formára is keres („Kft” a „korlátolt felelősségű társaság” nevet is megtalálja)." }, "customer_portal_id": { "type": "integer", "nullable": true, "description": "Csak ennek az ügyfélkapunak (`CustomerPortal.id`) az adózói. A hívó irodájához kell tartoznia, különben 422." }, "active": { "type": "boolean", "nullable": true, "description": "`true`: csak aktív, `false`: csak inaktív adózók. Elhagyva mindkettő (az API alapból az inaktív adózókat is visszaadja, a felület listájával ellentétben)." }, "has_simplified_employee_from": { "type": "string", "format": "date", "nullable": true, "example": "2026-10-01", "description": "Csak azok az adózók, akiknek van olyan egyszerűsített foglalkoztatottja (EFO), akinek a foglalkoztatása ezen a napon vagy később kezdődött (ÉÉÉÉ-HH-NN). A `has_simplified_employee_to` mezővel együtt intervallum." }, "has_simplified_employee_to": { "type": "string", "format": "date", "nullable": true, "example": "2026-10-31", "description": "Csak azok az adózók, akiknek van olyan EFO-ja, akinek a foglalkoztatása ezen a napon vagy korábban kezdődött (ÉÉÉÉ-HH-NN)." }, "has_simplified_employee": { "type": "boolean", "nullable": true, "description": "`true`: csak akinek van egyszerűsített foglalkoztatottja (EFO), `false`: csak akinek nincs." }, "has_employee": { "type": "boolean", "nullable": true, "description": "`true`: csak akinek van biztosítottja (bejelentett foglalkoztatottja), `false`: csak akinek nincs." }, "taxation_type": { "type": "string", "nullable": true, "enum": [ "VSZJA", "Átalányadó", "Új KATA", "Társasági adó", "KIVA" ], "description": "Szűrés az adózás módjára. Az adózás módja a NAV-törzsadat alapján: `VSZJA` (vállalkozói személyi jövedelemadó; ez az alapérték, ha a törzsadatból más nem olvasható ki), `Átalányadó` (egyéni vállalkozói átalányadó), `Új KATA` (kisadózó vállalkozások tételes adója), `Társasági adó`, `KIVA` (kisvállalati adó)." }, "vat_period": { "type": "string", "nullable": true, "enum": [ "Havi", "Negyedéves", "Éves" ], "description": "Szűrés az áfabevallás gyakoriságára (`Havi`, `Negyedéves`, `Éves`)." }, "upo_available": { "type": "boolean", "nullable": true, "description": "`true`: csak akik szerepelnek az ügyfélkapu meghatalmazói között a NAV Online Ügyfélportálon (ÜPO), `false`: csak akik már nem (pl. megszűnt a megbízás)." }, "koma_status": { "type": "string", "nullable": true, "enum": [ "included_qualified", "included_not_qualified", "in_progress", "not_included_qualified", "not_included_not_qualified" ], "description": "Szűrés a törzsadatok KOMA-állapotára (legalább egy törzsadat-lapnak ilyen az állapota). A Köztartozásmentes Adózói Adatbázis (KOMA) szerinti állapot: `included_qualified` szerepel, minősített; `included_not_qualified` szerepel, nem minősített; `in_progress` a felvételi kérelem beküldése vagy feldolgozása folyamatban; `not_included_qualified` nem szerepel, minősített; `not_included_not_qualified` nem szerepel, nem minősített." } }, "required": [ "period_start", "period_end" ] } } } }, "responses": { "200": { "description": "`emails` nélkül: a ZIP-fájl (letöltésként). `emails` megadásával: üres válasz, az eredmény emailben megy.", "content": { "application/zip": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/trustees/bulk-roles-query": { "post": { "tags": [ "Adózók" ], "summary": "Kiválasztott törzsadat-mezők kigyűjtése több adózóra", "description": "Egyetlen XLSX-táblázat a keresésnek és a szűrőknek megfelelő adózókról (ugyanazok a mezők, mint a `POST /trustees/search` kérésében, lapozás nélkül): soronként egy adózó, oszlopok: adózó, adószám, adózás módja, áfa-gyakoriság, majd a kiválasztott törzsadat-címkénként egy oszlop az aktuális értékkel (ha a címke többször szerepel, az értékek soronként egymás alatt). Így például egy lépésben kigyűjthető, kinél mikor kezdődött a KIVA-alanyiság. Fájlnév: „{n} adózó törzsadat kigyűjtés ÉÉÉÉ-HH-NN.xlsx”. Csak letölthető, emailben nem küldhető. Jogosultság: bármely szerepkör, csak Prémium csomagban (csoportos műveletek; más csomagban 403).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "trustee_role_label_ids" ], "properties": { "trustee_role_label_ids": { "type": "array", "minItems": 1, "items": { "type": "integer" }, "example": [ 12, 40 ], "description": "A kigyűjtendő törzsadat-címkék azonosítói (`GET /trustees/trustee-role-labels`), legalább egy. A táblázat oszlopai ebben a sorrendben követik egymást." }, "order_column": { "type": "string", "nullable": true, "enum": [ "name", "sum_debt", "sum_municipality_debt", "sum_public_debt", "unclosed_messages_count", "relationship_week_hours" ], "default": "name", "description": "Rendezési oszlop: `name` név (alapérték), `sum_debt` NAV-egyenleg, `sum_municipality_debt` tárgyévi önkormányzati egyenleg, `sum_public_debt` végrehajtható köztartozás, `unclosed_messages_count` le nem zárt tárhely-üzenetek száma, `relationship_week_hours` heti munkaóra a saját foglalkoztatóknál." }, "order_direction": { "type": "string", "nullable": true, "enum": [ "asc", "desc" ], "default": "asc", "description": "Rendezési irány: `asc` növekvő (alapérték), `desc` csökkenő." }, "search": { "type": "string", "nullable": true, "example": "alfa kft", "description": "Szabad szavas keresés. A szöveget szavakra bontja (szóköz, kötőjel, pont, vessző stb. mentén), és minden szónak szerepelnie kell az alábbiak valamelyikében: név, adószám, adóazonosító jel, adózás módja, áfa-gyakoriság, ASP-képviselő adószáma, megjegyzés. Cégforma-rövidítésnél a teljes formára is keres („Kft” a „korlátolt felelősségű társaság” nevet is megtalálja)." }, "customer_portal_id": { "type": "integer", "nullable": true, "description": "Csak ennek az ügyfélkapunak (`CustomerPortal.id`) az adózói. A hívó irodájához kell tartoznia, különben 422." }, "active": { "type": "boolean", "nullable": true, "description": "`true`: csak aktív, `false`: csak inaktív adózók. Elhagyva mindkettő (az API alapból az inaktív adózókat is visszaadja, a felület listájával ellentétben)." }, "has_simplified_employee_from": { "type": "string", "format": "date", "nullable": true, "example": "2026-10-01", "description": "Csak azok az adózók, akiknek van olyan egyszerűsített foglalkoztatottja (EFO), akinek a foglalkoztatása ezen a napon vagy később kezdődött (ÉÉÉÉ-HH-NN). A `has_simplified_employee_to` mezővel együtt intervallum." }, "has_simplified_employee_to": { "type": "string", "format": "date", "nullable": true, "example": "2026-10-31", "description": "Csak azok az adózók, akiknek van olyan EFO-ja, akinek a foglalkoztatása ezen a napon vagy korábban kezdődött (ÉÉÉÉ-HH-NN)." }, "has_simplified_employee": { "type": "boolean", "nullable": true, "description": "`true`: csak akinek van egyszerűsített foglalkoztatottja (EFO), `false`: csak akinek nincs." }, "has_employee": { "type": "boolean", "nullable": true, "description": "`true`: csak akinek van biztosítottja (bejelentett foglalkoztatottja), `false`: csak akinek nincs." }, "taxation_type": { "type": "string", "nullable": true, "enum": [ "VSZJA", "Átalányadó", "Új KATA", "Társasági adó", "KIVA" ], "description": "Szűrés az adózás módjára. Az adózás módja a NAV-törzsadat alapján: `VSZJA` (vállalkozói személyi jövedelemadó; ez az alapérték, ha a törzsadatból más nem olvasható ki), `Átalányadó` (egyéni vállalkozói átalányadó), `Új KATA` (kisadózó vállalkozások tételes adója), `Társasági adó`, `KIVA` (kisvállalati adó)." }, "vat_period": { "type": "string", "nullable": true, "enum": [ "Havi", "Negyedéves", "Éves" ], "description": "Szűrés az áfabevallás gyakoriságára (`Havi`, `Negyedéves`, `Éves`)." }, "upo_available": { "type": "boolean", "nullable": true, "description": "`true`: csak akik szerepelnek az ügyfélkapu meghatalmazói között a NAV Online Ügyfélportálon (ÜPO), `false`: csak akik már nem (pl. megszűnt a megbízás)." }, "koma_status": { "type": "string", "nullable": true, "enum": [ "included_qualified", "included_not_qualified", "in_progress", "not_included_qualified", "not_included_not_qualified" ], "description": "Szűrés a törzsadatok KOMA-állapotára (legalább egy törzsadat-lapnak ilyen az állapota). A Köztartozásmentes Adózói Adatbázis (KOMA) szerinti állapot: `included_qualified` szerepel, minősített; `included_not_qualified` szerepel, nem minősített; `in_progress` a felvételi kérelem beküldése vagy feldolgozása folyamatban; `not_included_qualified` nem szerepel, minősített; `not_included_not_qualified` nem szerepel, nem minősített." } } } } } }, "responses": { "200": { "description": "Az XLSX-fájl (letöltésként). Találat nélkül csak a fejléc.", "content": { "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/trustees/export-asp-balance": { "post": { "tags": [ "Adózók" ], "summary": "Adózók önkormányzati (ASP) egyenlegeinek letöltése", "description": "Egyetlen XLSX-táblázat a keresésnek és a szűrőknek megfelelő, önkormányzati adószámlával rendelkező adózók tárgyévi önkormányzati egyenlegeiről: soronként egy önkormányzati adónem. Oszlopok: adózó, adószám, adóazonosító, önkormányzat, adónem, egyenleg (+ tartozás / − túlfizetés), befizetési számlaszám. Fájlnév: „{n} adózó ASP egyenlege ÉÉÉÉ-HH-NN.xlsx”. A kérés mezői a `POST /trustees/search` szűrői (lapozás nélkül), mind elhagyható. Jogosultság: bármely szerepkör, csak Prémium csomagban (önkormányzati adatok; más csomagban 403).", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "order_column": { "type": "string", "nullable": true, "enum": [ "name", "sum_debt", "sum_municipality_debt", "sum_public_debt", "unclosed_messages_count", "relationship_week_hours" ], "default": "name", "description": "Rendezési oszlop: `name` név (alapérték), `sum_debt` NAV-egyenleg, `sum_municipality_debt` tárgyévi önkormányzati egyenleg, `sum_public_debt` végrehajtható köztartozás, `unclosed_messages_count` le nem zárt tárhely-üzenetek száma, `relationship_week_hours` heti munkaóra a saját foglalkoztatóknál." }, "order_direction": { "type": "string", "nullable": true, "enum": [ "asc", "desc" ], "default": "asc", "description": "Rendezési irány: `asc` növekvő (alapérték), `desc` csökkenő." }, "search": { "type": "string", "nullable": true, "example": "alfa kft", "description": "Szabad szavas keresés. A szöveget szavakra bontja (szóköz, kötőjel, pont, vessző stb. mentén), és minden szónak szerepelnie kell az alábbiak valamelyikében: név, adószám, adóazonosító jel, adózás módja, áfa-gyakoriság, ASP-képviselő adószáma, megjegyzés. Cégforma-rövidítésnél a teljes formára is keres („Kft” a „korlátolt felelősségű társaság” nevet is megtalálja)." }, "customer_portal_id": { "type": "integer", "nullable": true, "description": "Csak ennek az ügyfélkapunak (`CustomerPortal.id`) az adózói. A hívó irodájához kell tartoznia, különben 422." }, "active": { "type": "boolean", "nullable": true, "description": "`true`: csak aktív, `false`: csak inaktív adózók. Elhagyva mindkettő (az API alapból az inaktív adózókat is visszaadja, a felület listájával ellentétben)." }, "has_simplified_employee_from": { "type": "string", "format": "date", "nullable": true, "example": "2026-10-01", "description": "Csak azok az adózók, akiknek van olyan egyszerűsített foglalkoztatottja (EFO), akinek a foglalkoztatása ezen a napon vagy később kezdődött (ÉÉÉÉ-HH-NN). A `has_simplified_employee_to` mezővel együtt intervallum." }, "has_simplified_employee_to": { "type": "string", "format": "date", "nullable": true, "example": "2026-10-31", "description": "Csak azok az adózók, akiknek van olyan EFO-ja, akinek a foglalkoztatása ezen a napon vagy korábban kezdődött (ÉÉÉÉ-HH-NN)." }, "has_simplified_employee": { "type": "boolean", "nullable": true, "description": "`true`: csak akinek van egyszerűsített foglalkoztatottja (EFO), `false`: csak akinek nincs." }, "has_employee": { "type": "boolean", "nullable": true, "description": "`true`: csak akinek van biztosítottja (bejelentett foglalkoztatottja), `false`: csak akinek nincs." }, "taxation_type": { "type": "string", "nullable": true, "enum": [ "VSZJA", "Átalányadó", "Új KATA", "Társasági adó", "KIVA" ], "description": "Szűrés az adózás módjára. Az adózás módja a NAV-törzsadat alapján: `VSZJA` (vállalkozói személyi jövedelemadó; ez az alapérték, ha a törzsadatból más nem olvasható ki), `Átalányadó` (egyéni vállalkozói átalányadó), `Új KATA` (kisadózó vállalkozások tételes adója), `Társasági adó`, `KIVA` (kisvállalati adó)." }, "vat_period": { "type": "string", "nullable": true, "enum": [ "Havi", "Negyedéves", "Éves" ], "description": "Szűrés az áfabevallás gyakoriságára (`Havi`, `Negyedéves`, `Éves`)." }, "upo_available": { "type": "boolean", "nullable": true, "description": "`true`: csak akik szerepelnek az ügyfélkapu meghatalmazói között a NAV Online Ügyfélportálon (ÜPO), `false`: csak akik már nem (pl. megszűnt a megbízás)." }, "koma_status": { "type": "string", "nullable": true, "enum": [ "included_qualified", "included_not_qualified", "in_progress", "not_included_qualified", "not_included_not_qualified" ], "description": "Szűrés a törzsadatok KOMA-állapotára (legalább egy törzsadat-lapnak ilyen az állapota). A Köztartozásmentes Adózói Adatbázis (KOMA) szerinti állapot: `included_qualified` szerepel, minősített; `included_not_qualified` szerepel, nem minősített; `in_progress` a felvételi kérelem beküldése vagy feldolgozása folyamatban; `not_included_qualified` nem szerepel, minősített; `not_included_not_qualified` nem szerepel, nem minősített." } } } } } }, "responses": { "200": { "description": "Az XLSX-fájl (letöltésként).", "content": { "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/trustees/export-asp-deposit": { "post": { "tags": [ "Adózók" ], "summary": "Adózók önkormányzati (ASP) előírásainak, előlegeinek letöltése", "description": "Egyetlen XLSX-táblázat a keresésnek és a szűrőknek megfelelő, önkormányzati adószámlával rendelkező adózók iparűzési adó és építményadó előírásairól (előlegeiről), az összes letöltött évre: soronként egy előírás. Oszlopok: adózó, adószám, adóazonosító, önkormányzat, adónem, év, előírás dátuma, kódja, neve és összege. Az ASP-egyenlegekkel (`POST /trustees/export-asp-balance`) együtt az iparűzési adó előleg esedékessége előtti ellenőrzésre való. Fájlnév: „{n} adózó ASP előlege ÉÉÉÉ-HH-NN.xlsx”. Jogosultság: bármely szerepkör, csak Prémium csomagban (más csomagban 403).", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "order_column": { "type": "string", "nullable": true, "enum": [ "name", "sum_debt", "sum_municipality_debt", "sum_public_debt", "unclosed_messages_count", "relationship_week_hours" ], "default": "name", "description": "Rendezési oszlop: `name` név (alapérték), `sum_debt` NAV-egyenleg, `sum_municipality_debt` tárgyévi önkormányzati egyenleg, `sum_public_debt` végrehajtható köztartozás, `unclosed_messages_count` le nem zárt tárhely-üzenetek száma, `relationship_week_hours` heti munkaóra a saját foglalkoztatóknál." }, "order_direction": { "type": "string", "nullable": true, "enum": [ "asc", "desc" ], "default": "asc", "description": "Rendezési irány: `asc` növekvő (alapérték), `desc` csökkenő." }, "search": { "type": "string", "nullable": true, "example": "alfa kft", "description": "Szabad szavas keresés. A szöveget szavakra bontja (szóköz, kötőjel, pont, vessző stb. mentén), és minden szónak szerepelnie kell az alábbiak valamelyikében: név, adószám, adóazonosító jel, adózás módja, áfa-gyakoriság, ASP-képviselő adószáma, megjegyzés. Cégforma-rövidítésnél a teljes formára is keres („Kft” a „korlátolt felelősségű társaság” nevet is megtalálja)." }, "customer_portal_id": { "type": "integer", "nullable": true, "description": "Csak ennek az ügyfélkapunak (`CustomerPortal.id`) az adózói. A hívó irodájához kell tartoznia, különben 422." }, "active": { "type": "boolean", "nullable": true, "description": "`true`: csak aktív, `false`: csak inaktív adózók. Elhagyva mindkettő (az API alapból az inaktív adózókat is visszaadja, a felület listájával ellentétben)." }, "has_simplified_employee_from": { "type": "string", "format": "date", "nullable": true, "example": "2026-10-01", "description": "Csak azok az adózók, akiknek van olyan egyszerűsített foglalkoztatottja (EFO), akinek a foglalkoztatása ezen a napon vagy később kezdődött (ÉÉÉÉ-HH-NN). A `has_simplified_employee_to` mezővel együtt intervallum." }, "has_simplified_employee_to": { "type": "string", "format": "date", "nullable": true, "example": "2026-10-31", "description": "Csak azok az adózók, akiknek van olyan EFO-ja, akinek a foglalkoztatása ezen a napon vagy korábban kezdődött (ÉÉÉÉ-HH-NN)." }, "has_simplified_employee": { "type": "boolean", "nullable": true, "description": "`true`: csak akinek van egyszerűsített foglalkoztatottja (EFO), `false`: csak akinek nincs." }, "has_employee": { "type": "boolean", "nullable": true, "description": "`true`: csak akinek van biztosítottja (bejelentett foglalkoztatottja), `false`: csak akinek nincs." }, "taxation_type": { "type": "string", "nullable": true, "enum": [ "VSZJA", "Átalányadó", "Új KATA", "Társasági adó", "KIVA" ], "description": "Szűrés az adózás módjára. Az adózás módja a NAV-törzsadat alapján: `VSZJA` (vállalkozói személyi jövedelemadó; ez az alapérték, ha a törzsadatból más nem olvasható ki), `Átalányadó` (egyéni vállalkozói átalányadó), `Új KATA` (kisadózó vállalkozások tételes adója), `Társasági adó`, `KIVA` (kisvállalati adó)." }, "vat_period": { "type": "string", "nullable": true, "enum": [ "Havi", "Negyedéves", "Éves" ], "description": "Szűrés az áfabevallás gyakoriságára (`Havi`, `Negyedéves`, `Éves`)." }, "upo_available": { "type": "boolean", "nullable": true, "description": "`true`: csak akik szerepelnek az ügyfélkapu meghatalmazói között a NAV Online Ügyfélportálon (ÜPO), `false`: csak akik már nem (pl. megszűnt a megbízás)." }, "koma_status": { "type": "string", "nullable": true, "enum": [ "included_qualified", "included_not_qualified", "in_progress", "not_included_qualified", "not_included_not_qualified" ], "description": "Szűrés a törzsadatok KOMA-állapotára (legalább egy törzsadat-lapnak ilyen az állapota). A Köztartozásmentes Adózói Adatbázis (KOMA) szerinti állapot: `included_qualified` szerepel, minősített; `included_not_qualified` szerepel, nem minősített; `in_progress` a felvételi kérelem beküldése vagy feldolgozása folyamatban; `not_included_qualified` nem szerepel, minősített; `not_included_not_qualified` nem szerepel, nem minősített." } } } } } }, "responses": { "200": { "description": "Az XLSX-fájl (letöltésként).", "content": { "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/missing-declarations": { "get": { "tags": [ "Hiányzó bevallások" ], "summary": "Hiányzó bevallások listázása", "description": "Azok a bevallások, amelyeket a NAV Online Ügyfélportál (ÜPO) hiányzónak tart az adózóknál, az adózó adataival. A listából kimaradnak azok a sorok, amelyekre a rendszer már talált beküldött (nem törölt) bevallást ugyanarra a nyomtatványra és időszakra. Lapozás és szűrés nincs, a teljes lista egyben jön, azonosító szerint rendezve. Jogosultság: minden szerepkör; az ingyenes csomagban nem érhető el (403). Csak a hívó irodájának aktív ügyfélkapuihoz tartozó, aktív adózók adatai látszanak; „megadott adózók” hozzáférésű felhasználónál csak a hozzá rendelt adózóké.", "responses": { "200": { "description": "A hiányzó bevallások.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/MissingDeclaration" } } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" } } } }, "/missing-declarations/{missingDeclarationId}": { "get": { "tags": [ "Hiányzó bevallások" ], "summary": "Hiányzó bevallás megtekintése", "description": "Egy hiányzó bevallás sora az adózóval. Ez a végpont a sort akkor is visszaadja, ha időközben érkezett rá beküldött bevallás (a listából az ilyen sor kimarad). Jogosultság: minden szerepkör; az ingyenes csomagban nem érhető el (403). Csak a hívó irodájának aktív ügyfélkapuihoz tartozó, aktív adózók adatai látszanak; „megadott adózók” hozzáférésű felhasználónál csak a hozzá rendelt adózóké. Nem hozzáférhető sorra 404 a válasz.", "parameters": [ { "name": "missingDeclarationId", "in": "path", "required": true, "description": "A hiányzó bevallás sorának azonosítója (`id`).", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "A hiányzó bevallás.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MissingDeclaration" } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/missing-declarations/export": { "post": { "tags": [ "Hiányzó bevallások" ], "summary": "Hiányzó bevallások exportálása", "description": "A hiányzó bevallások listája Excel-fájlban (.xlsx), a `GET /missing-declarations` szabályai szerint (a már beküldöttek nélkül). Elhagyható szűrők: adózó és szabadszöveges keresés; törzs nélkül az összes hiányzó bevallás jön. Oszlopok: adózó neve, adószáma, adóazonosítója, bevallás típusa, megnevezése, időszaka, esedékessége. Legfeljebb 20 000 sor exportálható; efölött 422 hiba jön a `search` mezőre. Jogosultság: minden szerepkör; az ingyenes csomagban nem érhető el (403).", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "trustee_id": { "type": "integer", "minimum": 1, "nullable": true, "description": "Csak ennek az adózónak a hiányzó bevallásai." }, "search": { "type": "string", "nullable": true, "description": "Szabadszöveges keresés szavanként (minden szónak illeszkednie kell): bevallás típusa, megnevezése, időszaka, az adózó neve (cégforma-rövidítéssel is) és adószáma." }, "order_direction": { "type": "string", "nullable": true, "enum": [ null, "asc", "desc" ], "default": "asc", "description": "A sorok iránya azonosító szerint (`asc` / `desc`). Ha üres: `asc`." } } } } } }, "responses": { "200": { "description": "Az Excel-fájl (.xlsx), letöltésként.", "content": { "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/simplified-employees/{simplifiedEmployeeId}": { "get": { "tags": [ "Alkalmi munkavállalók" ], "summary": "Egyszerűsített foglalkoztatott (EFO) megtekintése", "description": "Egy egyszerűsített foglalkoztatási (alkalmi munka, idénymunka, filmipari statiszta) bejelentés adatai, a foglalkoztató adózóval és — ha a rendszerben megvan — a bejelentés bevallásával (azonos adózó, a vonalkód az iktatószám). Jogosultság: minden szerepkör; az ingyenes csomagban nem érhető el (403). Csak a hívó irodájának aktív ügyfélkapuihoz tartozó, aktív adózók adatai látszanak; „megadott adózók” hozzáférésű felhasználónál csak a hozzá rendelt adózóké. Nem hozzáférhető rekordra 404 a válasz.", "parameters": [ { "name": "simplifiedEmployeeId", "in": "path", "required": true, "description": "Az EFO-bejelentés azonosítója (`id`).", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Az EFO-bejelentés.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SimplifiedEmployee" } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/simplified-employees/search": { "post": { "tags": [ "Alkalmi munkavállalók" ], "summary": "Egyszerűsített foglalkoztatottak (EFO) szűrése", "description": "Az adózók által bejelentett egyszerűsített foglalkoztatottak lapozott, szűrhető listája. Alapból a legfrissebb bejelentés van elöl. Minden rekordban benne van a foglalkoztató adózó és a kapcsolódó bevallás (ha van). Jogosultság: minden szerepkör; az ingyenes csomagban nem érhető el (403). Csak a hívó irodájának aktív ügyfélkapuihoz tartozó, aktív adózók adatai látszanak; „megadott adózók” hozzáférésű felhasználónál csak a hozzá rendelt adózóké.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 200, "nullable": true, "default": 200, "description": "Oldalméret: ennyi rekord jön egy oldalon. Alapértelmezés: 200." }, "page": { "type": "integer", "minimum": 1, "nullable": true, "default": 1, "description": "A kért oldal sorszáma (1-től). Alapértelmezés: 1." }, "order_column": { "type": "string", "nullable": true, "enum": [ null, "name", "employment_start", "employment_end", "data_sheet_arrived_at", "trustee.name" ], "default": "data_sheet_arrived_at", "description": "Rendezési oszlop: `name` a munkavállaló neve, `employment_start` / `employment_end` a foglalkoztatás kezdő / záró napja, `data_sheet_arrived_at` a bejelentés napja, `trustee.name` a foglalkoztató adózó neve. Ha üres, `data_sheet_arrived_at` szerint rendez." }, "order_direction": { "type": "string", "nullable": true, "enum": [ null, "asc", "desc" ], "default": "desc", "description": "Rendezési irány: `asc` növekvő, `desc` csökkenő. Ha üres: `desc`." }, "search": { "type": "string", "nullable": true, "description": "Szabadszöveges keresés. A szöveget szavakra bontja (szóköz, kötőjel, pont, zárójel stb. mentén); minden szónak illeszkednie kell valamelyik mezőre (részleges egyezés). Keresett mezők: név, adóazonosító jel, TAJ szám, bejelentés típusa, foglalkoztatás jellege, iktatószám, adatlap állapota és típusa, valamint a foglalkoztató adózó neve, adószáma, adóazonosítója. Cégforma-rövidítésre a teljes cégformát is megtalálja." }, "trustee_id": { "type": "integer", "minimum": 1, "nullable": true, "description": "Csak ennek a foglalkoztató adózónak a bejelentései." }, "employment_start_min": { "type": "string", "format": "date", "nullable": true, "example": "2026-01-01", "description": "A foglalkoztatás kezdő napja legalább ez (ÉÉÉÉ-HH-NN)." }, "employment_start_max": { "type": "string", "format": "date", "nullable": true, "example": "2026-01-31", "description": "A foglalkoztatás kezdő napja legfeljebb ez (ÉÉÉÉ-HH-NN)." }, "employment_end_min": { "type": "string", "format": "date", "nullable": true, "description": "A foglalkoztatás záró napja legalább ez (ÉÉÉÉ-HH-NN)." }, "employment_end_max": { "type": "string", "format": "date", "nullable": true, "description": "A foglalkoztatás záró napja legfeljebb ez (ÉÉÉÉ-HH-NN)." } } } } } }, "responses": { "200": { "description": "A szűrésnek megfelelő rekordok egy oldala.", "content": { "application/json": { "schema": { "type": "object", "required": [ "records", "count", "page", "max_page", "order_column", "order_direction" ], "properties": { "records": { "type": "array", "items": { "$ref": "#/components/schemas/SimplifiedEmployee" }, "description": "Az EFO-bejelentések (adózóval és bevallással)." }, "count": { "type": "integer", "description": "A szűrésnek megfelelő összes rekord száma." }, "page": { "type": "integer", "description": "Az aktuális oldal sorszáma." }, "max_page": { "type": "integer", "description": "Az utolsó oldal sorszáma (0, ha nincs találat)." }, "order_column": { "type": "string", "description": "A ténylegesen használt rendezési oszlop." }, "order_direction": { "type": "string", "enum": [ "asc", "desc" ], "description": "A ténylegesen használt rendezési irány." } } } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/simplified-employees/export": { "post": { "tags": [ "Alkalmi munkavállalók" ], "summary": "Egyszerűsített foglalkoztatottak (EFO) exportálása", "description": "Ugyanazokkal a szűrőkkel, mint a `POST /simplified-employees/search`, lapozás nélkül, Excel-fájlban (.xlsx). Oszlopok: foglalkoztató neve, adószáma, adóazonosítója, a munkavállaló neve, adóazonosítója, TAJ száma, bejelentés típusa, foglalkoztatás jellege, kezdő és záró nap, iktatószám, állapot, nyomtatvány, benyújtás, sorszám. Legfeljebb 50 000 rekord; efölött 422 hiba a `search` mezőre. Jogosultság: minden szerepkör; az ingyenes csomagban nem érhető el (403). ", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "order_column": { "type": "string", "nullable": true, "enum": [ null, "name", "employment_start", "employment_end", "data_sheet_arrived_at", "trustee.name" ], "default": "data_sheet_arrived_at", "description": "Rendezési oszlop: `name` a munkavállaló neve, `employment_start` / `employment_end` a foglalkoztatás kezdő / záró napja, `data_sheet_arrived_at` a bejelentés napja, `trustee.name` a foglalkoztató adózó neve. Ha üres, `data_sheet_arrived_at` szerint rendez." }, "order_direction": { "type": "string", "nullable": true, "enum": [ null, "asc", "desc" ], "default": "desc", "description": "Rendezési irány: `asc` növekvő, `desc` csökkenő. Ha üres: `desc`." }, "search": { "type": "string", "nullable": true, "description": "Szabadszöveges keresés. A szöveget szavakra bontja (szóköz, kötőjel, pont, zárójel stb. mentén); minden szónak illeszkednie kell valamelyik mezőre (részleges egyezés). Keresett mezők: név, adóazonosító jel, TAJ szám, bejelentés típusa, foglalkoztatás jellege, iktatószám, adatlap állapota és típusa, valamint a foglalkoztató adózó neve, adószáma, adóazonosítója. Cégforma-rövidítésre a teljes cégformát is megtalálja." }, "trustee_id": { "type": "integer", "minimum": 1, "nullable": true, "description": "Csak ennek a foglalkoztató adózónak a bejelentései." }, "employment_start_min": { "type": "string", "format": "date", "nullable": true, "example": "2026-01-01", "description": "A foglalkoztatás kezdő napja legalább ez (ÉÉÉÉ-HH-NN)." }, "employment_start_max": { "type": "string", "format": "date", "nullable": true, "example": "2026-01-31", "description": "A foglalkoztatás kezdő napja legfeljebb ez (ÉÉÉÉ-HH-NN)." }, "employment_end_min": { "type": "string", "format": "date", "nullable": true, "description": "A foglalkoztatás záró napja legalább ez (ÉÉÉÉ-HH-NN)." }, "employment_end_max": { "type": "string", "format": "date", "nullable": true, "description": "A foglalkoztatás záró napja legfeljebb ez (ÉÉÉÉ-HH-NN)." } } } } } }, "responses": { "200": { "description": "Az Excel-fájl (.xlsx), letöltésként.", "content": { "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/employees/{employeeId}": { "get": { "tags": [ "Biztosítottak" ], "summary": "Biztosított megtekintése", "description": "Egy biztosított jogviszony adatai: akit az adózó foglalkoztat (a NAV-nál nyilvántartott T1041-es bejelentés alapján), személyes adatokkal, a jogviszony és a bejelentés adataival, a foglalkoztató adózóval. Jogosultság: minden szerepkör; az ingyenes csomagban nem érhető el (403). Csak a hívó irodájának aktív ügyfélkapuihoz tartozó, aktív adózók adatai látszanak; „megadott adózók” hozzáférésű felhasználónál csak a hozzá rendelt adózóké. Nem hozzáférhető rekordra 404 a válasz.", "parameters": [ { "name": "employeeId", "in": "path", "required": true, "description": "A biztosított jogviszony azonosítója (`id`).", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "A biztosított jogviszony.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Employee" } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/employees/search": { "post": { "tags": [ "Biztosítottak" ], "summary": "Biztosítottak szűrése", "description": "Az adózók által foglalkoztatott biztosítottak (jogviszonyok) lapozott, szűrhető listája, a foglalkoztató adózóval. Jogosultság: minden szerepkör; az ingyenes csomagban nem érhető el (403). Csak a hívó irodájának aktív ügyfélkapuihoz tartozó, aktív adózók adatai látszanak; „megadott adózók” hozzáférésű felhasználónál csak a hozzá rendelt adózóké.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 200, "nullable": true, "default": 200, "description": "Oldalméret: ennyi rekord jön egy oldalon. Alapértelmezés: 200." }, "page": { "type": "integer", "minimum": 1, "nullable": true, "default": 1, "description": "A kért oldal sorszáma (1-től). Alapértelmezés: 1." }, "order_column": { "type": "string", "nullable": true, "enum": [ null, "name", "relationship_start", "trustee.name" ], "default": "relationship_start", "description": "Rendezési oszlop: `name` a biztosított neve, `relationship_start` a jogviszony kezdete, `trustee.name` az adózó neve. Ha üres, `relationship_start` szerint rendez." }, "order_direction": { "type": "string", "nullable": true, "enum": [ null, "asc", "desc" ], "default": "asc", "description": "Rendezési irány: `asc` növekvő, `desc` csökkenő. Ha üres: `asc`." }, "search": { "type": "string", "nullable": true, "description": "Szabadszöveges keresés. A szöveget szavakra bontja (szóköz, kötőjel, pont, zárójel stb. mentén); minden szónak illeszkednie kell valamelyik mezőre (részleges egyezés). Keresett mezők: név, adóazonosító jel, TAJ szám, jogviszony-kód, FEOR-kód, adatlap iktatószáma, állapota és típusa, állampolgárság, anyja neve, születési hely, ország és név, valamint a foglalkoztató adózó neve, adószáma, adóazonosítója. Cégforma-rövidítésre a teljes cégformát is megtalálja." }, "trustee_id": { "type": "integer", "minimum": 1, "nullable": true, "description": "Csak ennek az adózónak a biztosítottjai." }, "relationship_start_min": { "type": "string", "format": "date", "nullable": true, "example": "2026-01-01", "description": "A jogviszony kezdete legalább ez a nap (ÉÉÉÉ-HH-NN)." }, "relationship_start_max": { "type": "string", "format": "date", "nullable": true, "example": "2026-01-31", "description": "A jogviszony kezdete legfeljebb ez a nap (ÉÉÉÉ-HH-NN)." } } } } } }, "responses": { "200": { "description": "A szűrésnek megfelelő rekordok egy oldala.", "content": { "application/json": { "schema": { "type": "object", "required": [ "records", "count", "page", "max_page", "order_column", "order_direction" ], "properties": { "records": { "type": "array", "items": { "$ref": "#/components/schemas/Employee" }, "description": "A biztosított jogviszonyok (adózóval)." }, "count": { "type": "integer", "description": "A szűrésnek megfelelő összes rekord száma." }, "page": { "type": "integer", "description": "Az aktuális oldal sorszáma." }, "max_page": { "type": "integer", "description": "Az utolsó oldal sorszáma (0, ha nincs találat)." }, "order_column": { "type": "string", "description": "A ténylegesen használt rendezési oszlop." }, "order_direction": { "type": "string", "enum": [ "asc", "desc" ], "description": "A ténylegesen használt rendezési irány." } } } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/employees/export": { "post": { "tags": [ "Biztosítottak" ], "summary": "Biztosítottak exportálása", "description": "Ugyanazokkal a szűrőkkel, mint a `POST /employees/search`, lapozás nélkül, Excel-fájlban (.xlsx): foglalkoztató, személyes adatok, jogviszony, FEOR, bejelentés adatai. Legfeljebb 50 000 rekord; efölött 422 hiba a `search` mezőre. Jogosultság: minden szerepkör; az ingyenes csomagban nem érhető el (403). ", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "order_column": { "type": "string", "nullable": true, "enum": [ null, "name", "relationship_start", "trustee.name" ], "default": "relationship_start", "description": "Rendezési oszlop: `name` a biztosított neve, `relationship_start` a jogviszony kezdete, `trustee.name` az adózó neve. Ha üres, `relationship_start` szerint rendez." }, "order_direction": { "type": "string", "nullable": true, "enum": [ null, "asc", "desc" ], "default": "asc", "description": "Rendezési irány: `asc` növekvő, `desc` csökkenő. Ha üres: `asc`." }, "search": { "type": "string", "nullable": true, "description": "Szabadszöveges keresés. A szöveget szavakra bontja (szóköz, kötőjel, pont, zárójel stb. mentén); minden szónak illeszkednie kell valamelyik mezőre (részleges egyezés). Keresett mezők: név, adóazonosító jel, TAJ szám, jogviszony-kód, FEOR-kód, adatlap iktatószáma, állapota és típusa, állampolgárság, anyja neve, születési hely, ország és név, valamint a foglalkoztató adózó neve, adószáma, adóazonosítója. Cégforma-rövidítésre a teljes cégformát is megtalálja." }, "trustee_id": { "type": "integer", "minimum": 1, "nullable": true, "description": "Csak ennek az adózónak a biztosítottjai." }, "relationship_start_min": { "type": "string", "format": "date", "nullable": true, "example": "2026-01-01", "description": "A jogviszony kezdete legalább ez a nap (ÉÉÉÉ-HH-NN)." }, "relationship_start_max": { "type": "string", "format": "date", "nullable": true, "example": "2026-01-31", "description": "A jogviszony kezdete legfeljebb ez a nap (ÉÉÉÉ-HH-NN)." } } } } } }, "responses": { "200": { "description": "Az Excel-fájl (.xlsx), letöltésként.", "content": { "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/employers/{employerId}": { "get": { "tags": [ "Saját foglalkoztatók" ], "summary": "Saját foglalkoztató megtekintése", "description": "Egy saját foglalkoztató: olyan munkáltató, amelynél maga az adózó biztosított (pl. egyéni vállalkozó adózó mellett fennálló munkaviszonya), a jogviszony adataival és az adózóval. A foglalkoztató neve rövidített cégformával jön. Jogosultság: minden szerepkör; az ingyenes csomagban nem érhető el (403). Csak a hívó irodájának aktív ügyfélkapuihoz tartozó, aktív adózók adatai látszanak; „megadott adózók” hozzáférésű felhasználónál csak a hozzá rendelt adózóké. Nem hozzáférhető rekordra 404 a válasz.", "parameters": [ { "name": "employerId", "in": "path", "required": true, "description": "A saját foglalkoztató azonosítója (`id`).", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "A saját foglalkoztató.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Employer" } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/employers/search": { "post": { "tags": [ "Saját foglalkoztatók" ], "summary": "Saját foglalkoztatók szűrése", "description": "Azoknak a munkáltatóknak a lapozott, szűrhető listája, amelyeknél az adózók biztosítottak, az adózóval. A `relationship_only` szűrővel a heti munkaórába beszámító jogviszonyokra szűkíthető. Jogosultság: minden szerepkör; az ingyenes csomagban nem érhető el (403). Csak a hívó irodájának aktív ügyfélkapuihoz tartozó, aktív adózók adatai látszanak; „megadott adózók” hozzáférésű felhasználónál csak a hozzá rendelt adózóké.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 200, "nullable": true, "default": 200, "description": "Oldalméret: ennyi rekord jön egy oldalon. Alapértelmezés: 200." }, "page": { "type": "integer", "minimum": 1, "nullable": true, "default": 1, "description": "A kért oldal sorszáma (1-től). Alapértelmezés: 1." }, "order_column": { "type": "string", "nullable": true, "enum": [ null, "name", "relationship_start", "trustee.name" ], "default": "relationship_start", "description": "Rendezési oszlop: `name` a foglalkoztató neve, `relationship_start` a jogviszony kezdete, `trustee.name` az adózó neve. Ha üres, `relationship_start` szerint rendez." }, "order_direction": { "type": "string", "nullable": true, "enum": [ null, "asc", "desc" ], "default": "asc", "description": "Rendezési irány: `asc` növekvő, `desc` csökkenő. Ha üres: `asc`." }, "search": { "type": "string", "nullable": true, "description": "Szabadszöveges keresés. A szöveget szavakra bontja (szóköz, kötőjel, pont, zárójel stb. mentén); minden szónak illeszkednie kell valamelyik mezőre (részleges egyezés). Keresett mezők: a foglalkoztató neve és adószáma, jogviszony-kód, FEOR-kód, valamint az adózó neve, adószáma, adóazonosítója. Cégforma-rövidítésre a teljes cégformát is megtalálja." }, "trustee_id": { "type": "integer", "minimum": 1, "nullable": true, "description": "Csak ennek az adózónak a foglalkoztatói." }, "relationship_only": { "type": "boolean", "nullable": true, "description": "`true`: csak a heti munkaórába beszámító jogviszonyok (jogviszony-kód 1101, 1102, 1103, 1105 vagy 1112, pl. munkaviszony). `false` vagy üres: minden jogviszony." }, "relationship_start_min": { "type": "string", "format": "date", "nullable": true, "example": "2026-01-01", "description": "A jogviszony kezdete legalább ez a nap (ÉÉÉÉ-HH-NN)." }, "relationship_start_max": { "type": "string", "format": "date", "nullable": true, "example": "2026-01-31", "description": "A jogviszony kezdete legfeljebb ez a nap (ÉÉÉÉ-HH-NN)." } } } } } }, "responses": { "200": { "description": "A szűrésnek megfelelő rekordok egy oldala.", "content": { "application/json": { "schema": { "type": "object", "required": [ "records", "count", "page", "max_page", "order_column", "order_direction" ], "properties": { "records": { "type": "array", "items": { "$ref": "#/components/schemas/Employer" }, "description": "A saját foglalkoztatók (adózóval)." }, "count": { "type": "integer", "description": "A szűrésnek megfelelő összes rekord száma." }, "page": { "type": "integer", "description": "Az aktuális oldal sorszáma." }, "max_page": { "type": "integer", "description": "Az utolsó oldal sorszáma (0, ha nincs találat)." }, "order_column": { "type": "string", "description": "A ténylegesen használt rendezési oszlop." }, "order_direction": { "type": "string", "enum": [ "asc", "desc" ], "description": "A ténylegesen használt rendezési irány." } } } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/employers/export": { "post": { "tags": [ "Saját foglalkoztatók" ], "summary": "Saját foglalkoztatók exportálása", "description": "Ugyanazokkal a szűrőkkel, mint a `POST /employers/search`, lapozás nélkül, Excel-fájlban (.xlsx): az adózó (munkavállaló) és a foglalkoztató neve, adószáma, adóazonosítója, a jogviszony, heti óra, FEOR. Legfeljebb 50 000 rekord; efölött 422 hiba a `search` mezőre. Jogosultság: minden szerepkör; az ingyenes csomagban nem érhető el (403). ", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "order_column": { "type": "string", "nullable": true, "enum": [ null, "name", "relationship_start", "trustee.name" ], "default": "relationship_start", "description": "Rendezési oszlop: `name` a foglalkoztató neve, `relationship_start` a jogviszony kezdete, `trustee.name` az adózó neve. Ha üres, `relationship_start` szerint rendez." }, "order_direction": { "type": "string", "nullable": true, "enum": [ null, "asc", "desc" ], "default": "asc", "description": "Rendezési irány: `asc` növekvő, `desc` csökkenő. Ha üres: `asc`." }, "search": { "type": "string", "nullable": true, "description": "Szabadszöveges keresés. A szöveget szavakra bontja (szóköz, kötőjel, pont, zárójel stb. mentén); minden szónak illeszkednie kell valamelyik mezőre (részleges egyezés). Keresett mezők: a foglalkoztató neve és adószáma, jogviszony-kód, FEOR-kód, valamint az adózó neve, adószáma, adóazonosítója. Cégforma-rövidítésre a teljes cégformát is megtalálja." }, "trustee_id": { "type": "integer", "minimum": 1, "nullable": true, "description": "Csak ennek az adózónak a foglalkoztatói." }, "relationship_only": { "type": "boolean", "nullable": true, "description": "`true`: csak a heti munkaórába beszámító jogviszonyok (jogviszony-kód 1101, 1102, 1103, 1105 vagy 1112, pl. munkaviszony). `false` vagy üres: minden jogviszony." }, "relationship_start_min": { "type": "string", "format": "date", "nullable": true, "example": "2026-01-01", "description": "A jogviszony kezdete legalább ez a nap (ÉÉÉÉ-HH-NN)." }, "relationship_start_max": { "type": "string", "format": "date", "nullable": true, "example": "2026-01-31", "description": "A jogviszony kezdete legfeljebb ez a nap (ÉÉÉÉ-HH-NN)." } } } } } }, "responses": { "200": { "description": "Az Excel-fájl (.xlsx), letöltésként.", "content": { "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/tax-account-queries": { "get": { "tags": [ "Adófolyószámla-lekérdezések" ], "summary": "Adófolyószámla-lekérdezések listázása", "description": "Az iroda összes olyan adófolyószámla-lekérdezése, amelyben a felhasználó lát legalább egy adózót, azonosító szerint növekvő sorrendben, lapozás nélkül. Minden lekérdezéshez a `tax_account_query_trustees` tömb tartalmazza a felhasználó által látható adózók eredményét (az adózó adataival). Jogosultság: bármely szerepkör (menedzser, könyvelő, adózó) és bármely csomag; adózó szerepkörű vagy „kijelölt adózók” jogkörű felhasználó csak a hozzá rendelt adózókat látja. Nagy irodánál a válasz nagy lehet: listázáshoz a `POST /tax-account-queries/search` lapozott változat ajánlott.", "responses": { "200": { "description": "A lekérdezések tömbje.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TaxAccountQuery" } } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" } } }, "post": { "tags": [ "Adófolyószámla-lekérdezések" ], "summary": "Adófolyószámla-lekérdezés indítása", "description": "Új adófolyószámla-kivonat lekérdezést indít a NAV-tól egy választott fordulónapra (`query_date`), egyszerre több adózóra. Meg kell adni a fordulónapot, a kivonat típusát (`type`), azt, hogy a kész eredmény menjen-e emailben (`send_mail`), és legalább egy adózó azonosítóját (`trustee_ids`); a megjegyzés nem kötelező. Az eredmény NEM azonnal érkezik: a válaszban a lekérdezés `completed_at` mezője `null`, az adózónkénti eredmények `status` mezője `pending`. Az állapotot a `GET /tax-account-queries/{taxAccountQueryId}` vagy a `/tax-account-query-trustees` végpontok mutatják: adózónként `completed` (a fájlok letölthetők) vagy `failed` lesz, és ha minden adózó elkészült, a lekérdezés `completed_at` mezője kitöltődik. Ha `send_mail` igaz, a befejezéskor a lekérdezést indító felhasználó email címére levél megy az eredményekkel (a PDF kivonatok mellékletként, amennyi belefér). Jogosultság: menedzser, könyvelő és adózó szerepkör, Alap vagy Prémium csomag (Ingyenes csomagban 403). Ha a funkció átmenetileg szünetel, a kérés 403-mal és magyarázó üzenettel elutasul.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "query_date", "type", "send_mail", "trustee_ids" ], "properties": { "query_date": { "type": "string", "format": "date", "example": "2026-09-30", "description": "A fordulónap (a felületen „Időszak vége”), amelyre a kivonat szól, ÉÉÉÉ-HH-NN formában. Jövőbeli dátum is lehet (pl. egy közelgő előleg-határidő egyenlegéhez)." }, "type": { "type": "string", "enum": [ "ADONEM_EGYENLEGES", "TETELES", "LISTA" ], "description": "A NAV-os kivonat típusa (a NAV Ügyfélportál lekérdezési típusai): `ADONEM_EGYENLEGES` adónemenkénti egyenleges kivonat, `TETELES` tételes kivonat (a `POST /tax-account-query-trustees/bulk-tax-type-query` adónem szerinti kigyűjtés csak ebből készül), `LISTA` lista típusú kivonat." }, "send_mail": { "type": "boolean", "description": "Igaz esetén a lekérdezés befejezésekor a lekérdezést indító felhasználó emailt kap az eredményekkel." }, "note": { "type": "string", "nullable": true, "maxLength": 255, "description": "Szabad szöveges megjegyzés, hogy később azonosítható legyen, mire készült a lekérdezés." }, "trustee_ids": { "type": "array", "minItems": 1, "items": { "type": "integer" }, "example": [ 123, 456 ], "description": "A lekérdezendő adózók azonosítói. Csak a felhasználó által elérhető AKTÍV adózók kerülnek a lekérdezésbe; a többi azonosítót a rendszer hibaüzenet nélkül kihagyja. Ha egyik sem érvényes, a válasz 404." } } } } } }, "responses": { "200": { "description": "Az elindított lekérdezés a még várakozó adózónkénti eredményekkel.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxAccountQuery" } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/tax-account-queries/{taxAccountQueryId}": { "get": { "tags": [ "Adófolyószámla-lekérdezések" ], "summary": "Adófolyószámla-lekérdezés megtekintése", "description": "Egy lekérdezés adatai az adózónkénti eredményekkel (`tax_account_query_trustees`, benne az adózó adataival, az állapottal és a letölthető fájlokkal). Egy elindított lekérdezés állapotának követésére ez a végpont való: amíg `completed_at` `null`, a lekérdezés még fut. Jogosultság: bármely szerepkör (menedzser, könyvelő, adózó) és bármely csomag; adózó szerepkörű vagy „kijelölt adózók” jogkörű felhasználó csak a hozzá rendelt adózókat látja. Ha a lekérdezés nem az irodáé, vagy a felhasználó egyetlen adózóját sem látja, 404.", "parameters": [ { "name": "taxAccountQueryId", "in": "path", "required": true, "description": "Az adófolyószámla-lekérdezés azonosítója.", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "A lekérdezés.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxAccountQuery" } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "tags": [ "Adófolyószámla-lekérdezések" ], "summary": "Adófolyószámla-lekérdezés törlése", "description": "Törli a lekérdezést az összes adózónkénti eredményével és a letöltött kivonatfájlokkal együtt (a felhasználó által nem látható adózók eredményeivel együtt is). A művelet nem vonható vissza. Jogosultság: bármely szerepkör, bármely csomag; a lekérdezésnek láthatónak kell lennie a felhasználó számára.", "parameters": [ { "name": "taxAccountQueryId", "in": "path", "required": true, "description": "Az adófolyószámla-lekérdezés azonosítója.", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Sikeres törlés (üres választörzs)." }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/tax-account-queries/search": { "post": { "tags": [ "Adófolyószámla-lekérdezések" ], "summary": "Adófolyószámla-lekérdezések keresése, lapozva", "description": "A lekérdezések szűrt, rendezett, lapozott listája. Minden szűrő elhagyható; alapértelmezés szerint azonosító szerint növekvő sorrend, oldalanként 200 rekord. A `search` a lekérdezés típusában és megjegyzésében keres. Jogosultság: bármely szerepkör (menedzser, könyvelő, adózó) és bármely csomag; adózó szerepkörű vagy „kijelölt adózók” jogkörű felhasználó csak a hozzá rendelt adózókat látja.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 200, "nullable": true, "default": 200, "description": "Egy oldalon visszaadott rekordok száma (alapértelmezés: 200)." }, "page": { "type": "integer", "minimum": 1, "nullable": true, "default": 1, "description": "A lekért oldal sorszáma (alapértelmezés: 1)." }, "order_column": { "type": "string", "nullable": true, "enum": [ "query_date", "created_at", "completed_at", null ], "description": "Rendezési oszlop: `query_date` fordulónap, `created_at` indítás ideje, `completed_at` befejezés ideje. Elhagyva azonosító szerint rendez." }, "order_direction": { "type": "string", "nullable": true, "enum": [ "asc", "desc", null ], "default": "asc", "description": "Rendezési irány: `asc` növekvő (alapértelmezés), `desc` csökkenő." }, "search": { "type": "string", "nullable": true, "description": "Szabad szöveges keresés szavanként a lekérdezés típusában és megjegyzésében." }, "trustee_id": { "type": "integer", "minimum": 1, "nullable": true, "description": "Csak azok a lekérdezések, amelyekben ez az adózó szerepel." }, "trustees_count_type": { "type": "string", "nullable": true, "enum": [ "one", "multiple", null ], "description": "Az adózók száma a lekérdezésben: `one` pontosan egy adózós, `multiple` több adózós lekérdezések." }, "query_date": { "type": "string", "format": "date", "nullable": true, "example": "2026-09-30", "description": "Csak az erre a fordulónapra szóló lekérdezések (ÉÉÉÉ-HH-NN)." }, "created_at_min": { "type": "integer", "minimum": 0, "maximum": 1893456000, "nullable": true, "example": 1761523200, "description": "A lekérdezés indításának legkorábbi időpontja (unix időbélyeg, másodperc), a határt is beleértve." }, "created_at_max": { "type": "integer", "minimum": 0, "maximum": 1893456000, "nullable": true, "example": 1764115199, "description": "A lekérdezés indításának legkésőbbi időpontja (unix időbélyeg, másodperc), a határt is beleértve." } } } } } }, "responses": { "200": { "description": "A szűrt, lapozott találati lista.", "content": { "application/json": { "schema": { "type": "object", "required": [ "records", "count", "page", "max_page", "order_column", "order_direction" ], "properties": { "records": { "type": "array", "items": { "$ref": "#/components/schemas/TaxAccountQuery" }, "description": "Az aktuális oldal rekordjai." }, "count": { "type": "integer", "description": "A szűrésnek megfelelő rekordok teljes száma." }, "page": { "type": "integer", "description": "Az aktuális oldal sorszáma (1-től)." }, "max_page": { "type": "integer", "description": "Az utolsó oldal sorszáma (0, ha nincs találat)." }, "order_column": { "type": "string", "description": "A ténylegesen alkalmazott rendezési oszlop (alapértelmezés: `id`)." }, "order_direction": { "type": "string", "enum": [ "asc", "desc" ], "description": "A rendezés iránya: `asc` növekvő, `desc` csökkenő." } } } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/tax-account-query-trustees": { "get": { "tags": [ "Adófolyószámla-lekérdezés adózónként" ], "summary": "Adózónkénti lekérdezés-eredmények listázása", "description": "Az iroda adófolyószámla-lekérdezéseinek adózónkénti eredményei (egy sor = egy adózó egy lekérdezésben), a felhasználó által látható adózókra szűkítve, azonosító szerint növekvő sorrendben, lapozás nélkül. Minden sorban benne van az adózó (`trustee`) és a lekérdezés (`tax_account_query`) adata. Jogosultság: bármely szerepkör (menedzser, könyvelő, adózó) és bármely csomag; adózó szerepkörű vagy „kijelölt adózók” jogkörű felhasználó csak a hozzá rendelt adózókat látja. Nagy irodánál a `POST /tax-account-query-trustees/search` lapozott változat ajánlott.", "responses": { "200": { "description": "Az eredmények tömbje.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TaxAccountQueryTrustee" } } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" } } } }, "/tax-account-query-trustees/{taxAccountQueryTrusteeId}": { "get": { "tags": [ "Adófolyószámla-lekérdezés adózónként" ], "summary": "Adózónkénti lekérdezés-eredmény megtekintése", "description": "Egy adózó egy lekérdezésbeli eredménye: állapot, letölthető kivonatfájlok, az adózó és a lekérdezés adatai. Jogosultság: bármely szerepkör (menedzser, könyvelő, adózó) és bármely csomag; adózó szerepkörű vagy „kijelölt adózók” jogkörű felhasználó csak a hozzá rendelt adózókat látja.", "parameters": [ { "name": "taxAccountQueryTrusteeId", "in": "path", "required": true, "description": "Az adózónkénti lekérdezés-eredmény azonosítója.", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Az eredmény.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxAccountQueryTrustee" } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "tags": [ "Adófolyószámla-lekérdezés adózónként" ], "summary": "Adózónkénti lekérdezés-eredmény törlése", "description": "Törli egy adózó eredményét a lekérdezésből, a hozzá tartozó kivonatfájlokkal (PDF, XLSX, XML) együtt. Ha a lekérdezésnek ezután nem marad eredménye, maga a lekérdezés is törlődik. A művelet nem vonható vissza. Jogosultság: bármely szerepkör, bármely csomag; csak a felhasználó által látható adózó eredménye törölhető.", "parameters": [ { "name": "taxAccountQueryTrusteeId", "in": "path", "required": true, "description": "Az adózónkénti lekérdezés-eredmény azonosítója.", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Sikeres törlés (üres választörzs)." }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/tax-account-query-trustees/search": { "post": { "tags": [ "Adófolyószámla-lekérdezés adózónként" ], "summary": "Adózónkénti lekérdezés-eredmények keresése, lapozva", "description": "Az adózónkénti eredmények szűrt, rendezett, lapozott listája (a felület „Adófolyószámla lekérdezés” listája). Minden szűrő elhagyható; alapértelmezés: azonosító szerint növekvő, oldalanként 200 rekord. A `search` az adózó nevében, adószámában, adóazonosító jelében, adózási formájában, áfagyakoriságában, megjegyzésében, valamint a lekérdezés típusában és megjegyzésében keres. Jogosultság: bármely szerepkör (menedzser, könyvelő, adózó) és bármely csomag; adózó szerepkörű vagy „kijelölt adózók” jogkörű felhasználó csak a hozzá rendelt adózókat látja.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 200, "nullable": true, "default": 200, "description": "Egy oldalon visszaadott rekordok száma (alapértelmezés: 200)." }, "page": { "type": "integer", "minimum": 1, "nullable": true, "default": 1, "description": "A lekért oldal sorszáma (alapértelmezés: 1)." }, "order_column": { "type": "string", "nullable": true, "enum": [ "trustee.name", "tax_account_query.query_date", "tax_account_query.created_at", null ], "description": "Rendezési oszlop: `trustee.name` az adózó neve, `tax_account_query.query_date` a lekérdezés fordulónapja, `tax_account_query.created_at` a lekérdezés indításának ideje. Elhagyva azonosító szerint rendez." }, "order_direction": { "type": "string", "nullable": true, "enum": [ "asc", "desc", null ], "default": "asc", "description": "Rendezési irány: `asc` növekvő (alapértelmezés), `desc` csökkenő." }, "search": { "type": "string", "nullable": true, "description": "Szabad szöveges keresés szavanként (lásd a művelet leírását)." }, "trustee_id": { "type": "integer", "minimum": 1, "nullable": true, "description": "Csak ennek az adózónak az eredményei." }, "query_date": { "type": "string", "format": "date", "nullable": true, "example": "2026-09-30", "description": "Csak az erre a fordulónapra szóló lekérdezések eredményei (ÉÉÉÉ-HH-NN)." }, "created_at_min": { "type": "integer", "minimum": 0, "maximum": 1893456000, "nullable": true, "example": 1761523200, "description": "A lekérdezés indításának legkorábbi időpontja (unix időbélyeg, másodperc), a határt is beleértve." }, "created_at_max": { "type": "integer", "minimum": 0, "maximum": 1893456000, "nullable": true, "example": 1764115199, "description": "A lekérdezés indításának legkésőbbi időpontja (unix időbélyeg, másodperc), a határt is beleértve." } } } } } }, "responses": { "200": { "description": "A szűrt, lapozott találati lista.", "content": { "application/json": { "schema": { "type": "object", "required": [ "records", "count", "page", "max_page", "order_column", "order_direction" ], "properties": { "records": { "type": "array", "items": { "$ref": "#/components/schemas/TaxAccountQueryTrustee" }, "description": "Az aktuális oldal rekordjai." }, "count": { "type": "integer", "description": "A szűrésnek megfelelő rekordok teljes száma." }, "page": { "type": "integer", "description": "Az aktuális oldal sorszáma (1-től)." }, "max_page": { "type": "integer", "description": "Az utolsó oldal sorszáma (0, ha nincs találat)." }, "order_column": { "type": "string", "description": "A ténylegesen alkalmazott rendezési oszlop (alapértelmezés: `id`)." }, "order_direction": { "type": "string", "enum": [ "asc", "desc" ], "description": "A rendezés iránya: `asc` növekvő, `desc` csökkenő." } } } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/tax-account-query-trustees/delete-all-failed": { "delete": { "tags": [ "Adófolyószámla-lekérdezés adózónként" ], "summary": "Az összes sikertelen eredmény törlése", "description": "Egyszerre törli az iroda összes `failed` (sikertelen) állapotú adózónkénti eredményét, a felhasználó által látható adózókra szűkítve. Sikertelen adózóra új lekérdezést kell indítani. A művelet nem vonható vissza. Jogosultság: bármely szerepkör, bármely csomag.", "responses": { "200": { "description": "Sikeres törlés (üres választörzs), akkor is, ha nem volt mit törölni." }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" } } } }, "/tax-account-query-trustees/bulk-tax-type-query": { "post": { "tags": [ "Adófolyószámla-lekérdezés adózónként" ], "summary": "Adónem szerinti kigyűjtés Excelbe", "description": "Egy adónem adatait gyűjti ki egy Excel fájlba az összes olyan adózónál, akinek van az adott fordulónapra szóló, KÉSZ, `TETELES` típusú lekérdezés-eredménye. Adózónként egy sor, név szerint rendezve: adózó, adószám, időszakig (fordulónap), adónem, megnevezés, előleg (az adónem utolsó előírt összege), egyenleg és a kivonat PDF-jének linkje. Ha nincs ilyen eredmény, csak a fejlécet tartalmazó fájl jön vissza. Jogosultság: bármely szerepkör, csak Prémium csomagban.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "tax_type_code", "query_date" ], "properties": { "tax_type_code": { "type": "integer", "example": 101, "description": "A NAV adónemkódja (pl. 101 társasági adó, 103 SZJA, 104 ÁFA, 138 késedelmi pótlék). Csak a rendszer által ismert adónemkód fogadható el." }, "query_date": { "type": "string", "format": "date", "example": "2026-12-31", "description": "A lekérdezések fordulónapja (ÉÉÉÉ-HH-NN); csak az erre a napra szóló lekérdezések eredményei kerülnek a fájlba." } } } } } }, "responses": { "200": { "description": "Az Excel fájl (`{adónemkód} adónem kigyűjtés.xlsx`).", "content": { "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/packages/change-package": { "post": { "tags": [ "Előfizetési csomag" ], "summary": "Előfizetési csomag váltása", "description": "Az iroda előfizetési csomagját váltja. Csak menedzser szerepkörrel hívható. Elutasítja (422, a `package` mezőnél az okok listájával), ha az iroda már ezt a csomagot használja; ha fizetős csomaghoz (próbaidőszakon kívül) nincsenek megadva a számlázási adatok; vagy ha az iroda jelenlegi használata túllépi az új csomag korlátait (felhasználók száma, ügyfélkapuk száma, aktív adózók száma, azonnali levélküldésre állított szabály). Fizetős csomagról (próbaidőszakon kívül) váltáskor a rendszer az addig eltelt időszakról elszámoló számlát állít ki és küld el emailben.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "package": { "type": "string", "description": "Az új csomag. `free` – Ingyenes, `basic` – Alap, `premium` – Prémium csomag.", "enum": [ "free", "basic", "premium" ] } }, "required": [ "package" ] } } } }, "responses": { "200": { "description": "A csomag megváltozott, üres választörzzsel." }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/packages/package-notification": { "get": { "tags": [ "Előfizetési csomag" ], "summary": "Csomaghoz kapcsolódó értesítés", "description": "Ha az irodának egyedi (kedvezményes) díjazása van, egy erről szóló, megjelenítésre szánt szöveget ad vissza (az érvényesség végével, ha van); egyébként `null`-t. Minden szerepkör hívhatja.", "responses": { "200": { "description": "Sikeres művelet.", "content": { "application/json": { "schema": { "type": "object", "description": "Értesítés.", "properties": { "notification": { "type": "string", "description": "Megjelenítendő szöveg; több bekezdés esetén `

` választja el őket (HTML). `null`, ha nincs értesítés.", "nullable": true } }, "required": [ "notification" ] } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" } } } }, "/invoices": { "get": { "tags": [ "Számlák" ], "summary": "Az iroda előfizetési számláinak listája", "description": "Az iroda részére kiállított összes előfizetési számlát adja vissza azonosító szerint növekvő sorrendben. Lapozás nincs. Csak menedzser szerepkörrel hívható.", "responses": { "200": { "description": "Sikeres művelet.", "content": { "application/json": { "schema": { "type": "array", "description": "Számlák.", "items": { "$ref": "#/components/schemas/Invoice" } } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" } } } }, "/invoices/{invoiceId}": { "get": { "tags": [ "Számlák" ], "summary": "Számla lekérdezése", "description": "Az iroda egy előfizetési számláját adja vissza. Más iroda számlájára 404. Csak menedzser szerepkörrel hívható.", "parameters": [ { "name": "invoiceId", "in": "path", "required": true, "description": "A számla azonosítója (csak a saját iroda számlái közül).", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Sikeres művelet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/invoices/current-pricing": { "get": { "tags": [ "Számlák" ], "summary": "A folyamatban lévő számlázási időszak várható díja", "description": "Megmutatja, milyen tételekkel és összeggel készülne el az iroda következő előfizetési számlája, ha a folyamatban lévő számlázási időszak ma zárulna (a mai napig eltelt napokkal arányosan). Ingyenes csomagnál, külön elszámolású irodánál, próbaidőszakban vagy számlázható adózó hiányában a tétellista üres. Minden szerepkör hívhatja.", "responses": { "200": { "description": "Sikeres művelet.", "content": { "application/json": { "schema": { "type": "object", "description": "Várható díj.", "properties": { "trustees_count": { "type": "integer", "description": "A számlázható (az időszakban elég napon aktív, egyedi) adózók száma; ha nincs számlázható tétel, az aktív egyedi adózók száma." }, "price": { "type": "integer", "description": "A tételek nettó összege forintban." }, "invoice_items": { "type": "array", "description": "A számla várható tételei.", "items": { "type": "object", "description": "Egy tétel.", "properties": { "name": { "type": "string", "description": "A tétel megnevezése.", "example": "Aktív adózók díja" }, "quantity": { "type": "integer", "description": "Mennyiség (alapdíjnál 1, adózódíjnál az adózók száma)." }, "unit_price": { "type": "integer", "description": "Nettó egységár forintban, az eltelt időszakkal arányosítva; kedvezménynél negatív." }, "price": { "type": "integer", "description": "A tétel nettó összege forintban (mennyiség × egységár)." }, "comment": { "type": "string", "description": "Megjegyzés a tételhez.", "nullable": true } } } } }, "required": [ "trustees_count", "price", "invoice_items" ] } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" } } } }, "/sent-mails/{sentMailId}": { "get": { "tags": [ "Elküldött levelek" ], "summary": "Elküldött e-mail megtekintése", "description": "Egy elküldött e-mail adatai, kiegészítve a levél tárgyával, HTML-törzsével, mellékleteinek számával és a kézbesítési eseményekkel (ezeket a rendszer a levélküldő szolgáltatótól kéri le; ha ott nem érhetők el, null / üres). Az iroda bármely levele elérhető (adózónkénti szűkítés nincs). Szerepkör: menedzser vagy könyvelő.", "parameters": [ { "name": "sentMailId", "in": "path", "required": true, "description": "Az elküldött e-mail azonosítója.", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Az elküldött e-mail a tartalmával.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SentMail" }, { "type": "object", "properties": { "subject": { "type": "string", "nullable": true, "description": "A levél tárgya." }, "body": { "type": "string", "nullable": true, "description": "A levél HTML-törzse." }, "attachment_count": { "type": "integer", "nullable": true, "description": "A mellékletek száma." }, "events": { "type": "array", "description": "Kézbesítési események időrendben.", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Az esemény neve (pl. sent, delivered, opened).", "example": "delivered" }, "time": { "type": "integer", "format": "int64", "description": "Az esemény ideje, unix időbélyeg.", "example": 1793088000 } } } } } } ] } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/sent-mails/search": { "post": { "tags": [ "Elküldött levelek" ], "summary": "Elküldött e-mailek keresése", "description": "Az iroda nevében kiküldött e-mailek lapozott, szűrhető listája (alapból a legújabb elöl). Az iroda összes levelét tartalmazza.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "limit": { "type": "integer", "nullable": true, "minimum": 1, "maximum": 200, "description": "Lapméret (alapértelmezés: 200)." }, "page": { "type": "integer", "nullable": true, "minimum": 1, "description": "Lap sorszáma (alapértelmezés: 1)." }, "order_column": { "type": "string", "nullable": true, "enum": [ "email", "attachment", "created_at", "updated_at", null ], "description": "Rendezés oszlopa (alapértelmezés: created_at)." }, "order_direction": { "type": "string", "nullable": true, "enum": [ "asc", "desc", null ], "description": "Rendezés iránya (alapértelmezés: desc)." }, "search": { "type": "string", "nullable": true, "description": "Szabad szavas keresés a címzett e-mail címében (részszó-egyezés, minden szónak illeszkednie kell)." }, "type": { "type": "string", "nullable": true, "enum": [ "message", "summary", "trustee_debt_notification", "trustee_roles", "tax_account_query_completed", "job_completed", "new_trustees", null ], "description": "Csak ilyen fajtájú levelek (lásd SentMail.type). A customer_portals_disconnected és payment_obligation fajtára a kód nem enged szűrni (422)." }, "attachment": { "type": "boolean", "nullable": true, "description": "true = csak a mellékletes, false = csak a melléklet nélküli levelek." }, "status": { "type": "string", "nullable": true, "enum": [ "sent", "delivered", "opened", "failed", null ], "description": "Csak ilyen kézbesítési állapotú levelek (lásd SentMail.status)." }, "created_at_min": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 1893456000, "nullable": true, "description": "Küldés ideje legkorábban, unix időbélyeg." }, "created_at_max": { "type": "integer", "format": "int64", "minimum": 0, "maximum": 1893456000, "nullable": true, "description": "Küldés ideje legkésőbb, unix időbélyeg." } } } } } }, "responses": { "200": { "description": "A találatok egy lapja.", "content": { "application/json": { "schema": { "type": "object", "properties": { "records": { "type": "array", "items": { "$ref": "#/components/schemas/SentMail" }, "description": "Az aktuális lap levelei." }, "count": { "type": "integer", "description": "Az összes találat száma." }, "page": { "type": "integer", "description": "Az aktuális lap sorszáma." }, "max_page": { "type": "integer", "description": "Az utolsó lap sorszáma (0, ha nincs találat)." }, "order_column": { "type": "string", "description": "A ténylegesen alkalmazott rendezési oszlop." }, "order_direction": { "type": "string", "enum": [ "asc", "desc" ], "description": "A ténylegesen alkalmazott rendezési irány." } } } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/municipalities": { "get": { "tags": [ "Önkormányzatok" ], "summary": "Önkormányzatok listázása", "description": "Az összes magyarországi önkormányzat, amelynek adószámláját a rendszer az önkormányzati (ASP) rendszerből le tudja tölteni, azonosító szerint, lapozás nélkül. Az azonosítók az adózó önkormányzatainak beállításához kellenek (`PUT /trustees/{trusteeId}`, `municipality_ids`). A lista minden irodának azonos. Jogosultság: bármely bejelentkezett felhasználó, bármely csomag.", "responses": { "200": { "description": "Az önkormányzatok tömbje.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Municipality" } } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" } } } }, "/municipalities/{municipalityId}": { "get": { "tags": [ "Önkormányzatok" ], "summary": "Önkormányzat megtekintése", "description": "Egy önkormányzat azonosítója és neve. Jogosultság: bármely bejelentkezett felhasználó.", "parameters": [ { "name": "municipalityId", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "Az önkormányzat azonosítója (`Municipality.id`).", "example": 2658 } ], "responses": { "200": { "description": "Az önkormányzat.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Municipality" } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/payment-obligations": { "get": { "tags": [ "Fizetési kötelezettségek" ], "summary": "Fizetési kötelezettségek listázása", "description": "Az összes fizetési kötelezettség (kézzel rögzített és automatikusan létrejött tétel) a felhasználó által elérhető aktív adózóknál, azonosító szerint növekvő sorrendben, lapozás nélkül, a kiküldött levelekkel (`sent_mails`). Jogosultság: csak Prémium csomagban, bármely szerepkör (menedzser, könyvelő, adózó); adózó szerepkörű vagy „kijelölt adózók” jogkörű felhasználó csak a hozzá rendelt adózók tételeit látja. Évre bontott, lapozott nézethez a `POST /payment-obligations/table` való.", "responses": { "200": { "description": "A kötelezettségek tömbje.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentObligation" } } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" } } }, "post": { "tags": [ "Fizetési kötelezettségek" ], "summary": "Fizetési kötelezettség rögzítése", "description": "Kézzel rögzít egy fizetési kötelezettséget egy adózóhoz (pl. kamarai tagdíj, könyvelési díj, bevallásból fizetendő ÁFA). A létrejött tétel `creator` értéke `user`, így később módosítható és törölhető. A tétel bekerül az esedékesség előtti automatikus emlékeztetőkbe, ha az iroda ilyet beállított. Jogosultság: csak Prémium csomagban, menedzser vagy könyvelő szerepkör.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "trustee_id", "name", "price", "due" ], "properties": { "trustee_id": { "type": "integer", "description": "Az adózó azonosítója, akihez a kötelezettség tartozik. Csak a felhasználó által elérhető aktív adózó adható meg." }, "name": { "type": "string", "maxLength": 255, "example": "Kamarai tagdíj", "description": "A kötelezettség megnevezése (pl. „101 Társasági adó”, „Kamarai tagdíj”)." }, "price": { "type": "integer", "format": "int64", "example": 35000, "description": "A fizetendő összeg forintban, egész számként." }, "due": { "type": "string", "format": "date", "example": "2026-11-12", "description": "Az esedékesség (fizetési határidő) napja, ÉÉÉÉ-HH-NN." }, "bank_account_number": { "type": "string", "nullable": true, "example": "10032000-01076019", "description": "A kedvezményezett bankszámlaszáma (2×8 vagy 3×8 számjegy, kötőjellel, szóközzel vagy anélkül; a rendszer ellenőrzi a CDV-t)." }, "announcement": { "type": "string", "nullable": true, "maxLength": 255, "example": "Adószám: 12345676-1-23", "description": "Az utalási közlemény." }, "note": { "type": "string", "nullable": true, "maxLength": 65535, "description": "Megjegyzés a tételhez; az ügyfélnek küldött levélben is megjelenik." } } } } } }, "responses": { "200": { "description": "A létrehozott kötelezettség.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentObligation" } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/payment-obligations/{paymentObligationId}": { "get": { "tags": [ "Fizetési kötelezettségek" ], "summary": "Fizetési kötelezettség megtekintése", "description": "Egy fizetési kötelezettség adatai a kiküldött levelekkel (`sent_mails`). Jogosultság: csak Prémium csomagban, bármely szerepkör (menedzser, könyvelő, adózó); adózó szerepkörű vagy „kijelölt adózók” jogkörű felhasználó csak a hozzá rendelt adózók tételeit látja.", "parameters": [ { "name": "paymentObligationId", "in": "path", "required": true, "description": "A fizetési kötelezettség azonosítója.", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "A kötelezettség.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentObligation" } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "tags": [ "Fizetési kötelezettségek" ], "summary": "Fizetési kötelezettség módosítása", "description": "Egy kézzel rögzített fizetési kötelezettség módosítása. Minden mezőt újra meg kell adni (a kihagyott nem kötelező mező `null` lesz). Automatikusan létrejött tétel (`creator` ≠ `user`) nem módosítható: 403. Jogosultság: csak Prémium csomagban, menedzser vagy könyvelő szerepkör.", "parameters": [ { "name": "paymentObligationId", "in": "path", "required": true, "description": "A fizetési kötelezettség azonosítója.", "schema": { "type": "integer", "minimum": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "trustee_id", "name", "price", "due" ], "properties": { "trustee_id": { "type": "integer", "description": "Az adózó azonosítója, akihez a kötelezettség tartozik. Csak a felhasználó által elérhető aktív adózó adható meg." }, "name": { "type": "string", "maxLength": 255, "example": "Kamarai tagdíj", "description": "A kötelezettség megnevezése (pl. „101 Társasági adó”, „Kamarai tagdíj”)." }, "price": { "type": "integer", "format": "int64", "example": 35000, "description": "A fizetendő összeg forintban, egész számként." }, "due": { "type": "string", "format": "date", "example": "2026-11-12", "description": "Az esedékesség (fizetési határidő) napja, ÉÉÉÉ-HH-NN." }, "bank_account_number": { "type": "string", "nullable": true, "example": "10032000-01076019", "description": "A kedvezményezett bankszámlaszáma (2×8 vagy 3×8 számjegy, kötőjellel, szóközzel vagy anélkül; a rendszer ellenőrzi a CDV-t)." }, "announcement": { "type": "string", "nullable": true, "maxLength": 255, "example": "Adószám: 12345676-1-23", "description": "Az utalási közlemény." }, "note": { "type": "string", "nullable": true, "maxLength": 65535, "description": "Megjegyzés a tételhez; az ügyfélnek küldött levélben is megjelenik." } } } } } }, "responses": { "200": { "description": "A módosított kötelezettség.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentObligation" } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } }, "delete": { "tags": [ "Fizetési kötelezettségek" ], "summary": "Fizetési kötelezettség törlése", "description": "Egy kézzel rögzített fizetési kötelezettség végleges törlése. Automatikusan létrejött tétel (`creator` ≠ `user`) nem törölhető: 403. Jogosultság: csak Prémium csomagban, menedzser vagy könyvelő szerepkör.", "parameters": [ { "name": "paymentObligationId", "in": "path", "required": true, "description": "A fizetési kötelezettség azonosítója.", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Sikeres törlés (üres választörzs)." }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/payment-obligations/export": { "post": { "tags": [ "Fizetési kötelezettségek" ], "summary": "Fizetési kötelezettségek exportálása Excelbe", "description": "A fizetési kötelezettségeket Excel fájlba exportálja (adózó, adószám, adóazonosító, kötelezettség neve, összeg, egyenleg, esedékesség, bankszámlaszám, utalási közlemény, megjegyzés). Ugyanazokat a szűrőket fogadja, mint a `POST /payment-obligations/table`; mind elhagyható, szűrő nélkül minden elérhető tétel bekerül. Legfeljebb 50 000 tétel exportálható, felette 422. Jogosultság: csak Prémium csomagban, bármely szerepkör (menedzser, könyvelő, adózó); adózó szerepkörű vagy „kijelölt adózók” jogkörű felhasználó csak a hozzá rendelt adózók tételeit látja.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "year": { "type": "integer", "minimum": 2000, "maximum": 2050, "nullable": true, "example": 2026, "description": "Tárgyév: csak az ebben az évben esedékes tételek." }, "trustee_id": { "type": "integer", "minimum": 1, "nullable": true, "description": "Csak ennek az adózónak a tételei." }, "customer_portal_id": { "type": "integer", "nullable": true, "minimum": 1, "description": "Szűrés ügyfélkapura: csak az ehhez az ügyfélkapuhoz tartozó adózók. Az iroda saját ügyfélkapujának azonosítója kell legyen, különben validációs hiba." }, "taxation_type": { "type": "string", "nullable": true, "enum": [ "VSZJA", "Átalányadó", "Új KATA", "Társasági adó", "KIVA", null ], "description": "Szűrés az adózó adózási formájára (az adózó adatlapján rögzített érték): `VSZJA` vállalkozói SZJA, `Átalányadó`, `Új KATA`, `Társasági adó`, `KIVA` kisvállalati adó." }, "vat_period": { "type": "string", "nullable": true, "enum": [ "Havi", "Negyedéves", "Éves", null ], "description": "Szűrés az adózó áfabevallási gyakoriságára: `Havi`, `Negyedéves` vagy `Éves`." }, "search": { "type": "string", "nullable": true, "description": "Szabad szöveges keresés szavanként (minden szónak illeszkednie kell) az adózó nevében, adószámában, adóazonosító jelében, adózási formájában, áfagyakoriságában, ÁSP-ben képviselt adószámában és megjegyzésében." }, "order_direction": { "type": "string", "nullable": true, "enum": [ "asc", "desc", null ], "default": "asc", "description": "A tételek sorrendje azonosító szerint: `asc` növekvő (alapértelmezés), `desc` csökkenő." } } } } } }, "responses": { "200": { "description": "Az Excel fájl.", "content": { "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/payment-obligations/download-import-sample": { "get": { "tags": [ "Fizetési kötelezettségek" ], "summary": "Import-minta Excel letöltése", "description": "Kitöltött példasorokat tartalmazó Excel sablon a `POST /payment-obligations/import` végponthoz. Oszlopai: „Adószám vagy adóazonosító”, „Kötelezettség neve”, „Összeg”, „Esedékesség”, „Bankszámlaszám”, „Utalási közlemény”, „Megjegyzés”, „Értesítés ennyi nappal az esedékesség előtt” (ez utóbbit az import figyelmen kívül hagyja). Jogosultság: csak Prémium csomagban, menedzser vagy könyvelő szerepkör.", "responses": { "200": { "description": "Az Excel sablon.", "content": { "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" } } } }, "/payment-obligations/import": { "post": { "tags": [ "Fizetési kötelezettségek" ], "summary": "Fizetési kötelezettségek importálása Excelből", "description": "Kézzel rögzített fizetési kötelezettségeket hoz létre egy Excel/CSV fájlból (a minta: `GET /payment-obligations/download-import-sample`); az első sor a fejléc. Az adózót adószám vagy adóazonosító jel azonosítja; csak a felhasználó által elérhető aktív adózó fogadható el. Ha ugyanaz az adószám több adózónál is szerepel (pl. több ügyfélkapu alatt), mindegyiknél létrejön a tétel. Bármely hibás sor esetén semmi nem kerül be, a válasz 422 a soronkénti hibaüzenetekkel. Jogosultság: csak Prémium csomagban, menedzser vagy könyvelő szerepkör.", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "import_file" ], "properties": { "import_file": { "type": "string", "format": "binary", "description": "A kitöltött fájl (xls, xlsx, csv vagy txt)." } } } } } }, "responses": { "200": { "description": "Sikeres import (üres választörzs)." }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/payment-obligations/table": { "post": { "tags": [ "Fizetési kötelezettségek" ], "summary": "Fizetési kötelezettségek éves táblázata havi bontásban", "description": "A felület „Fizetési kötelezettségek” táblázata: adózónként egy sor (adózó név szerint rendezve, lapozva), benne a tárgyévben esedékes tételek hónapokra bontva. Minden elérhető aktív adózó szerepel, akkor is, ha az évben nincs tétele (ekkor a 12 hónap üres tömb). Jogosultság: csak Prémium csomagban, bármely szerepkör (menedzser, könyvelő, adózó); adózó szerepkörű vagy „kijelölt adózók” jogkörű felhasználó csak a hozzá rendelt adózók tételeit látja.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "year" ], "properties": { "year": { "type": "integer", "minimum": 2000, "maximum": 2050, "example": 2026, "description": "Tárgyév: a táblázat az ebben az évben esedékes tételeket mutatja." }, "limit": { "type": "integer", "minimum": 1, "maximum": 200, "nullable": true, "default": 200, "description": "Egy oldalon visszaadott rekordok száma (alapértelmezés: 200)." }, "page": { "type": "integer", "minimum": 1, "nullable": true, "default": 1, "description": "A lekért oldal sorszáma (alapértelmezés: 1)." }, "search": { "type": "string", "nullable": true, "description": "Szabad szöveges keresés szavanként (minden szónak illeszkednie kell) az adózó nevében, adószámában, adóazonosító jelében, adózási formájában, áfagyakoriságában, ÁSP-ben képviselt adószámában és megjegyzésében." }, "trustee_id": { "type": "integer", "minimum": 1, "nullable": true, "description": "Csak ez az egy adózó (a jogosultsági kör ettől nem bővül)." }, "customer_portal_id": { "type": "integer", "nullable": true, "minimum": 1, "description": "Szűrés ügyfélkapura: csak az ehhez az ügyfélkapuhoz tartozó adózók. Az iroda saját ügyfélkapujának azonosítója kell legyen, különben validációs hiba." }, "taxation_type": { "type": "string", "nullable": true, "enum": [ "VSZJA", "Átalányadó", "Új KATA", "Társasági adó", "KIVA", null ], "description": "Szűrés az adózó adózási formájára (az adózó adatlapján rögzített érték): `VSZJA` vállalkozói SZJA, `Átalányadó`, `Új KATA`, `Társasági adó`, `KIVA` kisvállalati adó." }, "vat_period": { "type": "string", "nullable": true, "enum": [ "Havi", "Negyedéves", "Éves", null ], "description": "Szűrés az adózó áfabevallási gyakoriságára: `Havi`, `Negyedéves` vagy `Éves`." } } } } } }, "responses": { "200": { "description": "Az adózónkénti sorok és a lapozási adatok.", "content": { "application/json": { "schema": { "type": "object", "required": [ "table", "count", "page", "max_page" ], "properties": { "table": { "type": "array", "description": "Adózónként egy sor, az adózó neve szerint rendezve.", "items": { "type": "object", "required": [ "trustee", "months" ], "properties": { "trustee": { "allOf": [ { "$ref": "#/components/schemas/Trustee" } ], "description": "Az adózó adatai." }, "months": { "type": "array", "minItems": 12, "maxItems": 12, "description": "Pontosan 12 elem: a 0. index január, a 11. december. Minden elem az adott hónapban esedékes tételek tömbje esedékesség szerint rendezve (üres tömb, ha nincs). A tételekben nincs `trustee` mező.", "items": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentObligation" } } } } } }, "count": { "type": "integer", "description": "A szűrésnek megfelelő adózók teljes száma." }, "page": { "type": "integer", "description": "Az aktuális oldal sorszáma." }, "max_page": { "type": "integer", "description": "Az utolsó oldal sorszáma (0, ha nincs találat)." } } } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/payment-obligations/{paymentObligationId}/send-mail": { "post": { "tags": [ "Fizetési kötelezettségek" ], "summary": "Fizetési kötelezettség kiküldése emailben", "description": "Egy fizetési kötelezettséget emailben elküld a kérésben megadott címekre. Címzett: KIZÁRÓLAG az `emails` tömbben megadott címek (bármilyen cím lehet, nem kell az adózó rögzített címének lennie); minden cím külön levelet kap. A levél „1 kötelezettség értesítés érkezett” tárggyal, az iroda nevében megy, és tartalmazza a tétel nevét, összegét, egyenlegét az esedékesség napján, esedékességét, bankszámlaszámát, közleményét, megjegyzését és a kísérő üzenetet (`note`). A kiküldés a tétel `sent_mails` mezőjében és `notification_status` állapotában látszik. Jogosultság: csak Prémium csomagban, bármely szerepkör (menedzser, könyvelő, adózó); adózó szerepkörű vagy „kijelölt adózók” jogkörű felhasználó csak a hozzá rendelt adózók tételeit látja.", "parameters": [ { "name": "paymentObligationId", "in": "path", "required": true, "description": "A fizetési kötelezettség azonosítója.", "schema": { "type": "integer", "minimum": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "emails" ], "properties": { "emails": { "type": "array", "minItems": 1, "items": { "type": "string", "format": "email" }, "example": [ "ugyfel@example.com" ], "description": "A címzett email címek." }, "note": { "type": "string", "nullable": true, "description": "Kísérő üzenet, amely „Megjegyzés” címmel megjelenik a levélben." } } } } } }, "responses": { "200": { "description": "A levél kiküldése elindult (üres választörzs)." }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/payment-obligations/send-bulk-mail": { "post": { "tags": [ "Fizetési kötelezettségek" ], "summary": "Fizetési kötelezettségek tömeges kiküldése az adózóknak", "description": "A kiválasztott adózóknak emailben elküldi az adott időszakban esedékes összes fizetési kötelezettségüket. Címzett: minden adózó a SAJÁT értesítési email címeire kapja (az adózó `emails` mezője, a felületen „Üzenet küldési e-mail”), adózónként egy levélben, amely az időszakba eső összes tételét felsorolja (név, összeg, egyenleg az esedékesség napján, esedékesség, bankszámlaszám, közlemény, megjegyzés); több cím esetén minden cím külön levelet kap. A könyvelői, bérszámfejtői, adótanácsadói címek nem kapnak levelet. Kimarad hibaüzenet nélkül az az adózó, akinek nincs értesítési email címe, nincs tétele az időszakban, inaktív, vagy a felhasználó nem éri el. A levél az iroda nevében megy; a kiküldések a tételek `sent_mails` mezőjében és `notification_status` állapotában látszanak. Jogosultság: csak Prémium csomagban, bármely szerepkör (menedzser, könyvelő, adózó); adózó szerepkörű vagy „kijelölt adózók” jogkörű felhasználó csak a hozzá rendelt adózók tételeit látja.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "trustee_ids", "due_from", "due_to" ], "properties": { "trustee_ids": { "type": "array", "minItems": 1, "items": { "type": "integer", "minimum": 1 }, "example": [ 123, 456 ], "description": "A kiértesítendő adózók azonosítói." }, "due_from": { "type": "string", "format": "date", "example": "2026-01-01", "description": "Az esedékességi időszak első napja (ÉÉÉÉ-HH-NN), a határt is beleértve." }, "due_to": { "type": "string", "format": "date", "example": "2026-12-31", "description": "Az esedékességi időszak utolsó napja (ÉÉÉÉ-HH-NN), a határt is beleértve." }, "note": { "type": "string", "nullable": true, "description": "Kísérő üzenet, amely „Megjegyzés” címmel minden levélben megjelenik." } } } } } }, "responses": { "200": { "description": "A levelek kiküldése elindult (üres választörzs)." }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/declaration-obligations/table": { "post": { "tags": [ "Bevallási kötelezettségek" ], "summary": "Adónaptár: bevallási kötelezettségek éves táblázata havi bontásban", "description": "Az Adónaptár adatai: adózónként (név szerint rendezve, lapozva) a megadott év bevallási kötelezettségei, ahogy a NAV Online Ügyfélportál nyilvántartja őket, az esedékesség hónapja szerint 12 oszlopba sorolva. Minden kötelezettséghez jön a számolt állapota és a rá beérkezett bevallások. A lapozás az adózókra vonatkozik; az adózó akkor is szerepel, ha az évben nincs kötelezettsége. Minden csomagban és minden szerepkörrel elérhető. Csak a hívó irodájának aktív ügyfélkapuihoz tartozó, aktív adózók adatai látszanak; „megadott adózók” hozzáférésű felhasználónál csak a hozzá rendelt adózóké.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "year": { "type": "integer", "minimum": 2000, "maximum": 2050, "example": 2026, "description": "A tárgyév: az ebben az évben esedékes kötelezettségek jönnek." }, "limit": { "type": "integer", "minimum": 1, "maximum": 200, "nullable": true, "default": 200, "description": "Oldalméret (adózók száma oldalanként). Alapértelmezés: 200." }, "page": { "type": "integer", "minimum": 1, "nullable": true, "default": 1, "description": "A kért oldal sorszáma (1-től)." }, "search": { "type": "string", "nullable": true, "description": "Keresés az adózókra szavanként (minden szónak illeszkednie kell, részleges egyezés): név, adószám, adóazonosító jel, adózási forma, áfa-gyakoriság, ÁSP-ben képviselt adószám, megjegyzés." }, "customer_portal_id": { "type": "integer", "minimum": 1, "nullable": true, "description": "Csak ennek az ügyfélkapunak az adózói. Az ügyfélkapunak a hívó irodájához kell tartoznia, különben 422." }, "taxation_type": { "type": "string", "nullable": true, "enum": [ null, "VSZJA", "Átalányadó", "Új KATA", "Társasági adó", "KIVA" ], "description": "Csak az ilyen adózási formájú adózók: `VSZJA` vállalkozói SZJA, `Átalányadó`, `Új KATA`, `Társasági adó`, `KIVA` kisvállalati adó." }, "vat_period": { "type": "string", "nullable": true, "enum": [ null, "Havi", "Negyedéves", "Éves" ], "description": "Csak az ilyen áfabevallási gyakoriságú adózók." }, "trustee_id": { "type": "integer", "minimum": 1, "nullable": true, "description": "Csak ez az egy adózó (ha a hívó hozzáfér; a hozzáférési kört nem bővíti)." } }, "required": [ "year" ] } } } }, "responses": { "200": { "description": "Az adózónkénti havi táblázat egy oldala.", "content": { "application/json": { "schema": { "type": "object", "required": [ "table", "count", "page", "max_page" ], "properties": { "table": { "type": "array", "description": "Soronként egy adózó.", "items": { "type": "object", "required": [ "trustee", "months" ], "properties": { "trustee": { "allOf": [ { "$ref": "#/components/schemas/Trustee" } ], "description": "Az adózó." }, "months": { "type": "array", "minItems": 12, "maxItems": 12, "description": "Pontosan 12 elem, a 0. a január, a 11. a december. Minden elem az abban a hónapban esedékes kötelezettségek tömbje (esedékesség, majd nyomtatvány szerint rendezve); üres hónapnál üres tömb.", "items": { "type": "array", "items": { "$ref": "#/components/schemas/DeclarationObligation" } } } } } }, "count": { "type": "integer", "description": "A szűrésnek megfelelő adózók száma." }, "page": { "type": "integer", "description": "Az aktuális oldal sorszáma." }, "max_page": { "type": "integer", "description": "Az utolsó oldal sorszáma (0, ha nincs találat)." } } } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/surveys": { "get": { "tags": [ "Adategyeztetések" ], "summary": "Adategyeztetések listázása", "description": "A NAV által az adózóknak küldött adategyeztetések (az Online Ügyfélportálon kitöltendő kérdőívek) és állapotuk, az adózó adataival. Lapozás és szűrés nincs, a teljes lista egyben jön, azonosító szerint rendezve. Kitölteni és beküldeni a NAV felületén lehet, itt csak az állapot követhető. Minden szerepkör és csomag hívhatja. Csak a hívó irodájának aktív ügyfélkapuihoz tartozó, aktív adózók adatai látszanak; „megadott adózók” hozzáférésű felhasználónál csak a hozzá rendelt adózóké.", "responses": { "200": { "description": "Az adategyeztetések.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Survey" } } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" } } } }, "/surveys/{surveyId}": { "get": { "tags": [ "Adategyeztetések" ], "summary": "Adategyeztetés megtekintése", "description": "Egy adategyeztetés adatai az adózóval. Minden szerepkör és csomag hívhatja. Csak a hívó irodájának aktív ügyfélkapuihoz tartozó, aktív adózók adatai látszanak; „megadott adózók” hozzáférésű felhasználónál csak a hozzá rendelt adózóké. Nem hozzáférhető rekordra 404 a válasz.", "parameters": [ { "name": "surveyId", "in": "path", "required": true, "description": "Az adategyeztetés azonosítója (`id`).", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Az adategyeztetés.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Survey" } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/pmtseged/update-api-key": { "post": { "tags": [ "PmtSegéd" ], "summary": "PmtSegéd API-kulcs beállítása", "description": "Beállítja vagy törli (`null`) az iroda PmtSegéd.hu API-kulcsát, amellyel a KapuSegéd az aktív adózókat ügyfélként átadhatja a PmtSegéd pénzmosás-megelőzési rendszerbe. Mentés előtt a rendszer ellenőrzi a kulcsot a PmtSegédnél (érvénytelen kulcsnál 422). Más kulcs megadásakor az eddigi összekapcsolások és az utolsó szinkron ideje törlődnek. Csak menedzser szerepkörrel hívható. A válasz a frissített iroda.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "pmtseged_api_key": { "type": "string", "description": "A PmtSegéd.hu fiókban létrehozott API-kulcs; `null` vagy üres érték a kapcsolatot bontja.", "nullable": true, "maxLength": 255 } }, "required": [ "pmtseged_api_key" ] } } } }, "responses": { "200": { "description": "Sikeres művelet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Office" } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/pmtseged/sync": { "post": { "tags": [ "PmtSegéd" ], "summary": "PmtSegéd-szinkron kézi indítása", "description": "Az iroda még össze nem kapcsolt aktív adózóit átadja a PmtSegédnek: ha ott már van ilyen ügyfél (adószám, magánszemélynél név szerint), összekapcsolja, ha nincs, létrehozza a nyilvános cégadatokkal kiegészítve. A kérés a szinkron végéig tart. Csak menedzser szerepkörrel és beállított API-kulccsal hívható (különben 403); ha a szinkron már fut, vagy a PmtSegéd elutasítja (pl. érvénytelen kulcs, lejárt előfizetés), 422. A válasz a frissített iroda (`pmtseged_sync_completed_at`).", "responses": { "200": { "description": "Sikeres művelet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Office" } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/customer-portals/codes": { "get": { "tags": [ "Ügyfélkapuk" ], "summary": "Ügyfélkapu+ hitelesítő kódok lekérdezése", "description": "A felhasználó által látható, tárolt hitelesítő kulcsú (Ügyfélkapu+ hitelesítő alkalmazásos) ügyfélkapuk 6 jegyű belépési kódjai a mostani 30 másodperces időszaktól kezdve több időszakra előre, név szerint rendezve. Csak a kódok mennek ki, a hitelesítő kulcs (2FA-titok) SOHA. Az aktuális kódot a `server_time` alapján kell kiválasztani: index = floor((server_time/1000 − starts_at) / period). Szerepkör: menedzser vagy könyvelő.", "responses": { "200": { "description": "A kódok.", "content": { "application/json": { "schema": { "type": "object", "properties": { "server_time": { "type": "integer", "format": "int64", "description": "A szerver ideje a válasz pillanatában, ezredmásodpercben (unix ms) — a kliens órájának igazításához.", "example": 1793088012345 }, "starts_at": { "type": "integer", "format": "int64", "description": "Unix időbélyeg (mp): a `codes[0]` időszakának kezdete.", "example": 1793088000 }, "period": { "type": "integer", "description": "Egy kód érvényességi ideje másodpercben.", "example": 30 }, "windows": { "type": "integer", "description": "Hány egymást követő időszak kódja szerepel ügyfélkapunként (a `codes` hossza).", "example": 10 }, "portals": { "type": "array", "description": "Ügyfélkapunként a kódok.", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Az ügyfélkapu azonosítója." }, "name": { "type": "string", "description": "Az ügyfélkapu megnevezése." }, "username": { "type": "string", "nullable": true, "description": "Az ügyfélkapus felhasználónév." }, "active": { "type": "boolean", "description": "Aktív-e az ügyfélkapu." }, "codes": { "type": "array", "items": { "type": "string", "pattern": "^\\d{6}$" }, "description": "A 6 jegyű kódok időszakonként: az i. elem a starts_at + i × period időponttól érvényes.", "example": [ "123456", "654321" ] } } } } } } } } }, "401": { "$ref": "#/components/responses/NotAuthorized" }, "403": { "$ref": "#/components/responses/NoPermission" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "API-kulcs (Beállítások › API kulcsok) vagy a `POST /login` által adott `access_token`." }, "PartnerToken": { "type": "apiKey", "in": "header", "name": "partner-token", "description": "Nem kötelező partner-azonosító. Ha küldöd, érvényesnek kell lennie." } }, "responses": { "NotAuthorized": { "description": "Nincs bejelentkezve", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "NoPermission": { "description": "Nincs jogosultsága", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "ValidationError": { "description": "Validációs hiba", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "errors": { "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } } } } } } } }, "NotFound": { "description": "A rekord nem található", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } } }, "schemas": { "Office": { "type": "object", "description": "Iroda (könyvelőiroda): a KapuSegéd előfizetője, amelyhez a felhasználók, ügyfélkapuk és adózók tartoznak.", "properties": { "id": { "type": "integer", "description": "Az iroda azonosítója." }, "token": { "type": "string", "description": "Az iroda ajánlói kódja (8 karakter, nagybetűk és számok); regisztrációnál `referral_code`-ként adható meg.", "example": "AB12CD34" }, "email": { "type": "string", "description": "Az iroda email-címe (a regisztráló felhasználó címe); ide mennek az előfizetési számlák.", "format": "email" }, "package": { "type": "string", "description": "Az aktuális előfizetési csomag. `free` – Ingyenes, `basic` – Alap, `premium` – Prémium.", "enum": [ "free", "basic", "premium" ] }, "billing_name": { "type": "string", "description": "Számlázási név.", "nullable": true }, "billing_city": { "type": "string", "description": "Számlázási cím: település.", "nullable": true }, "billing_zip": { "type": "integer", "description": "Számlázási cím: irányítószám.", "minimum": 1000, "maximum": 9999, "nullable": true }, "billing_address": { "type": "string", "description": "Számlázási cím: közterület, házszám.", "nullable": true }, "billing_tax_number": { "type": "string", "description": "Adószám „12345678-1-12” formátumban.", "nullable": true, "example": "12345676-1-43" }, "tarhely_trustee_active_default": { "type": "boolean", "description": "Tárhely-üzenetben talált új adózó alapból aktív-e." }, "upo_trustee_active_default": { "type": "boolean", "description": "Az ÜPO-n talált új adózó alapból aktív-e." }, "mailbox_active_default": { "type": "boolean", "description": "A tárhelyen talált új cégkapu alapból aktív-e." }, "summary_mail_interval_days": { "type": "integer", "description": "Összesítő email gyakorisága napokban.", "minimum": 1, "maximum": 30 }, "trustee_debt_mail_interval_days": { "type": "integer", "description": "Adózói hátralék-értesítő email gyakorisága napokban.", "minimum": 1, "maximum": 30 }, "email_alias": { "type": "string", "description": "A kiküldött levelek feladóneve; `null` esetén az alapértelmezett.", "nullable": true }, "reply_to_email": { "type": "string", "description": "A kiküldött levelek válaszcíme.", "format": "email" }, "payment_obligation_notification_days_before_due": { "type": "array", "description": "Hány nappal az esedékesség előtt menjen fizetési kötelezettség-emlékeztető az adózónak (csökkenő sorrendben); üres lista: nincs emlékeztető.", "items": { "type": "integer", "minimum": 0, "maximum": 30 }, "example": [ 7, 1 ] }, "pmtseged_api_key": { "type": "string", "description": "A beállított PmtSegéd.hu API-kulcs; a válasz a teljes értéket visszaadja. `null`, ha nincs bekötve.", "nullable": true }, "pmtseged_sync_completed_at": { "type": "integer", "description": "Az utolsó sikeres PmtSegéd-szinkron ideje (unix időbélyeg, másodperc); `null`, ha még nem volt, vagy a kulcs azóta megváltozott.", "nullable": true, "example": 1761562800 } } }, "User": { "type": "object", "description": "Az iroda egy felhasználója (könyvelőirodai munkatárs vagy ügyfél). A jelszót és a 2FA-titkot a válasz nem tartalmazza.", "properties": { "id": { "type": "integer", "description": "A felhasználó azonosítója." }, "office_id": { "type": "integer", "description": "Az iroda azonosítója, amelyhez a felhasználó tartozik." }, "name": { "type": "string", "description": "Teljes név." }, "email": { "type": "string", "description": "Email-cím, egyben a belépési azonosító.", "format": "email" }, "phone": { "type": "string", "description": "Telefonszám.", "nullable": true }, "main": { "type": "boolean", "description": "Az iroda fő felhasználója-e (aki az irodát regisztrálta). A fő felhasználó szerepköre mindig menedzser." }, "status": { "type": "string", "description": "`invited` – meghívták, de még nem regisztrált (nem tud belépni); `active` – regisztrált felhasználó.", "enum": [ "invited", "active" ] }, "role": { "type": "string", "description": "Szerepkör. `manager` – menedzser: az iroda minden beállítását, felhasználóit, számláit és előfizetését kezeli; `accountant` – könyvelő: az adózókkal, üzenetekkel, bevallásokkal dolgozik, az iroda beállításaihoz, a felhasználókhoz és a számlákhoz nem fér hozzá; `trustee` – adózó: az iroda ügyfele, a hozzá rendelt adózók adatait jellemzően csak olvashatja, ügyfélkapus beléptetőt nem használhat.", "enum": [ "manager", "accountant", "trustee" ] }, "can_login_portal": { "type": "boolean", "description": "Használhatja-e a felhasználó az ügyfélkapus beléptetőt (KAÜ-belépés az adózó nevében). Adózó szerepkörnél a beléptető ettől függetlenül nem elérhető." }, "trustee_permission": { "type": "string", "description": "Mely adózókhoz fér hozzá a felhasználó. `all` – az iroda összes adózójához; `specified` – csak a `trustee_ids`-ben kijelölt adózókhoz (és az azokhoz tartozó üzenetekhez, bevallásokhoz stb.).", "enum": [ "all", "specified" ] }, "messages_read_at": { "type": "integer", "description": "Az az időpont (unix időbélyeg, másodperc), amikor a felhasználó utoljára mindent olvasottnak jelölt a tárhely-üzeneteknél; az ennél később érkezett üzenetek számítanak újnak.", "example": 1761562800 }, "permissions": { "type": "object", "description": "A felhasználó szerepköréből adódó jogosultságok: jogosultság-kulcs (pl. `read_office`, `invite_user`, `update_trustee`, `login_portal`) → engedélyezett-e. Egy művelet akkor érhető el, ha itt ÉS a `package_functions`-ben is engedélyezett. A `login_portal` már a `can_login_portal`-lal együtt értendő.", "additionalProperties": { "type": "boolean" }, "example": { "login_portal": true, "read_office": true, "invite_user": true } }, "package_functions": { "type": "object", "description": "Az iroda csomagjában elérhető funkciók: funkció-kulcs → érték. Logikai érték: benne van-e a csomagban; szám: a csomag korlátja (pl. `max_trustee_count`, `max_customer_portal_count`); `null`: korlátlan, illetve az adott szolgáltatás nem része a csomagnak.", "additionalProperties": { "nullable": true, "type": "object" }, "example": { "invite_user": false, "max_trustee_count": null, "read_declaration": true } }, "two_factor_enabled": { "type": "boolean", "description": "Be van-e kapcsolva a kétlépcsős azonosítás (2FA). A titkot a válasz nem adja vissza." }, "trustees": { "type": "array", "description": "A felhasználóhoz rendelt adózók (`trustee_permission: specified` esetén számít). Csak a felhasználók listájában, egy felhasználó lekérdezésénél és módosításánál szerepel; a törölt ügyfélkapuk adózói nem jelennek meg.", "items": { "$ref": "#/components/schemas/Trustee" } } } }, "ApiKey": { "type": "object", "description": "A felhasználó egy API-kulcsa. A kulcs titkos értékét csak a létrehozás válasza tartalmazza, ez az objektum nem.", "properties": { "id": { "type": "integer", "description": "Az API-kulcs azonosítója (a token „{azonosító}|{titok}” alakjának első része)." }, "name": { "type": "string", "description": "A kulcs megnevezése." }, "last_used_at": { "type": "integer", "description": "Az utolsó használat ideje (unix időbélyeg, másodperc); `null`, ha még nem használták.", "nullable": true, "example": 1761562800 }, "created_at": { "type": "integer", "description": "A létrehozás ideje (unix időbélyeg, másodperc).", "example": 1761476400 } } }, "CustomerPortal": { "type": "object", "description": "Egy ügyfélkapus belépési adatkészlet (egy magánszemély Ügyfélkapu+/DÁP-belépése), amelyen keresztül az iroda a meghatalmazó adózók adatait letölti. A belépési adatok közül a válasz CSAK a felhasználónevet adja vissza: a jelszót, a 2FA-titkot (hitelesítő kulcsot) és a NAV M2M API kulcsot SOHA. A 2FA-titok létezését a `has_two_factor_authentication_secret` jelzi, a belőle számolt aktuális 6 jegyű kódot a `two_factor_authentication_code` adja.", "properties": { "id": { "type": "integer", "description": "Az ügyfélkapu azonosítója." }, "name": { "type": "string", "maxLength": 255, "description": "Az ügyfélkapu megnevezése az irodában (jellemzően a magánszemély neve, akinek az ügyfélkapujáról van szó).", "example": "Kiss Elemér" }, "login_type": { "type": "string", "nullable": true, "enum": [ "ugyfelkapu_plusz_authenticator", "ugyfelkapu_plusz_email", "dap", "ugyfelkapu", null ], "description": "A belépés módja. null = még nincs összekapcsolva (lásd POST /customer-portal-connections). ugyfelkapu_plusz_authenticator = Ügyfélkapu+ hitelesítő alkalmazással (TOTP-kóddal; a rendszer felügyelet nélkül újra be tud lépni); ugyfelkapu_plusz_email = Ügyfélkapu+ e-mailben kapott kóddal; dap = Digitális Állampolgárság (DÁP) mobilalkalmazás; ugyfelkapu = régi, egyszerű ügyfélkapus belépés (új összekapcsolásnál már nem választható)." }, "username": { "type": "string", "nullable": true, "description": "Az ügyfélkapus felhasználónév. DÁP-belépésnél és összekapcsolás előtt null. (A jelszót a válasz nem tartalmazza.)" }, "active": { "type": "boolean", "description": "Aktív-e az ügyfélkapu. Inaktív ügyfélkapun nincs frissítés, és a hozzá tartozó adózók adatai (üzenetek, bevallások…) nem jelennek meg a listákban." }, "emails": { "type": "array", "items": { "type": "string", "format": "email" }, "description": "Az ügyfélkapuhoz rendelt értesítési e-mail címek. A szabályok „Küldés - Ügyfélkapu\" beállításánál a tárhely-üzenetek ezekre a címekre mennek. Üres tömb, ha nincs megadva.", "example": [ "elemer@kiss.hu" ] }, "note": { "type": "string", "nullable": true, "maxLength": 255, "description": "Belső megjegyzés az ügyfélkapuhoz." }, "has_two_factor_authentication_secret": { "type": "boolean", "description": "true = a rendszer tárolja az Ügyfélkapu+ hitelesítő kulcsát (2FA-titok). Maga a kulcs a válaszban nincs benne; csak a POST /customer-portals/{customerPortalId}/get-two-factor-authentication-secret adja ki, jelszavas megerősítéssel. (Beágyazott ügyfélkapunál, pl. cégkapu `customer_portal` mezőjében mindig false, lásd ott.)" }, "two_factor_authentication_code": { "type": "string", "nullable": true, "pattern": "^\\d{6}$", "description": "A tárolt hitelesítő kulcsból számolt, most érvényes 6 jegyű Ügyfélkapu+ belépési kód (TOTP). null, ha nincs tárolt kulcs.", "example": "123456" }, "two_factor_authentication_code_expires_at": { "type": "integer", "format": "int64", "description": "Unix időbélyeg (mp): eddig érvényes a `two_factor_authentication_code`. Akkor is kitöltött, ha nincs kód.", "example": 1793088030 }, "portals": { "type": "object", "description": "Portálonként a frissítés állapota: tárhely (tárhely-üzenetek), ÜPO (NAV Online Ügyfélportál: bevallások, folyószámla, foglalkoztatottak…), ASP (önkormányzati adóügyek) és M2M (NAV gépi interfész, külön API kulccsal).", "properties": { "tarhely": { "type": "object", "description": "A(z) Tárhely portál frissítésének állapota.", "properties": { "sync_completed_at": { "type": "string", "format": "date-time", "nullable": true, "description": "A legutóbbi befejezett Tárhely-frissítés időpontja; null, ha még nem volt. FIGYELEM: ebben a beágyazott objektumban az időpont ISO 8601 szöveg (UTC), nem unix időbélyeg.", "example": "2026-10-27T08:15:00.000000Z" }, "sync_started_at": { "type": "string", "format": "date-time", "nullable": true, "description": "A jelenleg futó Tárhely-frissítés kezdete; null, ha nem fut. FIGYELEM: ebben a beágyazott objektumban az időpont ISO 8601 szöveg (UTC), nem unix időbélyeg.", "example": "2026-10-27T08:15:00.000000Z" }, "next_sync": { "type": "string", "format": "date-time", "nullable": true, "description": "A következő tervezett Tárhely-frissítés időpontja; null, ha nincs tervezve. Múltbeli érték azt jelenti, hogy a frissítés sorra kerülésre vár (pl. azonnali indítás után). FIGYELEM: ebben a beágyazott objektumban az időpont ISO 8601 szöveg (UTC), nem unix időbélyeg.", "example": "2026-10-27T08:15:00.000000Z" }, "connected": { "type": "boolean", "description": "true = az ügyfélkapu aktív és a rendszer be tud lépni a(z) Tárhely portálra (élő összekapcsolás vagy automatikusan újra összekapcsolható belépés)." }, "instant_run": { "type": "object", "description": "Indítható-e most azonnali frissítés ezen a portálon (POST /customer-portals/{customerPortalId}/instant-portal-run), és ha nem, miért. Csak a teljes ügyfélkapu-válaszban szerepel (beágyazott ügyfélkapunál, pl. a cégkapu `customer_portal` mezőjében hiányzik).", "properties": { "allowed": { "type": "boolean", "description": "true = az azonnali frissítés most elindítható." }, "reason": { "type": "string", "nullable": true, "description": "Ha nem indítható: a felhasználónak szóló magyar indoklás (pl. az ügyfélkapu inaktív, a frissítés épp fut, a csomag nem tartalmazza). Egyébként null." }, "notice": { "type": "string", "nullable": true, "description": "Nem tiltó megjegyzés, pl. hogy a frissítés csak az első sikeres ÜPO-frissítés után fut le. Egyébként null." } } }, "progress": { "type": "object", "nullable": true, "description": "A folyamatban lévő frissítés haladása; null, ha éppen nem fut frissítés. Csak a tárhely/ÜPO/ASP portálnál és csak a teljes ügyfélkapu-válaszban szerepel.", "properties": { "run_id": { "type": "integer", "description": "A futó frissítés azonosítója." }, "done": { "type": "integer", "nullable": true, "description": "Az eddig feldolgozott egységek száma (az első jelentésig null)." }, "total": { "type": "integer", "nullable": true, "description": "A feldolgozandó egységek összesen (az első jelentésig null)." } } } } }, "upo": { "type": "object", "description": "A(z) ÜPO portál frissítésének állapota.", "properties": { "sync_completed_at": { "type": "string", "format": "date-time", "nullable": true, "description": "A legutóbbi befejezett ÜPO-frissítés időpontja; null, ha még nem volt. FIGYELEM: ebben a beágyazott objektumban az időpont ISO 8601 szöveg (UTC), nem unix időbélyeg.", "example": "2026-10-27T08:15:00.000000Z" }, "sync_started_at": { "type": "string", "format": "date-time", "nullable": true, "description": "A jelenleg futó ÜPO-frissítés kezdete; null, ha nem fut. FIGYELEM: ebben a beágyazott objektumban az időpont ISO 8601 szöveg (UTC), nem unix időbélyeg.", "example": "2026-10-27T08:15:00.000000Z" }, "next_sync": { "type": "string", "format": "date-time", "nullable": true, "description": "A következő tervezett ÜPO-frissítés időpontja; null, ha nincs tervezve. Múltbeli érték azt jelenti, hogy a frissítés sorra kerülésre vár (pl. azonnali indítás után). FIGYELEM: ebben a beágyazott objektumban az időpont ISO 8601 szöveg (UTC), nem unix időbélyeg.", "example": "2026-10-27T08:15:00.000000Z" }, "connected": { "type": "boolean", "description": "true = az ügyfélkapu aktív és a rendszer be tud lépni a(z) ÜPO portálra (élő összekapcsolás vagy automatikusan újra összekapcsolható belépés)." }, "instant_run": { "type": "object", "description": "Indítható-e most azonnali frissítés ezen a portálon (POST /customer-portals/{customerPortalId}/instant-portal-run), és ha nem, miért. Csak a teljes ügyfélkapu-válaszban szerepel (beágyazott ügyfélkapunál, pl. a cégkapu `customer_portal` mezőjében hiányzik).", "properties": { "allowed": { "type": "boolean", "description": "true = az azonnali frissítés most elindítható." }, "reason": { "type": "string", "nullable": true, "description": "Ha nem indítható: a felhasználónak szóló magyar indoklás (pl. az ügyfélkapu inaktív, a frissítés épp fut, a csomag nem tartalmazza). Egyébként null." }, "notice": { "type": "string", "nullable": true, "description": "Nem tiltó megjegyzés, pl. hogy a frissítés csak az első sikeres ÜPO-frissítés után fut le. Egyébként null." } } }, "progress": { "type": "object", "nullable": true, "description": "A folyamatban lévő frissítés haladása; null, ha éppen nem fut frissítés. Csak a tárhely/ÜPO/ASP portálnál és csak a teljes ügyfélkapu-válaszban szerepel.", "properties": { "run_id": { "type": "integer", "description": "A futó frissítés azonosítója." }, "done": { "type": "integer", "nullable": true, "description": "Az eddig feldolgozott egységek száma (az első jelentésig null)." }, "total": { "type": "integer", "nullable": true, "description": "A feldolgozandó egységek összesen (az első jelentésig null)." } } } } }, "asp": { "type": "object", "description": "A(z) ASP portál frissítésének állapota.", "properties": { "sync_completed_at": { "type": "string", "format": "date-time", "nullable": true, "description": "A legutóbbi befejezett ASP-frissítés időpontja; null, ha még nem volt. FIGYELEM: ebben a beágyazott objektumban az időpont ISO 8601 szöveg (UTC), nem unix időbélyeg.", "example": "2026-10-27T08:15:00.000000Z" }, "sync_started_at": { "type": "string", "format": "date-time", "nullable": true, "description": "A jelenleg futó ASP-frissítés kezdete; null, ha nem fut. FIGYELEM: ebben a beágyazott objektumban az időpont ISO 8601 szöveg (UTC), nem unix időbélyeg.", "example": "2026-10-27T08:15:00.000000Z" }, "next_sync": { "type": "string", "format": "date-time", "nullable": true, "description": "A következő tervezett ASP-frissítés időpontja; null, ha nincs tervezve. Múltbeli érték azt jelenti, hogy a frissítés sorra kerülésre vár (pl. azonnali indítás után). FIGYELEM: ebben a beágyazott objektumban az időpont ISO 8601 szöveg (UTC), nem unix időbélyeg.", "example": "2026-10-27T08:15:00.000000Z" }, "connected": { "type": "boolean", "description": "true = az ügyfélkapu aktív és a rendszer be tud lépni a(z) ASP portálra (élő összekapcsolás vagy automatikusan újra összekapcsolható belépés)." }, "instant_run": { "type": "object", "description": "Indítható-e most azonnali frissítés ezen a portálon (POST /customer-portals/{customerPortalId}/instant-portal-run), és ha nem, miért. Csak a teljes ügyfélkapu-válaszban szerepel (beágyazott ügyfélkapunál, pl. a cégkapu `customer_portal` mezőjében hiányzik).", "properties": { "allowed": { "type": "boolean", "description": "true = az azonnali frissítés most elindítható." }, "reason": { "type": "string", "nullable": true, "description": "Ha nem indítható: a felhasználónak szóló magyar indoklás (pl. az ügyfélkapu inaktív, a frissítés épp fut, a csomag nem tartalmazza). Egyébként null." }, "notice": { "type": "string", "nullable": true, "description": "Nem tiltó megjegyzés, pl. hogy a frissítés csak az első sikeres ÜPO-frissítés után fut le. Egyébként null." } } }, "progress": { "type": "object", "nullable": true, "description": "A folyamatban lévő frissítés haladása; null, ha éppen nem fut frissítés. Csak a tárhely/ÜPO/ASP portálnál és csak a teljes ügyfélkapu-válaszban szerepel.", "properties": { "run_id": { "type": "integer", "description": "A futó frissítés azonosítója." }, "done": { "type": "integer", "nullable": true, "description": "Az eddig feldolgozott egységek száma (az első jelentésig null)." }, "total": { "type": "integer", "nullable": true, "description": "A feldolgozandó egységek összesen (az első jelentésig null)." } } } } }, "m2m": { "type": "object", "description": "A(z) M2M portál frissítésének állapota.", "properties": { "sync_completed_at": { "type": "string", "format": "date-time", "nullable": true, "description": "A legutóbbi befejezett M2M-frissítés időpontja; null, ha még nem volt. FIGYELEM: ebben a beágyazott objektumban az időpont ISO 8601 szöveg (UTC), nem unix időbélyeg.", "example": "2026-10-27T08:15:00.000000Z" }, "sync_started_at": { "type": "string", "format": "date-time", "nullable": true, "description": "A jelenleg futó M2M-frissítés kezdete; null, ha nem fut. FIGYELEM: ebben a beágyazott objektumban az időpont ISO 8601 szöveg (UTC), nem unix időbélyeg.", "example": "2026-10-27T08:15:00.000000Z" }, "next_sync": { "type": "string", "format": "date-time", "nullable": true, "description": "A következő tervezett M2M-frissítés időpontja; null, ha nincs tervezve. Múltbeli érték azt jelenti, hogy a frissítés sorra kerülésre vár (pl. azonnali indítás után). FIGYELEM: ebben a beágyazott objektumban az időpont ISO 8601 szöveg (UTC), nem unix időbélyeg.", "example": "2026-10-27T08:15:00.000000Z" }, "connected": { "type": "boolean", "description": "true = az M2M-kapcsolat aktív." }, "status": { "type": "string", "nullable": true, "enum": [ "active", "failed", null ], "description": "A NAV M2M-kapcsolat állapota. null = nincs M2M API kulcs megadva; active = működő kapcsolat; failed = a kulcs ismételten hibázott, az M2M-frissítés leállt (új kulcs kell)." }, "instant_run": { "type": "object", "description": "Indítható-e most azonnali frissítés ezen a portálon (POST /customer-portals/{customerPortalId}/instant-portal-run), és ha nem, miért. Csak a teljes ügyfélkapu-válaszban szerepel (beágyazott ügyfélkapunál, pl. a cégkapu `customer_portal` mezőjében hiányzik).", "properties": { "allowed": { "type": "boolean", "description": "true = az azonnali frissítés most elindítható." }, "reason": { "type": "string", "nullable": true, "description": "Ha nem indítható: a felhasználónak szóló magyar indoklás (pl. az ügyfélkapu inaktív, a frissítés épp fut, a csomag nem tartalmazza). Egyébként null." }, "notice": { "type": "string", "nullable": true, "description": "Nem tiltó megjegyzés, pl. hogy a frissítés csak az első sikeres ÜPO-frissítés után fut le. Egyébként null." } } } } } } } } }, "CustomerPortalConnection": { "type": "object", "description": "Egy ügyfélkapu-összekapcsolási folyamat: a rendszer a megadott belépési adatokkal belép a KAÜ-n keresztül, és siker esetén az adatokat az ügyfélkapura menti. A válasz a megadott felhasználónevet, jelszót és hitelesítő kulcsot NEM tartalmazza. Az állapotot a GET /customer-portal-connections/{customerPortalConnectionId} lekérdezésével lehet követni.", "properties": { "id": { "type": "integer", "description": "Az összekapcsolási folyamat azonosítója." }, "status": { "type": "string", "enum": [ "pending", "in_progress", "confirmation", "completed", "failed" ], "description": "pending = sorra kerülésre vár; in_progress = a belépés folyamatban; confirmation = megerősítésre vár (Ügyfélkapu+ e-mailes kódnál a kapott kódot a set-confirmation-code végponton kell megadni; DÁP-nál a `dap_qr_code`-ot kell a DÁP alkalmazással beolvasni); completed = sikeres, az ügyfélkapu belépési adatai frissültek; failed = sikertelen, az okot az `error` adja." }, "login_type": { "type": "string", "enum": [ "ugyfelkapu_plusz_authenticator", "ugyfelkapu_plusz_email", "dap" ], "description": "A belépés módja (lásd CustomerPortal.login_type)." }, "confirmation_code_start": { "type": "string", "nullable": true, "description": "Ügyfélkapu+ e-mailes kódnál: a KAÜ által kiírt kód-előtag, amely az e-mailben kapott 6 számjegy előtt áll (a felület „ELŐTAG - ______\" alakban mutatja). Egyébként null.", "example": "ABC" }, "confirmation_code": { "type": "string", "nullable": true, "description": "A felhasználó által megadott 6 jegyű megerősítő kód (set-confirmation-code), ha volt.", "example": "123456" }, "dap_qr_code": { "type": "string", "nullable": true, "description": "DÁP-belépésnél: a QR-kód tartalma (szöveg), amelyet a felületnek QR-kódként kell megjelenítenie a DÁP alkalmazással való beolvasáshoz. Egyébként null." }, "error": { "type": "string", "nullable": true, "description": "Sikertelen összekapcsolásnál a hiba magyar leírása (pl. „Nem megfelelő felhasználónév vagy jelszó.\", „Összekapcsolási folyamat megszakítva.\"). Egyébként null." } } }, "Mailbox": { "type": "object", "description": "Cégkapu / tárhely-postafiók, amelyhez az ügyfélkapu hozzáfér (a magánszemély saját tárhelye vagy egy cég cégkapuja). A rendszer az ügyfélkapuk frissítésekor veszi fel; az API-n létrehozni vagy törölni nem lehet, csak az aktív állapota és az értesítési címei módosíthatók.", "properties": { "id": { "type": "integer", "description": "A cégkapu azonosítója." }, "customer_portal_id": { "type": "integer", "description": "Az ügyfélkapu azonosítója, amelyen keresztül a cégkapu elérhető." }, "name": { "type": "string", "description": "A cégkapu (postafiók) neve, ahogy a tárhely mutatja.", "example": "Alfa Kft." }, "tax_number": { "type": "integer", "nullable": true, "description": "A cégkapuhoz tartozó cég adószámának első 8 számjegye (törzsszám), számként; magánszemély tárhelyénél null.", "example": 12345678 }, "active": { "type": "boolean", "description": "Aktív-e a cégkapu az irodában." }, "emails": { "type": "array", "items": { "type": "string", "format": "email" }, "description": "A cégkapuhoz rendelt értesítési e-mail címek. A szabályok „Küldés - Cégkapu\" beállításánál a cégkapuba érkezett tárhely-üzenetek ezekre a címekre mennek. Üres tömb, ha nincs megadva.", "example": [ "iroda@alfa.hu" ] }, "customer_portal": { "allOf": [ { "$ref": "#/components/schemas/CustomerPortal" } ], "description": "A cégkapuhoz tartozó ügyfélkapu, csökkentett tartalommal: csak az `id`, `name`, `login_type`, `username`, `active`, `emails`, `note` mező megbízható. A `has_two_factor_authentication_secret` itt mindig false, a `two_factor_authentication_code` null, a `portals.*` dátumai null-ok és a `connected` false, az `instant_run`/`progress` hiányzik — az ügyfélkapu valódi állapotát a GET /customer-portals/{customerPortalId} adja." } } }, "Action": { "type": "object", "description": "Az iroda beállítása egy tárhely-szabályra (dokumentumtípusra): az ilyen típusú új tárhely-üzenet milyen státuszt kap, letöltse-e a rendszer, és kinek küldje ki e-mailben. Minden szabály szerepel, az iroda által nem módosított is (alapbeállítással). Az `id` a SZABÁLY azonosítója, nem egy irodai rekordé.", "properties": { "id": { "type": "integer", "description": "A szabály azonosítója; ezzel kell hívni a GET/PUT /actions/{actionId} végpontot." }, "document_id": { "type": "string", "description": "A szabály stabil szöveges kulcsa. Ezt kell megadni a POST /messages/search `valid_document` szűrőjében; az üzenet `valid_document` mezője is ezt adja.", "example": "ertesites_hibatlan_bevallas" }, "document": { "type": "string", "description": "A szabály (dokumentumtípus) megnevezése.", "example": "NAV - Értesítés hibátlan bevallásról" }, "note": { "type": "string", "nullable": true, "description": "A szabályhoz tartozó magyarázat (mit jelent az ilyen üzenet)." }, "legally_binding_days": { "type": "integer", "nullable": true, "description": "Ha az ilyen dokumentum a kézbesítéssel (megnyitással) joghatást vált ki: hány nap múlva válik jogerőssé / véglegessé a megnyitástól. null = nincs ilyen határidő.", "example": 15 }, "message_status_id": { "type": "integer", "description": "Az ilyen típusú új üzenet státusza (MessageStatus azonosító). Alapbeállításban az iroda lezárt státusza." }, "skip": { "type": "boolean", "description": "„Nem kell\": true = az ilyen típusú üzenet nem jelenik meg az üzenetlistában, és semmilyen letöltés/kiküldés nem történik vele." }, "download_method": { "type": "string", "nullable": true, "enum": [ "download", "put_in_permanent_storage", null ], "description": "Mi történjen az ilyen üzenet fájljával. null = semmi (a rendszer nem tölti le); download = a rendszer letölti a fájlt (az üzenet ezzel a tárhelyen olvasottá válik); put_in_permanent_storage = a rendszer letölti és a tárhelyen tartós tárba helyezi." }, "send_method": { "type": "string", "nullable": true, "enum": [ "send_now", "send_later", null ], "description": "E-mailes kiküldés módja. null = nincs kiküldés; send_now = azonnal, amint a fájl letöltődött (csak olyan előfizetési csomagban állítható, amely engedi az azonnali küldést); send_later = később, összevont levélben. A címzetteket a send_to_* mezők adják; a kiküldéshez letöltött fájl kell." }, "send_to_customer_portal": { "type": "boolean", "description": "Az ilyen üzenet menjen-e az ügyfélkapu értesítési címeire (CustomerPortal.emails)." }, "send_to_trustee": { "type": "boolean", "description": "Menjen-e az adózó e-mail címeire." }, "send_to_trustee_accountants": { "type": "boolean", "description": "Menjen-e az adózó könyvelőinek címeire." }, "send_to_trustee_payroll_accountants": { "type": "boolean", "description": "Menjen-e az adózó bérszámfejtőinek címeire." }, "send_to_trustee_tax_advisors": { "type": "boolean", "description": "Menjen-e az adózó adótanácsadóinak címeire." }, "send_to_mailboxes": { "type": "boolean", "description": "Menjen-e a cégkapu értesítési címeire (Mailbox.emails)." }, "email_note": { "type": "string", "nullable": true, "maxLength": 65535, "description": "Megjegyzés, amely a kiküldött e-mailben az üzenet mellett szerepel." }, "color": { "type": "string", "nullable": true, "pattern": "^#[0-9A-F]{6}$", "description": "Kiemelő szín az üzenetlistában az ilyen típusú üzeneteknél (#RRGGBB), vagy null.", "example": "#FF9999" }, "created_at": { "type": "integer", "format": "int64", "nullable": true, "description": "Unix időbélyeg: a szabály felvételének ideje a rendszerbe (nem az irodai beállításé).", "example": 1793088000 }, "updated_at": { "type": "integer", "format": "int64", "nullable": true, "description": "Unix időbélyeg: az iroda utolsó módosítása ezen a szabályon; null, ha az iroda nem módosította (alapbeállítás).", "example": 1793088000 }, "message_status": { "allOf": [ { "$ref": "#/components/schemas/MessageStatus" } ], "nullable": true, "description": "A `message_status_id` státusz adatai." } } }, "MessageStatus": { "type": "object", "description": "Az iroda által használt tárhely-üzenet státusz (feldolgozási állapot, pl. „Nyitott\", „Folyamatban\", „Lezárt\"). Minden irodának pontosan egy lezárt státusza van, ezt nem lehet törölni.", "properties": { "id": { "type": "integer", "description": "A státusz azonosítója." }, "name": { "type": "string", "maxLength": 255, "description": "A státusz neve.", "example": "Folyamatban" }, "color": { "type": "string", "pattern": "^#[0-9A-F]{6}$", "description": "A státusz színe #RRGGBB alakban (nagybetűs hexa).", "example": "#FFFF99" }, "closed": { "type": "boolean", "description": "true = ez az iroda lezárt („kész\") státusza. Ez az új szabályok alapértelmezett státusza, és ide kerülnek egy törölt státusz üzenetei és szabályai." } } }, "Message": { "type": "object", "description": "Egy tárhely-üzenet (a NAV vagy más hivatal által a tárhelyre / cégkapuba küldött dokumentum), amelyet a rendszer az ügyfélkapun keresztül letöltött és egy adózóhoz rendelt.", "properties": { "id": { "type": "integer", "description": "Az üzenet azonosítója." }, "customer_portal_id": { "type": "integer", "description": "Az ügyfélkapu azonosítója, amelyen keresztül az üzenet érkezett." }, "message_status_id": { "type": "integer", "description": "Az üzenet státusza (MessageStatus azonosító)." }, "sender_name": { "type": "string", "description": "A feladó hivatal teljes neve.", "example": "Nemzeti Adó- és Vámhivatal" }, "sender_short_name": { "type": "string", "description": "A feladó rövid neve.", "example": "NAV" }, "addressee_name": { "type": "string", "description": "A címzett (tárhely-tulajdonos) neve." }, "addressee_short_name": { "type": "string", "description": "A címzett rövid neve." }, "document_type": { "type": "string", "nullable": true, "description": "A dokumentum típusa, ahogy a tárhely mutatja.", "example": "Elfogadó nyugta" }, "document_description": { "type": "string", "description": "A dokumentum tárhelyen látható leírása (tárgya)." }, "note": { "type": "string", "nullable": true, "maxLength": 255, "description": "A tárhelyen az üzenethez tartozó megjegyzés." }, "filename": { "type": "string", "description": "A csatolt fájl neve a tárhelyen.", "example": "nyugta_2026.pdf" }, "file_size": { "type": "integer", "description": "A fájl mérete bájtban.", "example": 48213 }, "downloaded_file": { "type": "string", "format": "uri", "nullable": true, "description": "A rendszer által letöltött fájl URL-je; null, ha a rendszer még nem töltötte le." }, "downloaded_at": { "type": "integer", "format": "int64", "nullable": true, "description": "Unix időbélyeg: mikor nyitották meg / töltötték le először az üzenetet a tárhelyen (a rendszer vagy a felhasználó). Joghatással járó dokumentumnál ettől számít a határidő. null = még olvasatlan.", "example": 1793088000 }, "first_download_performer": { "type": "string", "nullable": true, "enum": [ "kapuseged", "user", null ], "description": "Ki nyitotta meg először: kapuseged = a rendszer töltötte le (szabály vagy kérés alapján); user = valaki közvetlenül a tárhelyen nyitotta meg. null = még olvasatlan." }, "arrived_at": { "type": "integer", "format": "int64", "description": "Unix időbélyeg: az üzenet tárhelyre érkezésének ideje.", "example": 1793088000 }, "download_method": { "type": "string", "nullable": true, "enum": [ "download", "put_in_permanent_storage", null ], "description": "Függő letöltési kérés: download = a rendszer letölti a fájlt; put_in_permanent_storage = letölti és tartós tárba helyezi. null = nincs függő kérés (a letöltés után is null lesz)." }, "user_note": { "type": "string", "nullable": true, "maxLength": 255, "description": "Az iroda saját megjegyzése az üzenethez." }, "valid_document": { "type": "string", "nullable": true, "description": "Az üzenetre illeszkedő tárhely-szabály kulcsa (a GET /actions lista `document_id` mezője). A szabály nélküli üzeneteknél is kitöltött (a „szabály nélküli\" gyűjtőszabály kulcsa).", "example": "nav_elfogado_nyugta" }, "valid_document_label": { "type": "string", "nullable": true, "description": "Az illeszkedő szabály megnevezése (a GET /actions lista `document` mezője)." }, "read": { "type": "boolean", "description": "„Átnézve\" a lekérdező felhasználó szerint (felhasználónként külön): true, ha az üzenet a felhasználó „mindet átnéztem\" időpontja (User.messages_read_at) előtt került a rendszerbe, vagy a felhasználó egyesével átnézettnek jelölte. Nem azonos a tárhelyen való megnyitással (az a `downloaded_at`)." }, "color": { "type": "string", "nullable": true, "pattern": "^#[0-9A-F]{6}$", "description": "Az illeszkedő szabály irodai kiemelő színe (Action.color), vagy null.", "example": "#FF9999" }, "legally_binding_deadline": { "type": "string", "format": "date", "nullable": true, "description": "Joghatással járó dokumentumnál a jogerő / véglegesség napja (megnyitás napja + Action.legally_binding_days), ÉÉÉÉ-HH-NN. null, ha a szabályhoz nincs ilyen határidő, vagy az üzenet még olvasatlan.", "example": "2026-11-11" }, "created_at": { "type": "integer", "format": "int64", "description": "Unix időbélyeg: mikor került az üzenet a rendszerbe.", "example": 1793088000 }, "updated_at": { "type": "integer", "format": "int64", "nullable": true, "description": "Unix időbélyeg: utolsó módosítás.", "example": 1793088000 }, "message_status": { "allOf": [ { "$ref": "#/components/schemas/MessageStatus" } ], "description": "Az üzenet státusza." }, "trustee": { "allOf": [ { "$ref": "#/components/schemas/Trustee" } ], "description": "Az adózó, akihez az üzenet tartozik (a rendszer a fájlnévben / leírásban szereplő adószám vagy adóazonosító jel alapján rendeli hozzá, ennek hiányában a cégkapu adózójához). Kapcsolatai (customer_portal, roles…) itt nincsenek betöltve." }, "declaration": { "allOf": [ { "$ref": "#/components/schemas/Declaration" } ], "nullable": true, "description": "A bevallás, amelyhez az üzenet kapcsolódik (bevallásról szóló értesítésnél / nyugtánál, a dokumentumban szereplő vonalkód alapján); egyébként null." }, "sent_mails": { "type": "array", "items": { "$ref": "#/components/schemas/SentMail" }, "description": "Az üzenetet továbbító, már elküldött e-mailek." } } }, "SentMail": { "type": "object", "description": "Az iroda nevében a rendszer által kiküldött e-mail (egy címzettnek egy rekord).", "properties": { "id": { "type": "integer", "description": "Az elküldött e-mail azonosítója." }, "type": { "type": "string", "enum": [ "message", "summary", "trustee_debt_notification", "trustee_roles", "tax_account_query_completed", "job_completed", "new_trustees", "customer_portals_disconnected", "payment_obligation" ], "description": "A levél fajtája. message = tárhely-üzenet(ek) továbbítása; summary = összesítő e-mail; trustee_debt_notification = adózónak szóló tartozás-értesítő; trustee_roles = törzsadatok kiküldése; tax_account_query_completed = adófolyószámla-lekérdezés elkészült; job_completed = egy kért művelet (pl. tömeges export) elkészült; new_trustees = új adózók értesítő; customer_portals_disconnected = ügyfélkapu-összekapcsolás megszakadt; payment_obligation = fizetési kötelezettség értesítő." }, "type_label": { "type": "string", "description": "A `type` magyar megnevezése.", "example": "Tárhely üzenetek" }, "email": { "type": "string", "format": "email", "description": "A címzett e-mail címe." }, "attachment": { "type": "boolean", "description": "Volt-e melléklet a levélben." }, "status": { "type": "string", "enum": [ "sent", "delivered", "opened", "failed" ], "description": "A kézbesítés állapota: sent = elküldve; delivered = kézbesítve a címzett levelezőszerverére; opened = a címzett megnyitotta; failed = sikertelen (pl. visszapattant)." }, "created_at": { "type": "integer", "format": "int64", "description": "Unix időbélyeg: a küldés ideje.", "example": 1793088000 }, "updated_at": { "type": "integer", "format": "int64", "nullable": true, "description": "Unix időbélyeg: az állapot utolsó változása.", "example": 1793088000 } } }, "Declaration": { "type": "object", "description": "Az adózó nevében a NAV-hoz beküldött bevallás (vagy igazolás-kérés, nyomtatvány), ahogy a NAV nyilvántartja.", "required": [ "id", "barcode", "interval_start", "interval_end", "tax_report_type", "function", "status", "file_pdf", "file_xkr", "first_message_arrived_at", "error_message_arrived_at", "downloadable" ], "properties": { "id": { "type": "integer", "description": "A bevallás azonosítója a KapuSegédben." }, "barcode": { "type": "integer", "description": "A bevallás 10 jegyű NAV-vonalkódja (iktatószáma).", "minimum": 1000000000, "maximum": 9999999999, "example": 2512345678 }, "interval_start": { "type": "string", "description": "A bevallási időszak első napja (ÉÉÉÉ-HH-NN).", "nullable": true, "format": "date", "example": "2026-01-01" }, "interval_end": { "type": "string", "description": "A bevallási időszak utolsó napja (ÉÉÉÉ-HH-NN).", "nullable": true, "format": "date", "example": "2026-03-31" }, "tax_report_type": { "type": "string", "description": "A nyomtatvány típusa (pl. `2608`, `2665`, `2653`).", "nullable": true, "example": "2608" }, "function": { "type": "string", "description": "A bevallás funkciója: `ALAPBEVALLAS` alapbevallás, `HELYESBITO_BEVALLAS` helyesbítő, `JAVITO_BEVALLAS` javító bevallás, `ONELLENORZES` önellenőrzés. `null`, ha még nem ismert.", "nullable": true, "enum": [ null, "ALAPBEVALLAS", "HELYESBITO_BEVALLAS", "JAVITO_BEVALLAS", "ONELLENORZES" ] }, "status": { "type": "string", "description": "A bevallás NAV szerinti állapota: `Feldolgozásra vár` / `Feldolgozás alatt` (a NAV még dolgozik rajta), `Feldolgozott`, `Kiértesítve` (a NAV értesítést küldött, pl. hibás adattartalom miatt; általában teendő van), `LEZÁRT/NAPLÓZOTT`, `ELINTÉZETT`, `NYITOTT` (további NAV-állapotok), `Törölt` (a NAV nyilvántartásában törölt, nem számít beadottnak). `null`: a bevallás a tárhely-üzenet alapján már megvan, de állapot még nem érkezett hozzá.", "nullable": true, "enum": [ null, "ELINTÉZETT", "Feldolgozásra vár", "Feldolgozás alatt", "Feldolgozott", "Kiértesítve", "LEZÁRT/NAPLÓZOTT", "Törölt", "NYITOTT" ] }, "file_pdf": { "type": "string", "description": "A bevallás PDF-fájljának teljes URL-je; `null`, ha még nincs letöltve.", "nullable": true, "format": "uri" }, "file_xkr": { "type": "string", "description": "A bevallás XKR-fájljának (ÁNYK-formátum) teljes URL-je; `null`, ha még nincs letöltve, vagy a NAV az adott nyomtatványhoz nem ad XKR-t (pl. SZJA-bevallás).", "nullable": true, "format": "uri" }, "first_message_arrived_at": { "type": "integer", "description": "A befogadás ideje: a bevalláshoz kapcsolt legkorábbi tárhely-üzenet (jellemzően az elfogadó nyugta) érkezése, Unix időbélyeg (másodperc). `null`, ha nincs kapcsolt üzenet.", "nullable": true, "example": 1767258000 }, "error_message_arrived_at": { "type": "integer", "description": "A NAV „Értesítés - Intézkedés” üzenetének érkezése a bevallásról, Unix időbélyeg (másodperc). `null`, ha ilyen értesítés nem jött.", "nullable": true }, "downloadable": { "type": "boolean", "description": "`true`, ha a bevallás PDF vagy (ahol a nyomtatványnál van) XKR fájlja még hiányzik, és a rendszer még megpróbálja letölteni; `false`, ha minden fájl megvan, vagy további letöltés már nem várható." }, "trustee": { "allOf": [ { "$ref": "#/components/schemas/Trustee" } ], "description": "Az adózó, akinek a nevében a bevallás készült. Csak a bevallás saját végpontjain (megtekintés, szűrés) szerepel; beágyazva (EFO, Adónaptár) hiányzik." }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/Message" }, "description": "A bevalláshoz kapcsolt tárhely-üzenetek (elfogadó nyugta, értesítések). Csak a bevallás saját végpontjain (megtekintés, szűrés) szerepel; beágyazva hiányzik." } } }, "Trustee": { "type": "object", "description": "Adózó (meghatalmazó ügyfél): egy természetes személy, egyéni vállalkozó vagy cég, akit az iroda egy ügyfélkapun (`CustomerPortal`) keresztül képvisel. A rendszer az ügyfélkapukból automatikusan veszi fel. Ugyanaz a valós adózó több ügyfélkapu alatt is szerepelhet, ilyenkor külön rekordként. A beágyazott kapcsolatok egy része a felhasználó jogosultságától és az iroda csomagjától függ; ami nem jár, az a kulcs nélkül marad ki a válaszból.", "properties": { "id": { "type": "integer", "description": "Az adózó azonosítója." }, "customer_portal_id": { "type": "integer", "description": "Az ügyfélkapu azonosítója (`CustomerPortal.id`), amelyen keresztül az iroda az adózót képviseli." }, "name": { "type": "string", "nullable": true, "example": "Alfa Kft.", "description": "Az adózó neve rövidített cégformával (pl. „Alfa Kft.”, „Béta Bt. \"v.a.\"”). A NAV-tól kapott teljes név az `official_name`. `null`, ha a név még nem ismert." }, "official_name": { "type": "string", "nullable": true, "example": "Alfa Korlátolt Felelősségű Társaság", "description": "Az adózó teljes, hivatalos neve, ahogy a NAV-tól érkezett." }, "active": { "type": "boolean", "description": "Aktív-e az adózó. Csak aktív adózóval dolgozik a rendszer (üzenetek, bevallások, egyenlegek, hátralék-értesítés), és az előfizetés díja az aktív adózók után számít." }, "tax_number": { "type": "integer", "nullable": true, "example": 12345678242, "description": "Adószám kötőjelek nélkül: 11 jegyű (a 8 jegyű törzsszám + áfakód + területi kód), vagy ha csak a törzsszám ismert, 8 jegyű. Magánszemélynél jellemzően `null`." }, "tax_identification_number": { "type": "integer", "nullable": true, "example": 8123456789, "description": "Adóazonosító jel (10 jegyű, természetes személyeknél, egyéni vállalkozóknál). Cégnél `null`." }, "emails": { "type": "array", "items": { "type": "string", "format": "email" }, "description": "Az adózó saját értesítési címei („Üzenet küldési e-mail”): ide megy a hátralék-értesítő, és a tárhely-szabályokban az „Adózó” címzett is ezt jelenti. Mindig tömb (lehet üres)." }, "accountant_emails": { "type": "array", "items": { "type": "string", "format": "email" }, "description": "A könyvelő címei (a szabályokban a „Könyvelő” címzett). Mindig tömb." }, "payroll_accountant_emails": { "type": "array", "items": { "type": "string", "format": "email" }, "description": "A bérszámfejtő címei (a szabályokban a „Bérszámfejtő” címzett). Mindig tömb." }, "tax_advisor_emails": { "type": "array", "items": { "type": "string", "format": "email" }, "description": "Az adótanácsadó címei (a szabályokban az „Adótanácsadó” címzett). Mindig tömb." }, "taxation_type": { "type": "string", "nullable": true, "enum": [ "VSZJA", "Átalányadó", "Új KATA", "Társasági adó", "KIVA" ], "description": "Az adózás módja a NAV-törzsadat alapján: `VSZJA` (vállalkozói személyi jövedelemadó; ez az alapérték, ha a törzsadatból más nem olvasható ki), `Átalányadó` (egyéni vállalkozói átalányadó), `Új KATA` (kisadózó vállalkozások tételes adója), `Társasági adó`, `KIVA` (kisvállalati adó). `null`, ha nincs cég-törzsadat." }, "vat_period": { "type": "string", "nullable": true, "enum": [ "Havi", "Negyedéves", "Éves" ], "description": "Az áfabevallás gyakorisága a NAV-törzsadat alapján: `Havi`, `Negyedéves` vagy `Éves`. `null`, ha nem ismert (pl. alanyi adómentes)." }, "debt_notification": { "type": "boolean", "description": "Hátralék-értesítés bekapcsolva: az adózó automatikus levelet kap a saját címeire (`emails`), ha NAV-, önkormányzati vagy végrehajtható köztartozása van (a csomagban elérhető adatkörök szerint)." }, "asp_represented_tax_number": { "type": "integer", "nullable": true, "example": 12345678242, "description": "ASP – képviselő cég adószáma (11 jegy, kötőjel nélkül): ha az adózót az önkormányzati (ASP) rendszerben egy cég képviseli. `null`, ha nincs megadva." }, "missing_declaration_sync_completed_at": { "type": "integer", "nullable": true, "example": 1793097780, "description": "Mikor frissítette utoljára a rendszer az adózó hiányzó bevallásait (unix időbélyeg, másodperc). `null`, ha még soha." }, "simplified_employee_sync_completed_at": { "type": "integer", "nullable": true, "example": 1793097780, "description": "Mikor frissítette utoljára a rendszer az adózó egyszerűsített foglalkoztatottjait (EFO) (unix időbélyeg, másodperc). `null`, ha még soha." }, "employee_sync_completed_at": { "type": "integer", "nullable": true, "example": 1793097780, "description": "Mikor frissítette utoljára a rendszer az adózó biztosítottjait (unix időbélyeg, másodperc). `null`, ha még soha." }, "role_sync_completed_at": { "type": "integer", "nullable": true, "example": 1793097780, "description": "Mikor frissítette utoljára a rendszer az adózó törzsadatait (unix időbélyeg, másodperc). `null`, ha még soha." }, "tax_type_sync_completed_at": { "type": "integer", "nullable": true, "example": 1793097780, "description": "Mikor frissítette utoljára a rendszer az adózó NAV-adófolyószámláját (unix időbélyeg, másodperc). `null`, ha még soha." }, "public_debt_sync_completed_at": { "type": "integer", "nullable": true, "example": 1793097780, "description": "Mikor frissítette utoljára a rendszer az adózó végrehajtható köztartozásait (unix időbélyeg, másodperc). `null`, ha még soha." }, "payment_obligation_sync_completed_at": { "type": "integer", "nullable": true, "example": 1793097780, "description": "Mikor frissítette utoljára a rendszer az adózó fizetési kötelezettségeit (unix időbélyeg, másodperc). `null`, ha még soha." }, "asp_sync_completed_at": { "type": "integer", "nullable": true, "example": 1793097780, "description": "Mikor frissítette utoljára a rendszer az adózó önkormányzati (ASP) adószámláit (unix időbélyeg, másodperc). `null`, ha még soha." }, "note": { "type": "string", "nullable": true, "maxLength": 255, "description": "Az iroda belső megjegyzése az adózóhoz." }, "upo_available": { "type": "boolean", "description": "Szerepel-e az adózó az ügyfélkapu meghatalmazói között a NAV Online Ügyfélportálon (ÜPO). `false`, ha már nem (pl. megszűnt a meghatalmazás)." }, "tax_file_pdf": { "type": "string", "format": "uri", "nullable": true, "description": "A legutóbbi NAV-adófolyószámla PDF-fájljának letöltési URL-je. `null`, ha nincs." }, "tax_file_xlsx": { "type": "string", "format": "uri", "nullable": true, "description": "A legutóbbi NAV-adófolyószámla XLSX-fájljának letöltési URL-je. `null`, ha nincs." }, "tax_file_xml": { "type": "string", "format": "uri", "nullable": true, "description": "A legutóbbi NAV-adófolyószámla XML-fájljának letöltési URL-je. `null`, ha nincs." }, "has_relations": { "type": "object", "description": "Melyik adatkörben van adat az adózónál (a felület ezek alapján mutatja az adatlap füleit). Független a csomagtól.", "properties": { "simplified_employees": { "type": "boolean", "description": "Van-e egyszerűsített foglalkoztatottja (EFO)." }, "employees": { "type": "boolean", "description": "Van-e biztosítottja." }, "roles": { "type": "boolean", "description": "Van-e NAV-törzsadata." }, "public_debts": { "type": "boolean", "description": "Van-e végrehajtható köztartozása." }, "trustee_municipalities": { "type": "boolean", "description": "Van-e letöltött önkormányzati (ASP) adószámlája (bármely évre)." }, "tax_types": { "type": "boolean", "description": "Van-e letöltött NAV-adófolyószámla fájlja (PDF, XLSX vagy XML)." } } }, "syncing": { "type": "boolean", "description": "Frissíti-e a rendszer jelenleg az adózó adatait: az adózó aktív, és az ügyfélkapuja aktív és csatlakoztatott. `false` esetén a felület „Nem szinkronizált adózó” jelzést mutat." }, "sum_debt": { "type": "integer", "nullable": true, "example": 125000, "description": "A NAV-adófolyószámla egyenlege összesen (a `tax_types` összege). Pozitív érték tartozás, negatív túlfizetés (forintban). `null`, ha nincs letöltött adófolyószámla; 0, ha van fájl, de nincs adónem." }, "sum_municipality_debt": { "type": "integer", "nullable": true, "description": "A tárgyévi önkormányzati (ASP) adószámlák egyenlege összesen. Pozitív érték tartozás, negatív túlfizetés (forintban). `null`, ha nincs tárgyévi adószámla. Csak Alap és Prémium csomagban szerepel a válaszban." }, "sum_public_debt": { "type": "integer", "nullable": true, "description": "A végrehajtható köztartozások összege forintban. `null`, ha nincs köztartozás. Csak Prémium csomagban szerepel a válaszban." }, "relationship_week_hours": { "type": "integer", "nullable": true, "description": "Az adózó heti munkaóráinak összege a saját foglalkoztatóinál, munkaviszony jellegű biztosítási jogviszonyokban (jogviszonykód 1101, 1102, 1103, 1105, 1112), pl. a főállás vizsgálatához. `null`, ha nincs ilyen jogviszony. Csak Alap és Prémium csomagban szerepel a válaszban." }, "unclosed_messages_count": { "type": "integer", "description": "Az adózóhoz tartozó, megjelenített és még le nem zárt tárhely-üzenetek száma." }, "customer_portal": { "allOf": [ { "$ref": "#/components/schemas/CustomerPortal" } ], "description": "Az ügyfélkapu, amelyen keresztül az adózót képviseli az iroda, csak a nyilvános alapmezőkkel (azonosító, név, belépési mód, felhasználónév, aktív, címek, megjegyzés). Ebben a beágyazásban a 2FA-titok jelzője mindig `false`, a kód `null`, és a `portals` szinkronállapotai nincsenek kitöltve; a pontos ügyfélkapu-adatokhoz a `GET /customer-portals/{customerPortalId}` való. Jelszót és 2FA-titkot nem ad vissza." }, "tax_types": { "type": "array", "items": { "$ref": "#/components/schemas/TrusteeTaxType" }, "description": "A NAV-adófolyószámla adónemenként (a legutóbbi letöltés szerint). Üres tömb, ha nincs adat." }, "roles": { "type": "array", "items": { "$ref": "#/components/schemas/TrusteeRole" }, "description": "A NAV-törzsadatok (cég és/vagy magánszemély lap, a cég elöl). Csak akkor szerepel, ha a felhasználónak van törzsadat-olvasási joga (Alap és Prémium csomag)." }, "trustee_municipalities": { "type": "array", "items": { "$ref": "#/components/schemas/TrusteeMunicipality" }, "description": "Az adózó önkormányzatai a letöltött önkormányzati (ASP) adószámlákkal. Csak Prémium csomagban szerepel." }, "public_debts": { "type": "array", "items": { "$ref": "#/components/schemas/TrusteePublicDebt" }, "description": "A végrehajtható köztartozások jogcímenként. Csak Prémium csomagban szerepel." } } }, "MissingDeclaration": { "type": "object", "description": "A NAV Online Ügyfélportál (ÜPO) szerint hiányzó bevallás egy adózónál.", "required": [ "name", "type", "period", "due_date", "formatted_period" ], "properties": { "name": { "type": "string", "description": "A bevallás megnevezése a NAV szerint.", "example": "Bevallás a szociális hozzájárulási adóról, a járulékokról…" }, "type": { "type": "string", "description": "A nyomtatvány típusa (pl. `2608`, `2658`).", "example": "2608" }, "period": { "type": "string", "description": "A bevallási időszak a NAV kódolásában: 2 jegy = év (`26` = 2026), 3 jegy = év + negyedév (`263` = 2026. 3. negyedév), 4 jegy = év + hónap (`2609` = 2026. szeptember). Más formátum is előfordulhat.", "example": "2609" }, "formatted_period": { "type": "string", "description": "Az időszak olvasható alakban, pl. „2026. évi”, „2026. 3. negyedév”, „2026. 09. hónap”; értelmezhetetlen kódnál a nyers `period`.", "example": "2026. 09. hónap" }, "due_date": { "type": "string", "description": "A bevallás esedékessége (ÉÉÉÉ-HH-NN).", "format": "date", "example": "2026-10-12" }, "trustee": { "allOf": [ { "$ref": "#/components/schemas/Trustee" } ], "description": "Az adózó, akinél a bevallás hiányzik." } } }, "SimplifiedEmployee": { "type": "object", "description": "Egyszerűsített foglalkoztatási (EFO) bejelentés: az adózó mint foglalkoztató által alkalmi munkára, idénymunkára vagy filmipari statisztaként bejelentett munkavállaló, a NAV nyilvántartása szerint.", "required": [ "id", "trustee_id", "name", "tax_identification_number", "social_security_number", "notification_type", "employment_type", "employment_start", "employment_end", "data_sheet_id", "data_sheet_status", "data_sheet_type", "data_sheet_arrived_at", "supplement_sheet_id" ], "properties": { "id": { "type": "integer", "description": "Az EFO-bejelentés azonosítója." }, "trustee_id": { "type": "integer", "description": "A foglalkoztató adózó azonosítója." }, "name": { "type": "string", "description": "A munkavállaló neve." }, "tax_identification_number": { "type": "integer", "description": "A munkavállaló adóazonosító jele (10 számjegy).", "example": 8449251001 }, "social_security_number": { "type": "string", "description": "A munkavállaló TAJ szám (9 számjegy, elválasztó nélkül).", "nullable": true, "example": "123456789" }, "notification_type": { "type": "string", "description": "A bejelentés típusa: `Új` új bejelentés; `null`, ha a NAV nem adta meg.", "nullable": true, "enum": [ null, "Új" ] }, "employment_type": { "type": "string", "description": "A foglalkoztatás jellege.", "enum": [ "alkalmi munka", "mezőgazdasági idénymunka", "turisztikai idénymunka", "filmipari statiszta" ] }, "employment_start": { "type": "string", "description": "A foglalkoztatás kezdő napja (ÉÉÉÉ-HH-NN).", "format": "date" }, "employment_end": { "type": "string", "description": "A foglalkoztatás záró napja (ÉÉÉÉ-HH-NN).", "format": "date" }, "data_sheet_id": { "type": "integer", "description": "A bejelentő adatlap NAV-iktatószáma (vonalkódja); ezzel párosul a `declaration`.", "example": 2612345678 }, "data_sheet_status": { "type": "string", "description": "Az adatlap NAV szerinti feldolgozási állapota: `FELDOLGOZOTT` feldolgozott, `HIBAS` hibás.", "enum": [ "FELDOLGOZOTT", "HIBAS" ] }, "data_sheet_type": { "type": "string", "description": "A bejelentő nyomtatvány típusa, évszám-előtaggal (pl. `25T1042E`).", "example": "25T1042E" }, "data_sheet_arrived_at": { "type": "string", "description": "A bejelentés napja (ÉÉÉÉ-HH-NN).", "format": "date" }, "supplement_sheet_id": { "type": "integer", "description": "A bejelentés sorszáma az adatlapon belül (több munkavállalót tartalmazó adatlapnál).", "nullable": true, "minimum": 1, "maximum": 65535 }, "trustee": { "allOf": [ { "$ref": "#/components/schemas/Trustee" } ], "description": "A foglalkoztató adózó." }, "declaration": { "allOf": [ { "$ref": "#/components/schemas/Declaration" } ], "nullable": true, "description": "A bejelentéshez tartozó bevallás (azonos adózó, vonalkód = `data_sheet_id`), adózó és tárhely-üzenetek nélkül; `null`, ha a rendszerben nincs ilyen bevallás." } } }, "Employee": { "type": "object", "description": "Biztosított jogviszony: akit az adózó foglalkoztat, a NAV-nál nyilvántartott biztosítotti bejelentés (T1041) alapján.", "required": [ "id", "trustee_id", "name", "tax_identification_number", "social_security_number", "relationship_start", "relationship_end", "relationship_code", "relationship_name", "week_hours", "feor_code", "feor_name", "data_sheet_id", "data_sheet_status", "data_sheet_type", "data_sheet_arrived_at", "supplement_sheet_id", "nationality", "mother_name", "only_additional_employer", "large_family_discount", "birthday", "birth_city", "birth_country", "birth_name" ], "properties": { "id": { "type": "integer", "description": "A jogviszony azonosítója." }, "trustee_id": { "type": "integer", "description": "A foglalkoztató adózó azonosítója." }, "name": { "type": "string", "description": "A biztosított neve." }, "tax_identification_number": { "type": "integer", "description": "A biztosított adóazonosító jele (10 számjegy).", "example": 8449251001 }, "social_security_number": { "type": "string", "description": "A biztosított TAJ szám (9 számjegy, elválasztó nélkül).", "nullable": true, "example": "123456789" }, "relationship_start": { "type": "string", "description": "A jogviszony kezdete (ÉÉÉÉ-HH-NN).", "format": "date" }, "relationship_end": { "type": "string", "description": "A jogviszony vége (ÉÉÉÉ-HH-NN); `null`, ha fennáll.", "nullable": true, "format": "date" }, "relationship_code": { "type": "string", "description": "A biztosítási jogviszony kódja (pl. `1101` munkaviszony).", "nullable": true, "example": "1101" }, "relationship_name": { "type": "string", "description": "A jogviszony-kód megnevezése (pl. „Munkaviszony”); `null`, ha a kód ismeretlen vagy hiányzik.", "nullable": true, "example": "Munkaviszony" }, "week_hours": { "type": "integer", "description": "A heti munkaóra (a legutóbbi érvényes érték).", "nullable": true, "minimum": 0, "maximum": 255, "example": 40 }, "feor_code": { "type": "string", "description": "A munkakör FEOR-kódja (4 karakter).", "nullable": true, "example": "4111" }, "feor_name": { "type": "string", "description": "A FEOR-kód megnevezése; `null`, ha a kód ismeretlen vagy hiányzik.", "nullable": true }, "data_sheet_id": { "type": "string", "description": "A bejelentő adatlap NAV-iktatószáma." }, "data_sheet_status": { "type": "string", "description": "Az adatlap NAV szerinti feldolgozási állapota: `FELDOLGOZOTT` feldolgozott, `HIBAS` hibás.", "enum": [ "FELDOLGOZOTT", "HIBAS" ] }, "data_sheet_type": { "type": "string", "description": "A bejelentő nyomtatvány típusa, évszám-előtaggal (pl. `25T1041`).", "example": "25T1041" }, "data_sheet_arrived_at": { "type": "integer", "description": "A bejelentés beküldésének ideje, Unix időbélyeg (másodperc).", "example": 1767258000 }, "supplement_sheet_id": { "type": "integer", "description": "A bejelentés sorszáma (pótlap száma) az adatlapon belül.", "nullable": true, "minimum": 1, "maximum": 65535 }, "nationality": { "type": "string", "description": "Állampolgárság (a NAV kód-megnevezés alakjában).", "nullable": true }, "mother_name": { "type": "string", "description": "Anyja születési neve.", "nullable": true }, "only_additional_employer": { "type": "boolean", "description": "A bejelentés szerint a foglalkoztató kizárólag további (nem fő) foglalkoztató." }, "large_family_discount": { "type": "boolean", "description": "A bejelentés szerint a biztosított nagycsaládos kedvezményt vesz igénybe." }, "birthday": { "type": "string", "description": "Születési dátum (ÉÉÉÉ-HH-NN).", "nullable": true, "format": "date" }, "birth_city": { "type": "string", "description": "Születési hely.", "nullable": true }, "birth_country": { "type": "string", "description": "Születési ország (a NAV kód-megnevezés alakjában).", "nullable": true }, "birth_name": { "type": "string", "description": "Születési név.", "nullable": true }, "trustee": { "allOf": [ { "$ref": "#/components/schemas/Trustee" } ], "description": "A foglalkoztató adózó." } } }, "Employer": { "type": "object", "description": "Saját foglalkoztató: munkáltató, amelynél maga az adózó biztosított, a NAV nyilvántartása szerint.", "required": [ "id", "trustee_id", "name", "tax_number", "tax_identification_number", "relationship_start", "relationship_end", "relationship_code", "relationship_name", "week_hours", "feor_code", "feor_name" ], "properties": { "id": { "type": "integer", "description": "A rekord azonosítója." }, "trustee_id": { "type": "integer", "description": "Az adózó (a biztosított) azonosítója." }, "name": { "type": "string", "description": "A foglalkoztató neve rövidített cégformával (pl. „Alfa Kft.”); a teljes név a válaszban nem szerepel.", "example": "Alfa Kft." }, "tax_number": { "type": "integer", "description": "A foglalkoztató adószáma elválasztó nélkül (8 jegyű törzsszám vagy 11 jegyű adószám); `null`, ha nincs (pl. magánszemély foglalkoztató).", "nullable": true, "example": 12345678211 }, "tax_identification_number": { "type": "integer", "description": "A foglalkoztató adóazonosító jele (10 számjegy), ha magánszemély; egyébként `null`.", "nullable": true }, "relationship_start": { "type": "string", "description": "A jogviszony kezdete (ÉÉÉÉ-HH-NN).", "format": "date" }, "relationship_end": { "type": "string", "description": "A jogviszony vége (ÉÉÉÉ-HH-NN); `null`, ha fennáll.", "nullable": true, "format": "date" }, "relationship_code": { "type": "string", "description": "A biztosítási jogviszony kódja (pl. `1101` munkaviszony).", "example": "1101" }, "relationship_name": { "type": "string", "description": "A jogviszony-kód megnevezése; `null`, ha a kód ismeretlen.", "nullable": true, "example": "Munkaviszony" }, "week_hours": { "type": "integer", "description": "Heti munkaóra ennél a foglalkoztatónál.", "nullable": true, "minimum": 0, "maximum": 255, "example": 40 }, "feor_code": { "type": "integer", "description": "A munkakör FEOR-kódja számként (a kezdő nulla elveszhet, pl. `0110` → `110`).", "nullable": true, "example": 4111 }, "feor_name": { "type": "string", "description": "A FEOR-kód megnevezése; `null`, ha a kód ismeretlen vagy hiányzik.", "nullable": true }, "trustee": { "allOf": [ { "$ref": "#/components/schemas/Trustee" } ], "description": "Az adózó, aki ennél a foglalkoztatónál biztosított." } } }, "TrusteeRole": { "type": "object", "description": "Egy NAV-törzsadat lap (a NAV Online Ügyfélportálon látható nyilvántartási adatok) cégként vagy magánszemélyként, a legutóbbi és az azt megelőző állapottal, valamint a KOMA (Köztartozásmentes Adózói Adatbázis) adatokkal.", "properties": { "role": { "type": "string", "enum": [ "natural_person", "company" ], "description": "A lap fajtája: `company` cég / vállalkozás adatai, `natural_person` a magánszemély adatai." }, "data": { "type": "array", "items": { "type": "object", "description": "Egy törzsadat-csomópont: vagy csoport (`label` + `rows`, a `rows` elemei ugyanilyen csomópontok, tetszőleges mélységben), vagy érték (`label` + `value`). A legfelső szintű csoportnak nem mindig van `label`-je.", "properties": { "label": { "type": "string", "example": "Székhelycíme", "description": "A mező vagy csoport neve, ahogy a NAV-nyilvántartásban szerepel." }, "value": { "type": "string", "nullable": true, "example": "HU 1011 BUDAPEST FŐ UTCA 1.", "description": "A mező értéke (csak érték-csomópontnál)." }, "rows": { "type": "array", "items": { "type": "object" }, "description": "Az alárendelt csomópontok (csak csoportnál), ugyanebben a szerkezetben." } } }, "description": "A törzsadatok aktuális állapota csoportokba rendezett fában." }, "previous_data": { "type": "array", "nullable": true, "items": { "type": "object", "description": "Egy törzsadat-csomópont: vagy csoport (`label` + `rows`, a `rows` elemei ugyanilyen csomópontok, tetszőleges mélységben), vagy érték (`label` + `value`). A legfelső szintű csoportnak nem mindig van `label`-je.", "properties": { "label": { "type": "string", "example": "Székhelycíme", "description": "A mező vagy csoport neve, ahogy a NAV-nyilvántartásban szerepel." }, "value": { "type": "string", "nullable": true, "example": "HU 1011 BUDAPEST FŐ UTCA 1.", "description": "A mező értéke (csak érték-csomópontnál)." }, "rows": { "type": "array", "items": { "type": "object" }, "description": "Az alárendelt csomópontok (csak csoportnál), ugyanebben a szerkezetben." } } }, "description": "A törzsadatok legutóbbi változás előtti állapota, ugyanabban a szerkezetben. `null`, ha még nem változott." }, "koma_included": { "type": "boolean", "nullable": true, "description": "Szerepel-e az adózó a Köztartozásmentes Adózói Adatbázisban (KOMA). `null`, ha nincs róla adat." }, "koma_qualification": { "type": "boolean", "nullable": true, "description": "Minősített-e (megfelel-e a KOMA-ba kerülés feltételeinek). `null`, ha nincs róla adat." }, "koma_disqualifying_reason": { "type": "string", "nullable": true, "description": "A KOMA-ból kizáró ok szövege, ha van." }, "koma_application_date": { "type": "string", "format": "date", "nullable": true, "description": "A KOMA-felvételi kérelem dátuma (ÉÉÉÉ-HH-NN)." }, "koma_admission_date": { "type": "string", "format": "date", "nullable": true, "description": "A KOMA-ba felvétel dátuma (ÉÉÉÉ-HH-NN)." }, "koma_rejection_date": { "type": "string", "format": "date", "nullable": true, "description": "A kérelem elutasításának dátuma (ÉÉÉÉ-HH-NN)." }, "koma_appeal_date": { "type": "string", "format": "date", "nullable": true, "description": "A fellebbezés dátuma (ÉÉÉÉ-HH-NN)." }, "koma_deletion_request_date": { "type": "string", "format": "date", "nullable": true, "description": "A KOMA-ból törlés kérelmezésének dátuma (ÉÉÉÉ-HH-NN)." }, "koma_request_status": { "type": "string", "nullable": true, "enum": [ "Beküldés folyamatban", "Feldolgozás alatt", "Feldolgozott", "Elutasított" ], "description": "A KOMA-kérelem állapota magyar szöveggel. `null`, ha nincs kérelem." }, "koma_status": { "type": "string", "nullable": true, "enum": [ "included_qualified", "included_not_qualified", "in_progress", "not_included_qualified", "not_included_not_qualified" ], "description": "Összesített KOMA-állapot (erre szűr a keresés `koma_status` mezője). A Köztartozásmentes Adózói Adatbázis (KOMA) szerinti állapot: `included_qualified` szerepel, minősített; `included_not_qualified` szerepel, nem minősített; `in_progress` a felvételi kérelem beküldése vagy feldolgozása folyamatban; `not_included_qualified` nem szerepel, minősített; `not_included_not_qualified` nem szerepel, nem minősített. `null`, ha nincs KOMA-adat." }, "koma_status_label": { "type": "string", "nullable": true, "enum": [ "Szerepel, minősített", "Szerepel, nem minősített", "Folyamatban", "Nem szerepel, minősített", "Nem szerepel, nem minősített" ], "description": "A `koma_status` magyar felirata." }, "updated_at": { "type": "integer", "nullable": true, "description": "A törzsadat lap utolsó frissítésének ideje (unix időbélyeg, másodperc)." } } }, "TrusteeRoleLabel": { "type": "object", "description": "Egy NAV-törzsadat mezőnév (címke), amely kigyűjthető a `POST /trustees/bulk-roles-query` végponttal.", "properties": { "id": { "type": "integer", "description": "A címke azonosítója (`trustee_role_label_ids` elemei)." }, "label": { "type": "string", "example": "KIVA adóalanyiság kezdete", "description": "A címke szövege, ahogy a NAV-törzsadatokban szerepel." } } }, "TrusteeTaxType": { "type": "object", "description": "Az adózó NAV-adófolyószámlájának egy adóneme a legutóbbi letöltés szerint.", "properties": { "tax_type_number": { "type": "integer", "example": 104, "description": "A NAV-adónem kódja (pl. 101 társasági adó, 103 személyi jövedelemadó, 104 általános forgalmi adó)." }, "tax_type_name": { "type": "string", "nullable": true, "example": "Általános forgalmi adó", "description": "Az adónem neve. `null`, ha a kód ismeretlen." }, "tax_type_bank_account_number": { "type": "string", "nullable": true, "example": "10032000-01076868", "description": "Az adónem NAV-os befizetési számlaszáma. `null`, ha nem ismert." }, "debt": { "type": "integer", "example": 4000, "description": "Az adónem egyenlege. Pozitív érték tartozás, negatív túlfizetés (forintban)." }, "last_obligation_date": { "type": "string", "format": "date", "nullable": true, "example": "2026-06-01", "description": "Az utolsó kötelezettség (előírás) dátuma (ÉÉÉÉ-HH-NN)." }, "last_payment_date": { "type": "string", "format": "date", "nullable": true, "description": "Az utolsó befizetés dátuma (ÉÉÉÉ-HH-NN)." } } }, "TaxAccountQuery": { "type": "object", "description": "Adófolyószámla-lekérdezés: egy fordulónapra szóló NAV adófolyószámla-kivonat kérése egy vagy több adózóra.", "required": [ "id", "query_date", "type", "send_mail", "note", "created_at", "completed_at" ], "properties": { "id": { "type": "integer", "description": "A lekérdezés azonosítója." }, "query_date": { "type": "string", "format": "date", "example": "2026-09-30", "description": "A fordulónap (a felületen „Időszak vége”), amelyre a kivonat szól (ÉÉÉÉ-HH-NN)." }, "type": { "type": "string", "enum": [ "ADONEM_EGYENLEGES", "TETELES", "LISTA" ], "description": "A kivonat típusa: `ADONEM_EGYENLEGES` adónemenkénti egyenleges, `TETELES` tételes (az adónem szerinti kigyűjtés ebből készül), `LISTA` lista típusú kivonat." }, "send_mail": { "type": "boolean", "description": "Igaz, ha a befejezéskor a lekérdezést indító felhasználó emailt kap az eredményekkel." }, "note": { "type": "string", "nullable": true, "description": "A lekérdezéshez írt megjegyzés." }, "created_at": { "type": "integer", "example": 1761555600, "description": "A lekérdezés indításának ideje (unix időbélyeg, másodperc)." }, "completed_at": { "type": "integer", "nullable": true, "example": 1761559200, "description": "A befejezés ideje (unix időbélyeg): akkor töltődik ki, amikor minden adózó eredménye `completed` vagy `failed` lett. `null`, amíg a lekérdezés fut." }, "tax_account_query_trustees": { "type": "array", "items": { "$ref": "#/components/schemas/TaxAccountQueryTrustee" }, "description": "Adózónkénti eredmények, csak a felhasználó által látható adózókra; minden elemben benne van a `trustee`, de nincs `tax_account_query`. Csak a `/tax-account-queries` végpontok válaszában szerepel; a `/tax-account-query-trustees` végpontok beágyazott lekérdezéséből hiányzik." } } }, "TaxAccountQueryTrustee": { "type": "object", "description": "Egy adózó eredménye egy adófolyószámla-lekérdezésben (állapot és a letölthető kivonatfájlok).", "required": [ "id", "trustee_id", "status", "tax_file_pdf", "tax_file_xlsx", "tax_file_xml" ], "properties": { "id": { "type": "integer", "description": "Az adózónkénti eredmény azonosítója." }, "trustee_id": { "type": "integer", "description": "Az adózó azonosítója." }, "status": { "type": "string", "enum": [ "pending", "in_progress", "completed", "failed" ], "description": "Az eredmény állapota: `pending` várakozik, `in_progress` folyamatban, `completed` kész (legalább egy kivonatfájl letölthető), `failed` sikertelen (nem készült kivonat; új lekérdezést kell indítani)." }, "tax_file_pdf": { "type": "string", "format": "uri", "nullable": true, "description": "A PDF kivonat letöltési URL-je; `null`, ha nincs (még) ilyen fájl." }, "tax_file_xlsx": { "type": "string", "format": "uri", "nullable": true, "description": "Az XLSX kivonat letöltési URL-je; `null`, ha nincs (még) ilyen fájl." }, "tax_file_xml": { "type": "string", "format": "uri", "nullable": true, "description": "Az XML kivonat letöltési URL-je; `null`, ha nincs (még) ilyen fájl." }, "trustee": { "allOf": [ { "$ref": "#/components/schemas/Trustee" } ], "description": "Az adózó adatai (minden végpont válaszában szerepel, ahol ez az objektum megjelenik)." }, "tax_account_query": { "allOf": [ { "$ref": "#/components/schemas/TaxAccountQuery" } ], "description": "A lekérdezés adatai (a `tax_account_query_trustees` nélkül). Csak a `/tax-account-query-trustees` végpontok válaszában szerepel." } } }, "Invoice": { "type": "object", "description": "Az iroda részére kiállított KapuSegéd előfizetési számla.", "properties": { "id": { "type": "integer", "description": "A számla azonosítója." }, "invoice_no": { "type": "string", "description": "A számla sorszáma.", "example": "KS-2026-123" }, "price": { "type": "integer", "description": "A számla végösszege forintban." }, "paid_price": { "type": "integer", "description": "Az eddig kiegyenlített összeg forintban; ha eléri a `price`-t, a számla rendezett." }, "period_start": { "type": "string", "description": "Az elszámolt időszak első napja.", "format": "date", "example": "2026-09-01" }, "period_end": { "type": "string", "description": "Az elszámolt időszak utolsó napja.", "format": "date", "example": "2026-09-30" }, "url": { "type": "string", "description": "Nyilvános link a számla megtekintéséhez és letöltéséhez.", "format": "uri" }, "created_at": { "type": "integer", "description": "A kiállítás ideje (unix időbélyeg, másodperc).", "example": 1759312800 } } }, "Municipality": { "type": "object", "description": "Magyarországi önkormányzat, amelynek adószámlája az önkormányzati (ASP) rendszerből letölthető.", "properties": { "id": { "type": "integer", "example": 2658, "description": "Az önkormányzat azonosítója (`municipality_ids` elemei)." }, "name": { "type": "string", "example": "SZEGED MEGYEI JOGÚ VÁROS ÖNKORMÁNYZATA", "description": "Az önkormányzat hivatalos neve." } } }, "TrusteeMunicipality": { "type": "object", "description": "Az adózó egy önkormányzata (ahol helyi adót fizet), a letöltött önkormányzati (ASP) adószámlákkal. Saját azonosítója nincs a válaszban; az önkormányzatok listája a `PUT /trustees/{trusteeId}` `municipality_ids` mezőjével módosítható.", "properties": { "municipality": { "allOf": [ { "$ref": "#/components/schemas/Municipality" } ], "description": "Az önkormányzat." }, "accounts": { "type": "array", "items": { "$ref": "#/components/schemas/TrusteeMunicipalityAccount" }, "description": "Az ennél az önkormányzatnál letöltött adószámlák évenként. Üres tömb, ha még nincs letöltött adószámla." } } }, "TrusteeMunicipalityAccount": { "type": "object", "description": "Az adózó egy önkormányzati (ASP) adószámlája egy évre.", "properties": { "year": { "type": "integer", "example": 2026, "description": "Az adószámla éve." }, "file": { "type": "string", "format": "uri", "nullable": true, "description": "Az önkormányzati adószámla-kivonat (PDF) letöltési URL-je." }, "tax_types": { "type": "array", "items": { "$ref": "#/components/schemas/TrusteeMunicipalityAccountTaxType" }, "description": "Az adószámla adónemei." } } }, "TrusteeMunicipalityAccountTaxType": { "type": "object", "description": "Egy helyi adónem (pl. helyi iparűzési adó, építményadó) az önkormányzati adószámlán.", "properties": { "name": { "type": "string", "example": "Helyi iparűzési adó", "description": "Az adónem neve, ahogy az adószámlán szerepel." }, "debt": { "type": "integer", "example": -21711, "description": "Az adónem egyenlege. Pozitív érték tartozás, negatív túlfizetés (forintban)." }, "bank_account_number": { "type": "string", "nullable": true, "example": "12067008-00102725-00100006", "description": "Az adónem befizetési számlaszáma tagolva (8-8 vagy 8-8-8 jegy). `null`, ha nem ismert." }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/TrusteeMunicipalityAccountTaxTypeItem" }, "description": "Az adónem tételei (előírások, befizetések). Az adózó-végpontok (`GET`, `PUT`, `search`) válaszában mindig szerepel." } } }, "TrusteeMunicipalityAccountTaxTypeItem": { "type": "object", "description": "Egy tétel (előírás, befizetés stb.) egy helyi adónem adószámláján.", "properties": { "date": { "type": "string", "format": "date", "example": "2026-03-16", "description": "A tétel dátuma (ÉÉÉÉ-HH-NN)." }, "code": { "type": "string", "nullable": true, "enum": [ "AE1", "AKE", "AKT", "RNF", "AE0", "AE2", "AHE", "JOC", "NKD", "REF", "REN", "SNO", "SZA", "SZV", "VIF" ], "description": "A tétel ASP-s jogcímkódja (pl. `AE1`, `AE2` előleg-előírás, `RNF` rendszeres befizetés), ahogy az adószámlán szerepel. `null`, ha nincs." }, "name": { "type": "string", "nullable": true, "description": "A tétel megnevezése vagy hivatkozási száma, ahogy az adószámlán szerepel." }, "debt": { "type": "integer", "example": 1292, "description": "A tétel összege forintban." } } }, "TrusteePublicDebt": { "type": "object", "description": "Az adózó egy végrehajtható köztartozása (a NAV által nyilvántartott, végrehajtásra átadott köztartozás) jogcímenként.", "properties": { "name": { "type": "string", "example": "Kamarai hozzájárulás (Gazdasági kamara)", "description": "A jogcím neve." }, "code": { "type": "string", "example": "00004", "description": "A jogcím kódja." }, "debt": { "type": "integer", "minimum": 0, "example": 20000, "description": "A tartozás összege forintban." } } }, "PaymentObligation": { "type": "object", "description": "Fizetési kötelezettség: egy adózó egy befizetendő tétele (összeg, esedékesség, utalási adatok), kézzel rögzítve vagy a NAV adófolyószámlájából / önkormányzati adószámlából automatikusan létrehozva.", "required": [ "id", "trustee_id", "name", "price", "due", "bank_account_number", "announcement", "note", "notification_status", "creator", "balance" ], "properties": { "id": { "type": "integer", "description": "A kötelezettség azonosítója." }, "trustee_id": { "type": "integer", "description": "Az adózó azonosítója, akihez a tétel tartozik." }, "name": { "type": "string", "example": "101 Társasági adó", "description": "A kötelezettség megnevezése; automatikus tételnél az adónem kódja és neve." }, "price": { "type": "integer", "format": "int64", "example": 450000, "description": "A fizetendő összeg forintban." }, "due": { "type": "string", "format": "date", "example": "2026-11-12", "description": "Az esedékesség napja (ÉÉÉÉ-HH-NN)." }, "bank_account_number": { "type": "string", "nullable": true, "example": "10032000-01076019", "description": "A kedvezményezett bankszámlaszáma kötőjelekkel tagolva (8-8 vagy 8-8-8 számjegy)." }, "announcement": { "type": "string", "nullable": true, "example": "Adószám: 12345676-1-23", "description": "Az utalási közlemény." }, "note": { "type": "string", "nullable": true, "description": "Megjegyzés a tételhez (az ügyfélnek küldött levélben is megjelenik)." }, "notification_status": { "type": "string", "enum": [ "not_notified", "delivered", "opened" ], "description": "A tételről küldött levelek legjobb állapota: `opened` legalább egy levelet megnyitottak, `delivered` legalább egy levél megérkezett, de egyiket sem nyitották meg, `not_notified` nem ment ki levél, vagy egyik sem érkezett meg." }, "creator": { "type": "string", "enum": [ "user", "upo_tax_file", "asp_tax_file" ], "description": "A tétel forrása: `user` kézzel rögzített (egyenként vagy importtal; módosítható, törölhető), `upo_tax_file` a NAV adófolyószámlájából automatikusan, `asp_tax_file` az önkormányzati (ÁSP) adószámlából automatikusan létrejött tétel (ez a kettő nem módosítható és nem törölhető)." }, "balance": { "type": "integer", "format": "int64", "nullable": true, "description": "Automatikus tételnél az adónem várható egyenlege az esedékesség napján forintban: pozitív érték még fizetendő összeget jelent, nulla vagy negatív érték azt, hogy befizették, vagy túlfizetés fedezi. Kézzel rögzített tételnél, vagy ha az egyenleg nem ismert, `null`." }, "trustee": { "allOf": [ { "$ref": "#/components/schemas/Trustee" } ], "description": "Az adózó adatai. A jelenlegi végpontok nem töltik be, ezért a válaszban nem szerepel (az adózó a `trustee_id`-ból, a táblázatnál a sor `trustee` mezőjéből olvasható)." }, "sent_mails": { "type": "array", "items": { "$ref": "#/components/schemas/SentMail" }, "description": "A tételről kiküldött levelek (címzettenként egy) a kézbesítés állapotával." } } }, "DeclarationObligation": { "type": "object", "description": "Az adózó egy bevallási kötelezettsége a NAV Online Ügyfélportál (ÜPO) nyilvántartása szerint (az Adónaptár egy kártyája).", "required": [ "id", "trustee_id", "title", "tax_report_type", "due", "conditional", "note", "interval_start", "interval_end", "status", "declarations" ], "properties": { "id": { "type": "integer", "description": "A kötelezettség azonosítója." }, "trustee_id": { "type": "integer", "description": "Az adózó azonosítója." }, "title": { "type": "string", "description": "A kötelezettség megnevezése a NAV szerint." }, "tax_report_type": { "type": "string", "description": "A nyomtatvány típusa (pl. `2608`); `null`, ha a NAV nem rendelt hozzá nyomtatványt.", "nullable": true, "example": "2608" }, "due": { "type": "string", "description": "Az esedékesség napja (ÉÉÉÉ-HH-NN).", "format": "date", "example": "2026-11-12" }, "conditional": { "type": "boolean", "description": "`true`, ha a NAV feltételes kötelezettségként tartja nyilván: csak bizonyos feltételek teljesülése esetén kell beadni." }, "note": { "type": "string", "description": "A NAV megjegyzése a kötelezettséghez.", "nullable": true }, "interval_start": { "type": "string", "description": "A kötelezettség bevallási időszakának első napja (ÉÉÉÉ-HH-NN), a nyomtatványból, az esedékességből és az adózó áfa-gyakoriságából számolva; `null`, ha nem állapítható meg.", "nullable": true, "format": "date" }, "interval_end": { "type": "string", "description": "A bevallási időszak utolsó napja (ÉÉÉÉ-HH-NN); `null`, ha nem állapítható meg.", "nullable": true, "format": "date" }, "status": { "type": "string", "description": "Számolt állapot: `submitted` beadva (van bevallás ugyanarra a nyomtatványra és időszakra); `submittable` beadható (az esedékesség még nem járt le, bevallás nem érkezett); `missing` hiányzó (lejárt, és az ÜPO hiányzónak tartja); `conditional` feltételes (lejárt, bevallás nem érkezett, a kötelezettség feltételes); `unknown` ismeretlen (nincs nyomtatvány vagy időszak, vagy lejárt, de sem bevallás, sem hiányzó-jelzés nincs).", "enum": [ "submitted", "submittable", "missing", "conditional", "unknown" ] }, "declarations": { "type": "array", "items": { "$ref": "#/components/schemas/Declaration" }, "description": "A kötelezettségre beérkezett bevallások (azonos adózó, nyomtatvány és időszak), adózó és tárhely-üzenetek nélkül." } } }, "Survey": { "type": "object", "description": "Adategyeztetés: a NAV által az adózónak küldött, az Online Ügyfélportálon kitöltendő kérdőív és állapota.", "required": [ "id", "trustee_id", "survey_id", "name", "status", "sent_at", "submitted_at", "editable", "editor_tax_identification_number", "editor_name" ], "properties": { "id": { "type": "integer", "description": "Az adategyeztetés azonosítója a KapuSegédben." }, "trustee_id": { "type": "integer", "description": "Az adózó azonosítója." }, "survey_id": { "type": "string", "description": "Az adategyeztetés NAV-azonosítója." }, "name": { "type": "string", "description": "Az adategyeztetés (adategyeztető) neve." }, "status": { "type": "string", "description": "Állapot a NAV kódjával: `KITOLTENDO` kitöltendő, `FOLYAMATBAN` a kitöltés folyamatban, `BEKULDOTT` beküldve, `LEZART` lezárt. Más kód is előfordulhat.", "example": "KITOLTENDO" }, "sent_at": { "type": "string", "description": "A létrehozás (kiküldés) napja (ÉÉÉÉ-HH-NN).", "nullable": true, "format": "date" }, "submitted_at": { "type": "integer", "description": "A beküldés ideje, Unix időbélyeg (másodperc); `null`, ha még nincs beküldve.", "nullable": true }, "editable": { "type": "boolean", "description": "`true`, ha az adategyeztetés a NAV-on még szerkeszthető." }, "editor_tax_identification_number": { "type": "integer", "description": "A kitöltő adóazonosító jele (10 számjegy).", "nullable": true }, "editor_name": { "type": "string", "description": "A kitöltő neve.", "nullable": true }, "trustee": { "allOf": [ { "$ref": "#/components/schemas/Trustee" } ], "description": "Az adózó." } } } } } }