Technikai kérdések

A kommunikáció HTTP(S) protokolon történik, POST típusú (method) üzenet küldésével. A kérés a POST üzenet body részében küldendő XML-adat. A válasz ehhez hasonlóan a válasz body részében lévő XML.

Az eKÁER-rendszer jelenleg a TLS 1.2-es verziót támogatja.
Támogatott algoritmusok:
TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384

OpenSSL használata esetén a minimum támogatott verzió az 1.0.1g.

Az üzenetek pontos szerkezete elérhető XSD-sémadefiníció formában a Dokumentáció menüpont alatt. Az egyes mezők részletes bemutatása a specifikációban található.

Az XML feltöltésének két módja van:

  • XML API-n keresztül automatikus, gép–gép kommunikációhoz.
  • Feltöltés a webes felületen a kézi kezeléshez. Az eKÁER webes felületen külön funkció van az XML-fájl feltöltésére. A feltöltés után egy XML-válaszfájl letöltése következik. A letöltött fájlban a dokumentációban definiált válasz-XML lesz.

Az éles rendszer eléréséhez a HTTP POST üzeneteket a  https://import.ekaer.nav.gov.hu/TradeCardManagementService/customer/{OPERATION} címre kell küldeni, ahol az {OPERATION} a kívánt műveletre cserélendő.

Bejelentkezés után a webes felületen is feltölthető a dokumentációban ismertetett XML-struktúra. A felületen külön funkció van az XML-fájl feltöltésére, melynek megtörténte után egy XML-válaszfájl letöltése következik. A letöltött fájlban a dokumentációban definiált válasz-XML lesz.

Az API nem SOAP protokolt használ, így WSDL sincs hozzá. Az üzenetek szerkezete azonban validálható az elérhető XSD alapján.

Az eKÁER-be elsődleges felhasználóként az Ügyfélkapun keresztül tudnak belépni az eljárásra jogosult személyek. Az eKÁER-en belül ezzel a hozzáféréssel a bejelentés kötelezettje további, másodlagos felhasználókat tud felvinni, mellyel felhatalmazást adhat másoknak a bejelentés elvégzésére. Az informatikai rendszerek fejlesztőit is ilyen módon lehet felhatalmazni, hogy a bejelentés kötelezettjének nevében járhassanak el.

Kérjük, írjon egy e-mailt az ekaer-support@icellmobilsoft.hu címre a következő adatokkal.

  • Cégnév
  • Telefonszám
  • Cím
  • E-mail-cím
  • Adószám

Az interfészszinkron működik és az összes vizsgálat tranzakcionálisan fut. Ennek megfelelően egy bejelentés létrehozása kérésre érkező válasz – a megfelelő validálás és a szükséges biztosítékok foglalása után – a generált eKÁER-számot tartalmazza. Amennyiben a validáció sikertelen, vagy a biztosíték foglalása nem lehetséges, hibaüzenetet ad vissza a rendszer.

A request ID-nak adózóként kell egyedinek lennie. Ennek biztonságtechnikai oka van.

A HTTP POST üzeneteket a
https://import.ekaer.nav.gov.hu/TradeCardManagementService/customer/{OPERATION} 
címre kell küldeni, ahol az {OPERATION} a kívánt műveletre cserélendő.

A teszt rendszer esetén az üzeneteket a https://import-test.ekaer.nav.gov.hu/TradeCardManagementService/customer/{OPERATION} címre kell küldeni.

Példa HTTP header:

POST https://import.ekaer.nav.gov.hu/TradeCardManagementService/customer/manageTradeCards

Accept: text/xml

Content-Type: text/xml

Minden kérésnek van egy fejléc része, mely tartalmazza azon felhasználó nevét és jelszavának hash-kulcsát, amelynek nevében a kérés érkezik, továbbá egy aláíró kulcsot, melyhez a kérés azonosítóját és a felhasználó aláírókulcsát kell használni. A fejléc szerkezetéről a dokumentáció tartalmaz részletes leírást.

A mezőben átadott érték a következő szöveges értékek összefűzéséből kapott szöveg SHA-512 hash- értéke:

  • requestId
  • timestamp mező a következő formátumban (UTC-ben): yyyyMMddHHmmss. pl.: 2014.10.05 12:58:08 formátuma: 20141005125808. Fontos, hogy az aláírás hash generálásnál a Timestamp-ben küldött idő UTC megfelelőjét kell használni!
  • A user titkos aláírókulcsa. Ezt a jelszószerű adatot a weben minden felhasználó magának tudja beállítani az XML kommunikációs kulcs elnevezésű mezőben. Legalább 6, legfeljebb 15 karakter hosszúságú lehet a titkos jelszó. Akinek nincs beállítva az XML kommunikációs kulcsa, az nem tudja használni az XML-es interfészeket!

Példa:

A példában használt user XML kommunikációs kulcsa (amit ő maga állított be a webes felületen): Elek65Titkos

A példa-request adatai:

  • requestId = TSTKFT1222564
  • timestamp = 2015-01-15T13:25:45+01:00 ebből a hash-hez használt érték: 20150115122545

XML-ben a timestamp elemben mindegy milyen időzónában van megadva az idő, a hash gyártásnál viszont mindig ennek az időnek az UTC-ben vett megfelelőjét kell használni! Az XML-ben a timestamp mező xs:dateTime típusú, aminek az egyik sajátossága, hogy ha nincs időzóna a szöveges formában utazó időn (pl: 2015-01-15T13:25:45), akkor azt a szerver a saját időzónájában értelmezett helyi időnek tekinti. Célszerű minden esetben megadni az időzónát, mert előfordulhat, hogy a szerver időzónája más, mint a küldő rendszeré, és ebben az esetben az aláíró hash-hez használt UTC idő nem fog egyezni, ebből kifolyólag az aláírást érvénytelennek tekintheti a szerver.

A szöveges érték, amelyből a hash készül, így épül fel:

TSTKFT1222564 + 20150115122545 + Elek65Titkos= TSTKFT122256420150115122545Elek65Titkos

Az így előállt („TSTKFT122256420150115122545Elek65Titkos”) szövegnek az SHA-512 hash értéke ez lenne: AF84DC456B82234E67550C80169E517FBDAB4403607293985DECB09F534D9F73FADAABEFEE932554FABBC49F6E8F74A5