AyCode.Core/AyCode.Services/Nav/docs/EKAER_INTERFACE.md

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

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)