48 lines
4.1 KiB
Markdown
48 lines
4.1 KiB
Markdown
# Nav/docs — NAV referencia-anyagok és kivonatok
|
||
|
||
A NAV adatszolgáltatás (jelenleg EKÁER) hivatalos forrásai + **LLM-barát kivonatok**. A kivonatok célja: ne kelljen a 2.2 MB-os PDF-et olvasni a gyakori feladatokhoz (token-takarékos, kereshető, a `docs-discovery` skill megtalálja).
|
||
|
||
## Hiteles források
|
||
|
||
| Fájl | Mit ad |
|
||
|---|---|
|
||
| [`eKAERManagementService_2.2.pdf`](eKAERManagementService_2.2.pdf) | A hivatalos EKÁER 2.2 interfész-leírás (NAV). **Ütközésnél ez + az XSD a mérvadó.** |
|
||
| [`ekaermanagement.xsd`](ekaermanagement.xsd) | A management-séma — a generált modellek (`Nav/Ekaer/Models/`) forrása. XSD-validációhoz is ez. |
|
||
| [`common.xsd`](common.xsd) | Közös EKÁER-séma: `BasicHeaderType`, `UserHeaderType`, `BaseResultType`, és a teljes `ReasonCodeType` (~150 hibakód). |
|
||
|
||
## Kivonatok (kezdd ezekkel)
|
||
|
||
| Fájl | Téma | Mikor |
|
||
|---|---|---|
|
||
| [`EKAER_INTERFACE.md`](EKAER_INTERFACE.md) | Transport, endpoint, **auth-algoritmus** (teszt-vektorral), üzenet-váz | A kommunikáció bekötésekor (megvan a kódban) |
|
||
| [`EKAER_TRADECARD.md`](EKAER_TRADECARD.md) | A **payload**: tradeType, fejrész, címadat, vehicle, deliveryPlan, tétel, tradeReason | A `Shipping → TradeCard` mapping (3. réteg) írásakor |
|
||
| [`EKAER_OPERATIONS.md`](EKAER_OPERATIONS.md) | Műveletek (create/modify/delete/finalize/correction) + státusz-életciklus | A bejelentés-folyamat implementálásakor |
|
||
| [`EKAER_VALIDATION.md`](EKAER_VALIDATION.md) | Validációs szabályok (tradeType-függő) + hibakód-kategóriák | Hibakezelés / mező-kötelezőség eldöntésekor |
|
||
|
||
**Olvasási sorrend új belépőnek:** `EKAER_INTERFACE` → `EKAER_TRADECARD` → `EKAER_OPERATIONS` → `EKAER_VALIDATION`.
|
||
|
||
## Jogszabályi alap, kötelezettség, hozzáférés (kontextus, 2026-06)
|
||
|
||
A fenti PDF/XSD a **HOGYAN** (a 2.2 interfész — a tradeCard beküldése). Néhány **általános** dolog, ami tisztázódott (a forrásból ellenőrizve):
|
||
|
||
**Jogszabály (a MIKOR kötelező):** a hatályos rendelet a **13/2020. (XII. 23.) PM rendelet** (<https://net.jogtar.hu>). A leképezést/kötelezettséget érintő elvek:
|
||
- az EKÁER-egység = **egy feladó → egy címzett, egy gépjárművel**; **§ 12:** EGY EKÁER-szám több *fel-/kirakodási címet* és több *terméktételt* is fedhet — **nem** szállítólevelenként kell darabolni;
|
||
- a bejelentés-kötelezettség **küszöbe erre a relációra AGGREGÁLT** (egy fuvarozás keretében ugyanazon feladótól ugyanazon címzett részére ugyanazon gépjárművel — § 4 i);
|
||
- a NAV **mindkét irányban büntet:** az **aluljelentés ÉS a túljelentés** is bírság — a kötelezettség-döntésnek pontosnak kell lennie.
|
||
|
||
> A konkrét küszöb-kategóriák/értékek a **jogszabálytól és a beállítástól függően változnak**, és a **fogyasztó** (pl. FruitBank) dönti el a kötelezettséget — itt szándékosan **nincs érték bedrótozva**. A fogyasztó-oldali kapu + a dátumozott küszöb-referencia: a FruitBank plugin `docs/EKAER/`.
|
||
|
||
**Hozzáférés (kié a `user` + `signingKey`):** az **ADÓZÓé** (a bejelentő cégé), **nem a fejlesztőé** — az adózó Ügyfélkapun, elsődleges felhasználóként állítja be a kulcsot, a szoftver az ő credentialját használja (`INavCredentials`). Részletek + a 2024–25-ös „NAV M2M" alternatíva: [`EKAER_INTERFACE.md`](EKAER_INTERFACE.md) → *Hozzáférés*.
|
||
|
||
## A réteg-kód
|
||
|
||
A base réteg (interfészek, auth, send-flow) doksija: [`../README.md`](../README.md).
|
||
|
||
Az EKÁER-kód a `Nav/Ekaer/`-ben:
|
||
- generált modellek: `Nav/Ekaer/Models/` (+ `EkaerNavAdapters.cs` — az `INav*` interfészek a generált típusokon)
|
||
- `EkaerManageService` / `EkaerQueryService` — NAV HTTP (manage / query)
|
||
- `EkaerTradeCardValidator` — a [`EKAER_VALIDATION.md`](EKAER_VALIDATION.md) szabályainak ellenőrzése (séma + üzleti), hibalistával
|
||
- `EkaerSubmitService` / `EkaerSubmitResult` — beküldés-orchestráció (validate → send)
|
||
|
||
Ez mind **általános** NAV/EKÁER réteg. A FruitBank-specifikus leképezés (`Shipping → tradeCard`) NEM itt van, hanem a fogyasztó oldalon: `FruitBank.Common/Services/Ekaer/` (mapper) + `FruitBank.Common.Server/Services/Ekaer/` (fogyasztó).
|