# EKÁER — Validációs szabályok és hibakódok

> **Forrás:** [`eKAERManagementService_2.2.pdf`](eKAERManagementService_2.2.pdf) §2.3.2.2/2.3.2.5/2.3.2.9/3.5 + `common.xsd` `ReasonCodeType`.
> Kivonat — a **teljes** hibakód-lista (~150 érték, leírással) a `common.xsd` `ReasonCodeType`-jában. Payload: [`EKAER_TRADECARD.md`](EKAER_TRADECARD.md).

## Válasz-eredmény (`result`)

| Mező | Érték |
|---|---|
| `funcCode` | `OK` (siker) / `WARNING` (részben — ritka) / `ERROR` (hiba) |
| `reasonCode` | enum; `SUCCESS` a siker, minden más hibára utal |
| `msg` | szöveges leírás (jellemzően hibánál) |

A `manageTradeCardsResponse` művelet­enként (`operationResult`, `index` szerint) adja vissza az eredményt. A `tradeCardInfo` a bejelentés alapadatait (köztük a `tcn`-t és a státuszt) hozza; `NAVValidations` / `warnings` a részletek.

## Kötelezőség `tradeType` szerint (a leggyakoribb hibaforrás)

| Szabály | E (export) | I (import) | D (belföld) |
|---|---|---|---|
| feladó+címzett **név és adószám** | kötelez | kötelező | kötelező (mindig) |
| feladó címadat (`sellerAddress`/`sellerCountry`) | kötelező | opcionális | kötelező |
| címzett címadat (`destinationAddress`/`destinationCountry`) | opcionális | kötelező | kötelező |
| fel-/lerakodási cím **magyar** + magyar adószám | felrakodás HU | lerakodás HU | mindkettő HU |

Normál bejelentésnél (`tradeCardType=N`) **mindig** kell fel- és lerakodási cím (1.8-tól: `deliveryPlan`-ben). Egyszerűsítettnél (`S`) nem.

## Címadat-validáció (`LocationType`)

- `country`, `zipCode`, `city` kötelező.
- `street`+`streetNumber` **vagy** `lotNumber` kötelező.
- `gpsPosition` önmagában csak akkor elég, ha **nincs kockázatos termék**.
- Import + `isDestinationCompanyIdentical=false` + kockázatos termék → a lerakodási címben `name` és `VATNumber` kötelező.

## Tétel-validáció (`tradeCardItem`)

- **VTSZ** létezés-ellenőrzés; 2021.01.01-től **8 számjegy** kötelező (különben `TC_VTSZ_TOO_SHORT`), ismeretlen → `TC_VTSZ_UNKNOWN`.
- VTSZ alapján **kockázatos**-e → ha igen, **biztosítékot** számol; csak elegendő fedezetnél rögzíthető (`LOW_BALANCE`).
- VTSZ alapján **FELIR**-köteles-e → a bejelentő FELIR-számának ellenőrzése (NÉBIH); ezeket csak engedélyezett első beraktározási helyen lehet lerakni.
- 2021.01.01-től minden tétel `value` > 0 kötelező.

## Hibakód-kategóriák (`ReasonCodeType` kivonat)

> A pontos kód + magyar leírás: `common.xsd` `ReasonCodeType`. Itt a navigációhoz a fő csoportok:

| Csoport | Példa kódok |
|---|---|
| Általános | `SUCCESS`, `OPERATION_FAILED`, `INVALID_INPUT`, `INVALID_REQUEST`, `INVALID_REQUEST_HEADERS`, `UNKNOWN_PACKAGE_VERSION` |
| Auth / jogosultság | `INVALID_USER_OR_PASSWORD`, `ACCESS_DENIED`, `NO_TAX_DATA`, `USER_TAX_DATA_NOT_VALID`, `EXPIRED_PASSWORD`, `NO_VALID_MASTER_USER` |
| Feladó / címzett | `TC_SELLER_NAME_EMPTY`, `TC_SELLER_VAT_NUMBER_EMPTY/ERROR`, `TC_DESTINATION_*`, `TC_*_MUST_BE_HUNGARY`, `TC_*_CANT_BE_HUNGARY` |
| Cím | `TC_LOAD_LOCATION_*`, `TC_UNLOAD_LOCATION_*`, `TC_LOCATION_NOT_HUNGARY`, `TC_LOCATION_NOT_COMPLETE` |
| Jármű / rendszám | `TC_VEHICLE_NOT_FOUND`, `TC_PLATENUMBER_MISSING`, `TC_PLATENUMBER_COUNTRY_MISSING`, `TC_UNKNOWN_LICENCE_PLATE_COUNTRY_CODE` |
| Dátum | `TC_INVALID_LOADDATE`, `TC_INVALID_ARRIVALDATE`, `TC_ARRIVALDATE_MISSING`, `TC_LOADDATE_MISSING`, `TC_FUTURE_ARRIVAL_NOT_ALLOWED`, `TC_VALIDITY_EXCEEDED` |
| Finalize | `TC_FINALIZE_VEHICLE_DATA_EMPTY`, `TC_FINALIZE_ARRIVAL_DATE_EMPTY`, `TC_FINALIZE_NOT_ALLOWED` |
| VTSZ / tétel | `TC_VTSZ_TOO_SHORT`, `TC_VTSZ_UNKNOWN`, `TC_ITEM_NOT_FOUND`, `TCI_*` (item-szintű), `TC_FELIR_NEBIH_REG_NEEDED` |
| Módosítás / lezárt | `TC_MODIFICATION_DISABLED`, `TC_MODIFY_BY_CARRIER_DISABLED`, `TC_FINALIZED_MOD_NOT_ALLOWED`, `TC_FINALIZED_*` |
| Biztosíték | `LOW_BALANCE` |

## A `funcCode`/`reasonCode` C# leképezése

A `BaseResultType` (funcCode/reasonCode/msg) a `Nav/NavInterfaces.cs` `INavResult`-jára húzódik rá (`IsSuccess` = `funcCode == OK`). A `NavReportServiceBase` ez alapján dob `NavReportException`-t a `reasonCode`-dal.

## A validáció C# megvalósítása

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): legalább egy tétel, feladó/címzett név+adószám+ország, és tételenként **`weight > 0`** + **`value > 0`** (2026-07; a value a NAV-nál 2021.01.01-től követelmény — a 0/hiányzó érték blokkoló `Error`, mert a forrás-dokumentumról hiányzó adatot jelez). 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.

### 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.

> ✅ **Lezárva (2026-07, value + weight):** a validátor tételenként kényszeríti a **`value > 0`**-t (NAV-követelmény 2021-től) és a **`weight > 0`**-t — mindkettő blokkoló `Error` (a 0/hiány a forrás-dokumentum adathibája, szándékosan nincs fallback). A fogyasztó (FruitBank) oldalán a value a `Partner.Currency` + EUR-HUF config-árfolyam alapján, a weight a szállítólevélen szereplő bruttóból (`GrossWeightOnDocument`) töltődik. (Plugin `EKAER_TODO` #3/#4/#10.)
