7.3 KiB

Raw Blame History

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

Forrás: eKAERManagementService_2.2.pdf + ekaermanagement.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:

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

7.3 KiB Raw Blame History Unescape Escape