# EKÁER Management Service 2.2 — interfész-kivonat

> **Forrás:** [`eKAERManagementService_2.2.pdf`](eKAERManagementService_2.2.pdf) + [`ekaermanagement.xsd`](ekaermanagement.xsd) / [`common.xsd`](common.xsd).
> Ez **LLM-barát kivonat** a gyakori dolgokról — ütközés esetén **a PDF/XSD a hiteles forrás**.
> Online: <https://ekaer.nav.gov.hu/faq/?page_id=9>

## Transport

- **HTTP POST**, a body XML (UTF-8), a válasz body is XML. **Nincs SOAP.** TLS 1.2.
- Kötelező HTTP header-ek: **`content-type: text/xml`** és **`accept: text/xml`**. (NEM `application/xml`!)
- HTTP **200 OK** az üzleti válaszra is — a tényleges eredmény a válasz `result/funcCode`-jában van.

### Endpoint-ok

| Környezet | Báziscím |
|---|---|
| PROD | `https://import.ekaer.nav.gov.hu/TradeCardManagementService` |
| TEST | `https://import-test-b.ekaer.nav.gov.hu/TradeCardManagementService` |

Műveletek (a báziscímhez fűzve):
- `/customer/manageTradeCards` — bejelentések kezelése (create / modify / delete / finalize / correction)
- `/customer/queryTradeCards` — bejelentések lekérdezése
- `/customer/validateTradeCardRequest` — validáció (a create-et küldjük rá)

## Üzenet-szerkezet

Minden request a `BasicRequestType`-ból származik: `header` + `user` + payload.

```
manageTradeCardsRequest
├── header (BasicHeaderType)
│     requestId       – user-enként egyedi (egy requestId csak EGYSZER); pattern [+a-zA-Z0-9_/=]{1,50}
│     timestamp       – xs:dateTime; max 24h régi, jövőbeni tiltott, ±5 perc tűrés. IDŐZÓNÁT adj meg!
│     requestVersion  – interfész-verzió (pl. "2.2")
│     headerVersion   – default "1.0"
├── user (UserHeaderType)
│     user             – login név (6–30 char)
│     passwordHash     – lásd lent
│     VATNumber        – az adószám ELSŐ 8 SZÁMJEGYE
│     requestSignature – lásd lent
└── tradeCardOperations / queryParams …
```

## Authentikáció — a két hash (KRITIKUS)

Mindkettő **SHA-512**, **nagybetűs hex** (128 karakter). Az encoding UTF-8.

### 1) passwordHash
```
passwordHash = SHA-512(jelszó)        // a NYERS jelszó hash-e, NEM a kódolatlan jelszó!
```

### 2) requestSignature
A három érték **összefűzésének** SHA-512 hash-e, ebben a sorrendben:
```
requestSignature = SHA-512( requestId + timestampUTC + signingKey )
```
- `timestampUTC` = a header `timestamp` **UTC-megfelelője**, `yyyyMMddHHmmss` formátumban (elválasztó nélkül).
- `signingKey` = a felhasználó titkos **XML kommunikációs kulcsa** (6–15 char, a weben állítja be; az XML-ben NEM szerepel).

> ⚠️ **Időzóna-csapda:** a header `timestamp` lehet bármilyen időzónában, de a hash-hez **mindig az UTC** kell.
> Ezért a `timestamp`-be **mindig adj időzónát** (pl. `Z`), különben a szerver a saját helyi idejének veszi → az aláírás nem egyezik.

### Hivatalos teszt-vektor (a PDF-ből — egyben unit-test alapanyag)
```
requestId   = TSTKFT1222564
timestamp   = 2015.01.15T13:25:45+01:00   → UTC: 20150115122545
signingKey  = Elek65Titkos
összefűzve  = TSTKFT122256420150115122545Elek65Titkos
SHA-512     = AF84DC456B82234E67550C80169E517FBDAB4403607293985DECB09F534D9F73FADAABEFEE932554FABBC49F6E8F74A5DD54EA359D6B7644D95CFF3530AFB889
```

## Műveletek (`tradeCardOperations` → `operation`)

| Operation | Jelentés |
|---|---|
| `Create` | bejelentés rögzítése (a `tcn` elemet EL kell hagyni) |
| `Modify` | bejelentés módosítása |
| `Delete` | bejelentés törlése (csak aktív állapotban) |
| `Finalize` | bejelentés véglegesítése (a rendszám + érkezési dátum kötelező előtte) |
| `Correction` | lezárt bejelentés utólagos módosítása |

## Trade card státusz-életciklus (`TradeCardStatusType`, common.xsd)

```
P (Prepare) ──► S (Start, úton) ──► F (Finalized, lerakva, VÉGÁLLAPOT)
│
├──► D (Deleted)   – csak P-ből
└──► I (Inactive)  – ha időben nem véglegesedik (más állapotokból)
```

## Válasz (`result`, minden válaszban)

| Mező | Érték |
|---|---|
| `funcCode` | `OK` / `WARNING` / `ERROR` |
| `reasonCode` | enum (a teljes lista a `common.xsd` `ReasonCodeType`-jában, ~150 `TC_*`/`TCI_*` kód) |
| `msg` | szöveges leírás (jellemzően hibánál) |

## C# leképezés (ebben a repóban)

| EKÁER fogalom | Hol |
|---|---|
| `passwordHash`, `requestSignature` algoritmus | `Nav/NavAuthHelper.cs` |
| send-flow (POST + (de)szerializál + ellenőrzés) | `Nav/NavReportServiceBase.cs` |
| `header`/`user`/`result` közös szerződés | `Nav/NavInterfaces.cs` (`INavRequestHeader`, `INavUserHeader`, `INavResult`) |
| generált modellek | `Nav/Ekaer/Models/` (`xscgen` az `ekaermanagement.xsd`-ből) |