# 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>
>
> **Verzió-állapot (2026-07-10, a NAV-oldalról ellenőrizve):** a **2.2 az aktuális** interfész-verzió, újabb nincs bejelentve. A NAV a 2.2 dokumentációt **2025-05-14-én frissítette** („Lejárt jelszó kezelése" — `EXPIRED_PASSWORD` eset viselkedése). **A helyi PDF EZ a friss kiadás** (byte-azonos méret az online-nal, letöltve 2026-06-01) — nem kell újra letölteni.

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

## 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: <https://ekaer.nav.gov.hu/faq/>, 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.

### Teszt-környezet — külön belépés + technikai felhasználó (2026-07, gyakorlatból)

A **TESZT-rendszer credentialjai NEM a saját portál-belépési adatok** (a személyes Ügyfélkapu/EKÁER login a teszt-API-hoz `InvalidUserOrPassword`-öt ad). A menet:
1. **Teszt-hozzáférés igénylése** a NAV-nál (Kapcsolatfelvétel → „EKÁER, Informatikai problémák"; a levélben: cégnév, adószám, cím/telefon, e-mail) → a NAV e-mailben küld **kifejezetten generált teszt-belépést**.
2. A teszt-felületen a profilban **technikai felhasználó + kulcsok** generálása: `username` (technikai user, NEM a személyes login), `password`, **XML aláírókulcs** (`signingKey`).
3. A `taxNumber` a **teszthez regisztrált cég** adószámának első 8 jegye.

Ezek kerülnek az `INavCredentials`-be (a fogyasztónál: `Ekaer:Credentials`). A `BaseUrl` a teszt-hoszt (pl. `https://import-test.ekaer.nav.gov.hu`). **Endpoint:** `{BaseUrl}/TradeCardManagementService/customer/{művelet}` — a művelet-utat a kód fűzi.

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