GYIK

Amennyiben nem talált választ kérdéseire, kérjük küldjön egy e-mailt a ekaer-importor-teszt@virgo.hu címre!

 

Technikai kérdések (13)

Milyen módon történik a kommunikáció az interfésszel?

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.

Hol találom az üzenetek pontos leírását?

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

Milyen módon küldhető be XML a rendszerbe?

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.

Hol érhető el az éles EKÁER importőr interfész?

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

Miként tudok feltölteni XML-t a webes felületen?

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.

Elérhető WSDL az API-hoz?

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

Informatikai rendszer fejlesztőjeként milyen hozzáféréssel tudok eljárni a partnereim nevében?

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.

Szeretném elérni a teszt API interfészt! Mit tegyek?

Igényeljen hozzáférést!

Amennyiben a fenti hivatkozás nem megfelelően nyílik meg Önnek, kérjük írjon egy e-mailt a ekaer-importor-teszt@virgo.hu címre a következő adatokkal.

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

Szinkron vagy aszinkron az API működése? Mikor kapok EKÁER számot?

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.

A fejlécben a request ID-nek globálisan vagy beküldő szinten kell egyedinek lennie?

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

Milyen címre kell a kéréseket küldeni?

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

Miként azonosított a kérés küldője?

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.

Hogy épül fel az aláírás (requestSignature)?

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: AF84DC456B82234E67550C80169E517FBDAB4403607293985DECB09F534D9F73FADAABEFEE932554FABBC49F6E8F74A5DD54EA359D6B7644D95CFF3530AFB889

Működési kérdések (8)

EKAER-ben alkalmazott VTSZ törzsadatok

A rendszer használatának és a vonatkozó kötelezettségek előzetes ellenőrzésének megkönnyítéséhez publikálásra került az EKAER_TARIFA_TORZS_20160101.xlsx táblázat.

A táblázatban megtalálja a rendszer által elfogadható, érvényes

  • tarifaszámokat,

Ezúton hívjuk fel a figyelmet arra, hogy a tarifaszám megnevezése jellemzően nem egyezik meg a kereskedelmi forgalomban szokásos árumegnevezéssel!

A tarifális árumegnevezéseket a vám- és statisztikai nómenklatúráról, valamint a Közös Vámtarifáról szóló 1987. július 23-i 2658/87 EGK tanácsi rendelet – bejelentés időpontjában hatályos – I. számú melléklete (Kombinált Nómenklatúra) tartalmazza. Ennek megfelelően az áru tarifális besorolást minden esetben el kell végezni, és az áru pontos tarifális megnevezését pedig ellenőrizni kell. Ehhez támogatást (joganyagokat, KN és HR magyarázatokat, stb.) talál a TARICWEB-n, az alábbi elérhetőségen: http://kkk.nav.gov.hu/eles/1/taricweb/

A TARICWEB használatához felhasználói kézikönyvet talál az OPENKKK oldalon https://openkkk.nav.gov.hu/default.aspx a dokumentumtárban, melynek közvetlen elérése:
https://openkkk.nav.gov.hu/Dokumentumok/K%C3%A9zik%C3%B6nyvek/TARIC_Web_felhasznaloi_%20kezikonyv_%20v_4_2_20110511.pdf

  • biztosíték kötelezettséget: 0=NEM, 1 =IGEN

Az „Elektronikus Közúti Áruforgalom Ellenőrző Rendszer működésével összefüggésben a kockázatos termékek meghatározásáról” szóló NGM rendelet 1. illetve 2. sz. melléklete szerint kockázatosnak minősített termék (1=igen) esetén kockázati biztosíték fizetési kötelezettség áll fent, továbbá a terméket a Kombinált Nómenklatura szerint 8 hosszú vámtarifaszámig kötelező meghatározni a bejelentés során.

  • termék típusa: F = élelmiszer (FOOD), O = egyéb termék (OTHER)

A táblázatban megtekinthető, hogy a kockázatosnak minősített termék egyúttal kockázatos élelmiszernek is minősül-e (F=élelmiszer) vagy sem (O=egyéb termék). (ezek a rendelet 1. sz. melléklete alá sorolt áruk)

  • első betárolási hely kötelezettség: 0=NEM, 1 =IGEN

A NÉBIH felügyelet alá tartozó termékeknél, import esetén kizárólag olyan helyre történhet a betárolás, amely szerepel a NÉBIH első betárolási hely listáján. Az érintett termékek (1=igen) esetén megtörténik rögzített címadatnak a NÉBIH nyilvántartásával való összevetése.

  • FELIR szám kötelezettséget: 0=NEM, 1 =IGEN

A táblázatban megtekinthető, hogy a bejelentésre kötelezettnek mely termékek esetében kell rendelkeznie NÉBIH által kiadott FELIR azonosítószámmal (1=igen).

Milyen VTSZ számokat fogad el a tesztrendszer?

A tesztrendszer már a 2015-től érvényes VTSZ számokkal dolgozik, melyek listája letölthető innen (EKAER_TARIFA_TORZS_20160101.xlsx).

Csak az elsődleges felhasználónak vagy a másodlagos felhasználók számára is szükséges ügyfélkapus regisztráció?

A másodlagos felhasználók számára nem szükséges Ügyfélkapus regisztráció. Egyszerű felhasználónév és jelszó párossal tudnak belépni.

Ki módosíthatja a már beküldött bejelentést

A beküldött és még aktív állapotban lévő bejelentéseket a bejelentő adózó és annak nevében eljáró összes elsődleges vagy bejelentési jogosultággal rendelkező másodlagos felhasználó módosíthatja, törölheti vagy véglegesítheti. Emellett a bejelentésben megjelölt szállítmányozó is módosíthat néhány, csak szállítás alatt és után elérhető adatot, amennyiben a modByCarrierEnabled mező true értéket kap.

Milyen műveleteket végezhetek az API-n keresztül?

Az apin keresztül

  • létrehozható EKÁER bejelentés
  • törölhető, módosítható EKÁER bejelentés
  • véglegesíthető EKÁER bejelentés

Mi az API használatának folyamata?

A folyamat a következő

  • Export és belföldi szállítás esetén a szállító, vagy import esetén a megrendelő létrehozza a bejelentést a szállítás előtt. A bejelentés ekkor aktív státuszba kerül.
  • A szállító elvégzi a felrakodást és a végleges adatokat (szállító jármű adatai, végleges súly és érték) a megfelelő fél rögzíti a bejelentéshez
  • A szállítmány megérkezik és a lerakodás időpontját a megfelelő fél rögzíti majd véglegesíti a bejelentést.

A jogosult fél elsősorban a bejelentést kezdeményező fél, aki export és belföldi szállítás esetén a szállító/eladó, import esetén azonban a vevő.
Ettől eltérés kétféle esetben lehet:

  • modByCarrierEnabled és a carrier mező a bejelentésben kitöltésre került, úgy a szállítmányozó a saját hozzáférésével kitöltheti a hiányzó adatokat.

Miket tudok módosítani egy létrehozott, aktív bejelentésen?

Egy aktív státuszú bejelentés a következő adatok módosíthatóak

  • Tételek mennyiség, súly
  • Tételek értéke
  • Szállító jármű rendszáma, adatai
  • Lerakodási hely adatai
  • Saját megrendelési szám
  • Szállítmányozó
  • Módosíthat-e a szállítmányozó?

Az elérhető táblázatban szereplő VTSZ számot nem fogadja el a rendszer

Amennyiben egy VTSZ számhoz tartozó termék kockázatos, úgy a VTSZ számot 8 hosszan szükséges megadni. Amennyiben az elérhető táblázatban a VTSZ szám csak 4/6 hosszúságú, úgy azt 0 számjegyekkel szükséges kiegészíteni. Pl.: 030241 -> 03024100