# 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): vonó jármű kötelező, legalább egy tétel, feladó/címzett név+adószám+ország.
- **`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`.

> ⚠️ **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.)