A requestID-nak adózóként kell egyedinek lennie. Ennek biztonságtechnikai oka van.
Az API nem SOAP protokolt használ, így WSDL sincs hozzá. Az üzenetek szerkezete azonban validálható az elérhető XSD alapján.
A mezőben átadott értékek 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ában (UTC-ben!): yyyyMMddHHmmss. pl.: 2014.10.05 12:58:08 formája: 20141005125808. NAGYON 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 WEB-en minden felhasználó magának tudja beállítani. Legalább 8 hosszú titkos jelszó, aminek tartalmaznia kell kis és nagybetűt, valamint számot! pl.: titkos7Password98. Akinek nincs beállítva az aláíró kulcsa, az nem tudja használni az XML-es interface-eket!
Példa:
A példában használt testelek user titkos aláíró kulcsa (amit ő maga állított be a WEB-es 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 element-ben 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! 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: AF84DC456B82234E67550C80169E517FBDAB4403607293985DECB09F534D9F73FADAABEFEE932554FABBC49F6E8F74A5DD
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ő.
Az üzenetek pontos szerkezete elérhető XSD séma-definició formában a dokumentáció menüpont alatt. Az egyes mezők részletes bemutatása a specifikációban található.
Az EKÁER rendszerbe elsődleges felhasználóként az Ügyfélkapun keresztül tudnak belépni az eljárásra jogosult személyek. Az EKÁER rendszeren belül ezzel a hozzáféréssel a bejelentés kötelezettje további, másodlagos felhasználókat tud felvinni, melyel felhatalmazást adhat másoknak a bejelentés elvégzésére. Az informatikai rendszerek fejlesztőit is ilyen módon lehet felhatalamazni, hogy a bejelentés kötelezettjének nevében járhassanak el.
Minden kérésnek van egy fejléc része, mely tartalmazza azon felhasználó nevét és jelszavának hash-kulcsát, mely 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.
WEB-es felületen is feltölthető a dokumentumban ismertetett XML struktúra a felhasználók által, bejelentkezés után! Az EKAER WEB-es felületen külön funkció van az xml file feltöltésére, aminek hatására egy XML válasz file letöltése indul be! A letöltött file-ban a dokumentációban definiált válasz XML lesz.
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
XML feltöltésének két módja van:
- XML API-n keresztül automatikus, gép-gép kommunikációhoz
- A webes felületen történő feltöltés a kézi kezeléshez. Az EKAER WEB-es felületen külön funkció van az xml file feltöltésére, aminek hatására egy XML válasz file letöltése indul be! A letöltött file-ban a dokumentációban definiált válasz XML lesz.
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ó a 1.0.1g.
Kérjük, írjon egy levelet a Levél küldése a NAV-nak oldalon a következő adatokkal:
- Cégnév
- Telefonszám
- Cím
- E-mail cím
- Adószám
Az interfész szinkron működik és az összes vizsgálat tranzakcionálisan fut. Ennek megfelelően egy bejelentés létrehozása kérésre a 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üzenet kerül visszaadásra.