# EKÁER — TradeCard (a bejelentés payload-ja)

> **Forrás:** [`eKAERManagementService_2.2.pdf`](eKAERManagementService_2.2.pdf) §2.3 + [`ekaermanagement.xsd`](ekaermanagement.xsd) / [`common.xsd`](common.xsd).
> Kivonat — ütközésnél a PDF/XSD a hiteles. Auth/transport: [`EKAER_INTERFACE.md`](EKAER_INTERFACE.md). Műveletek: [`EKAER_OPERATIONS.md`](EKAER_OPERATIONS.md). Szabályok/hibák: [`EKAER_VALIDATION.md`](EKAER_VALIDATION.md).
> C# típusok: `Nav/Ekaer/Models/` (`BasicTradeCardType`, `TradeCardType`, `LocationType`, `TradeCardItemType`, `DeliveryPlanType`, `BasicVehicleDetailType`).

## tradeType — a fuvar iránya (MINDENT ez determinál)

| Érték | Irány | Magyar |
|---|---|---|
| `E` | Export | Belföldről közösségbe |
| `I` | Import | Közösségből belföldre |
| `D` | Domestic | Belföldről belföldre |

A `tradeType` dönti el, melyik cím-/adat-mező kötelező — lásd a kötelezőség-táblát lent és az [`EKAER_VALIDATION.md`](EKAER_VALIDATION.md)-t.

## Payload-fa

```
manageTradeCardsRequest
└── tradeCardOperations
    └── tradeCardOperation (index, operation, tradeCard|tcn, [arrivalDate finalize-nál])
        └── tradeCard
            ├── fejrész (tradeType, seller*, destination*, vehicle, dátumok, tradeCardType …)
            └── deliveryPlans → deliveryPlan (1.8+ : cím + tételek itt)
                └── items → tradeCardItem (VTSZ, név, tömeg, érték, tradeReason …)
```

## TradeCard fejrész — fő mezők

| Mező | Típus | Köt. | Megjegyzés |
|---|---|---|---|
| `tcn` | szöveg(20) | modify/delete/finalize-nál | eKÁER-szám; **create-nél elhagyandó** |
| `orderNumber` | szöveg(50) | nem | a bejelentő saját azonosítója |
| `tradeType` | `E`/`I`/`D` | **igen** | lásd fent |
| `sellerName` / `sellerVatNumber` | szöveg(200)/(15) | **igen** | feladó/eladó; magyar esetén az adószám **első 8 jegye** |
| `sellerCountry` / `sellerAddress` | szöveg(2)/(200) | E,D-nél igen | feladó országkód + cím |
| `destinationName` / `destinationVatNumber` | szöveg | **igen** | átvevő/vevő (adószám első 8 jegy) |
| `destinationCountry` / `destinationAddress` | szöveg | I,D-nél igen | |
| `vehicle/plateNumber` + `vehicle/country` | element | finalize előtt igen | vontató rendszáma + felségjel (A-Z) |
| `vehicle2/...` | element | nem | első vontatmány |
| `loadDate` (vagy `loadDateOnly`) | dateTime/date | nem | felrakodás ideje |
| `arrivalDate` (vagy `arrivalDateOnly`) | dateTime/date | finalize-nál | **2.0-tól a finalize operation-ben adandó meg**, nem itt |
| `tradeCardType` | `S`/`N` | nem (def. N) | `S`=egyszerűsített (nincs tétel), `N`=normál |
| `modByCarrierEnabled` | bool | nem (def. false) | a szállító módosíthat-e |
| `carrier` / `carrierText` | szöveg(30)/(200) | nem | szállítmányozó azonosító / név |
| `isIntermodal` | bool | nem | ha true, a fel-/lerakodás országa nincs validálva (1.6+) |

## Címadat (`LocationType`) — fel- és lerakodás

Mezők: `name`, `VATNumber`, `phone`, `e-mail`, `country`, `zipCode`, `city`, `street`, `streetType`, `streetNumber`, `lotNumber`, `gpsPosition/latitude|longitude`.

**Kötelezőség egy megadott címen belül:**
- `country`, `zipCode`, `city` — **kötelező**
- `street` + `streetNumber` — kötelező, **HA** nincs `lotNumber`
- `lotNumber` (helyrajzi szám) — opcionális; ha nincs, akkor `street`+`streetNumber` kell
- `gpsPosition` — opcionális; csak akkor elég önmagában, ha nincs kockázatos termék
- `name`, `VATNumber` — XSD-szinten opcionális, de Import + `isDestinationCompanyIdentical=false` + kockázatos termék esetén a **lerakodási címben kötelező**

## DeliveryPlan (menetlevél) — 1.8-tól

- **Normál** (`tradeCardType=N`) bejelentésnek **legalább 1 `deliveryPlan`** kell. Egyszerűsítettnek (`S`) nem.
- A fel-/lerakodási **címek + a tételek a deliveryPlan-ben** vannak (nem a fejrészben). Egy bejelentéshez több deliveryPlan is tartozhat (több útvonal).
- Tételt **csak deliveryPlan-hez** rendelve lehet megadni — minden menetlevélen definiálni kell az ott szállított összes tételt.
- Menetlevél **nem törölhető**; új deliveryPlan aktív bejelentéshez nem vehető fel.
- Mezők: `id` (szerver generálja, modify-nál kötelező), `externalId`, `isDestinationCompanyIdentical`, `loadLocation`, `unloadLocation`, `items`.
- **Backward-kompat:** 1.8 ALATT a címek a fejrészben (egy fel-/lerakodás), nincs deliveryPlans.

## Tétel (`tradeCardItem`)

| Mező | Típus | Köt. | Megjegyzés |
|---|---|---|---|
| `productVtsz` | szöveg(8), csak szám | **igen** | VTSZ-szám; **2021.01.01-től minden termék 8 számjegy** |
| `productName` | szöveg(200) | **igen** | a bejelentő által használt név (nem a VTSZ-megfelelő) |
| `tradeReason` | `S`/`A`/`W`/`O` | **igen** (1.x-től) | fuvar oka — biztosítékot befolyásol (lásd lent) |
| `weight` | decimal | **igen** | bruttó súly **kg**, max 9 jegyű egész |
| `value` | decimal | nem* | beszerzési érték **HUF**, max 11 jegyű egész. *2021.01.01-től kötelező, >0 |
| `adrNumber` | szöveg(200) | veszélyesnél igen | UN-kód(ok), vesszővel, UN prefix nélkül |
| `transportLicense` | szöveg(30) | nem | veszélyesáru-engedély száma |
| `expirationDate` | date | nem | élelmiszernél a lejárat |
| `batchNumber` | szöveg(30) | nem | sarzsszám |
| `factoryItemNumber` / `importerItemNumber` | szöveg(200) | nem | gyári / bejelentői cikkszám |
| `vatRateAssuranceExemption` | bool | nem (2.1+) | biztosítékmentes ÁFA-mérték (5%) alá tartozik-e |

## tradeReason (fuvar oka) + biztosíték

| Kód | Jelentés | Biztosíték? |
|---|---|---|
| `S` | Termékértékesítés / -beszerzés | **van** |
| `A` | Saját tulajdonú termék (kivezetve 2015.03.01 után — új bejelentésnél nem adható) | van |
| `W` | Bérmunka | nincs |
| `O` | Egyéb | nincs |

**A `tradeReason` a `tradeType`-tól függően korlátozott:**
- `E` (export): `S`, `W`, `O`
- `I` (import): `S`, `W`, `O`
- `D` (belföld): **csak `S`**

## Ország- és felségjel-kódok

Nem másoljuk — a megengedett listák: ország (`ISOCountryCodeA2Type`) a PDF §2.3.2.6 / `common.xsd`; jármű-felségjel (`VehicleCountryCode`) a PDF §2.3.2.7. A `country` mezők ezekre validálnak (kivéve `isIntermodal=true`).