diff --git a/AyCode.Services/Nav/docs/EKAER_INTERFACE.md b/AyCode.Services/Nav/docs/EKAER_INTERFACE.md index bcfd1d2..5b7fcdb 100644 --- a/AyCode.Services/Nav/docs/EKAER_INTERFACE.md +++ b/AyCode.Services/Nav/docs/EKAER_INTERFACE.md @@ -70,6 +70,16 @@ signingKey = Elek65Titkos SHA-512 = AF84DC456B82234E67550C80169E517FBDAB4403607293985DECB09F534D9F73FADAABEFEE932554FABBC49F6E8F74A5DD54EA359D6B7644D95CFF3530AFB889 ``` +## Hozzáférés — kié a `user` + `signingKey`? (gyakori félreértés) + +A fenti `user` / `passwordHash` / `signingKey` az **ADÓZÓé** (a bejelentésre kötelezett cégé), **NEM a szoftverfejlesztőé** (leellenőrizve: , 2026-06): + +- Az adózó **elsődleges felhasználóként, Ügyfélkapun** lép be az EKÁER-be, és **ő állítja be a titkos XML kommunikációs kulcsot** (`signingKey`) a saját fiókjában (a kulcs a webről jön, az XML-ben nem szerepel). +- A szoftver egyszerűen az **adózó** `user`+`signingKey` párját használja (a fogyasztó config/secret-store-ából — itt: `INavCredentials`). +- A fejlesztő legfeljebb **másodlagos felhasználóként** kap jogot (a primary user adja, NINCS külön NAV/Ügyfélkapu-regisztráció). **„Technikai felhasználó" itt NINCS.** + +> **Másik interfész (2024–25): a „NAV M2M általános gépi interfész"** — ÚJ, általánosabb beküldő-csatorna, ahol **a fejlesztő a kliensprogramot regisztrálja** a NAV-nál (a végfelhasználók is regisztrálnak + NAV-tól kapott titkos kódokat írnak be). Ez **NEM** a fenti klasszikus EKÁER 2.2 XML-interfész. Ha a NAV oda terel, ott VAN fejlesztői regisztráció — production előtt érdemes tisztázni, melyik a hatályos. + ## Műveletek (`tradeCardOperations` → `operation`) | Operation | Jelentés | diff --git a/AyCode.Services/Nav/docs/EKAER_VALIDATION.md b/AyCode.Services/Nav/docs/EKAER_VALIDATION.md index 78d3ebe..b2f2148 100644 --- a/AyCode.Services/Nav/docs/EKAER_VALIDATION.md +++ b/AyCode.Services/Nav/docs/EKAER_VALIDATION.md @@ -64,9 +64,16 @@ A `BaseResultType` (funcCode/reasonCode/msg) a `Nav/NavInterfaces.cs` `INavResul A fenti szabályokat a **`EkaerTradeCardValidator`** (`Nav/Ekaer/`) ellenőrzi a leképzett tradeCard-okon, **beküldés előtt**, hibalistával (nem áll meg az első hibánál): - **Séma-szint:** a generált modellek `[Required]` / `[RegularExpression]` / hossz-attribútumai (rekurzívan a tradeCard + tételek + jármű + helyszínek fölött), a `System.ComponentModel.DataAnnotations.Validator`-ral. A `*Value`/`*Specified` segéd-property-ket kihagyja (a default `DateTime` különben tévesen bukna a timestamp-patternen). -- **Üzleti szabályok** (az XSD-ben nem `[Required]`, de a NAV megköveteli): vonó jármű kötelező, legalább egy tétel, feladó/címzett név+adószám+ország. +- **Üzleti szabályok** (az XSD-ben nem `[Required]`, de a NAV megköveteli): legalább egy tétel, feladó/címzett név+adószám+ország. A **vonó jármű (rendszám)** viszont **NEM blokkoló hiba, hanem `Warning`** (lásd a *Súlyosság* szakaszt) — a NAV csak a *felrakodás megkezdéséig* / `Finalize`-ig kéri (`TC_FINALIZE_VEHICLE_DATA_EMPTY`), `Create`-nél még hiányozhat (pl. a vevő viszi el az árut, beadáskor még nincs rendszám). - **`productVtsz` üres-string:** a modellen `[Required(AllowEmptyStrings=true)]` + pattern miatt az `""` elcsúszna a sémán (a `null` bukik, az `""` nem) — ezért a validátor külön lezárja. -A **`EkaerSubmitService`** (`Nav/Ekaer/`) a kapu: `Validate` → ha a hibalista nem üres, **nem küld** (`EkaerSubmitResult.Invalid`); egyébként `EkaerManageService.ManageAsync`. +### Súlyosság: `Warning` vs `Error` (2026-06) + +A validátor üzenetei **súlyozottak**: `EkaerValidationMessage : ValidationResult` egy `EkaerSeverity { Warning, Error }` mezővel. A sima `ValidationResult` (séma-szint, `ValidateAnnotations`) **`Error`**-nak számít — a `GetSeverity()` kiterjesztés default-ja. Segédek: `HasErrors()` / `HasWarnings()`. + +- **`Error`** = blokkoló (séma-bukás, hiányzó feladó/címzett/VTSZ, rossz formátum) → **nem küldhető**. +- **`Warning`** = küldhető, de pótlandó adat — jelenleg a **hiányzó vonó jármű (rendszám)** (a felrakodásig / `Finalize`-ig pótolandó). + +A **`EkaerSubmitService`** (`Nav/Ekaer/`) a kapu: `Validate` → **csak ha `HasErrors()`** áll meg (`EkaerSubmitResult.Invalid`); a `Warning`-ok **átmennek** (a beküldés mehet, a hiányt később pótolják), egyébként `EkaerManageService.ManageAsync`. A fogyasztó (FruitBank) ezt `Generated` / `GeneratedWithWarning` státuszra képezi. > ⚠️ **Nyitott (value):** a tétel `value` a NAV szerint **2021-től > 0 kötelező** (lásd a Tétel-validáció szakaszt), a validátor viszont **jelenleg nem követeli** — mert a FruitBank-mapper a deviza/FX tisztázásáig nem tölti. Amíg ez nyitott, a NAV **elutasíthatja** a beküldést. Lezárandó: a value kitöltése (deviza→HUF) + a validátorban `value > 0` üzleti szabály. (Plugin `EKAER_TODO` #3/#10.) diff --git a/AyCode.Services/Nav/docs/README.md b/AyCode.Services/Nav/docs/README.md index 93168c7..ef6fff2 100644 --- a/AyCode.Services/Nav/docs/README.md +++ b/AyCode.Services/Nav/docs/README.md @@ -21,6 +21,19 @@ A NAV adatszolgáltatás (jelenleg EKÁER) hivatalos forrásai + **LLM-barát ki **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** (). 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).