EMCS-järjestelmän rajapinnat ovat Vero API -rajapintapalvelussa

EMCS-järjestelmä (Excise Movement and Control System) on EU-maiden välillä toimiva sähköinen tiedonvaihtojärjestelmä. Järjestelmällä ilmoitetaan ja valvotaan EU:ssa yhdenmukaistetun valmisteveron alaisten tuotteiden eli alkoholin, alkoholijuomien, tupakan ja nestemäisten energiatuotteiden siirtoja. Yritys ilmoittaa ko. tuotteiden siirrot OmaVerossa tai API-rajapinnan kautta. Suomen sisäisissä siirroissa EMCS:n käyttö ei ole pakollista.

Muutoksia EMCS-rajapintoihin

Huomaa! Hollannin lakimuutosten vuoksi 1.1.–13.2.2024 DegreePlatoa ei voida antaa oluttuotteelle (B000), kun kohdemaa on Hollanti (NL).

EMCS-rajapintoihin tulee seuraavia muutoksia 13.2.2024 alkaen:

  • IE801 Hae vahvistettu e-AD/e-SAD ja
  • IE815 Lähetä e-AD/e-SAD -luonnos
    • Vastaanottajan nimi- ja osoitetiedot (ConsigneeTrader) vaaditaan, kun vientimenettelyyn saapuva jäsenvaltio on Suomi (DestinationType = 6).
    • DegreePlato voidaan antaa valinnaisena tietona oluttuotteelle (B000), vaikka kohdemaa ei sitä vaatisi.
    • Uusi kenttä pientuottajatiedon antamiseen (IndependentSmallProducersDeclaration)
      Tämä vaikuttaa olemassa olevien Alkuperäselvitys (DesignationOfOrigin) ja Tuottajan koko -kenttien (SizeOfProducer) vaatimuksiin. Katso parametrien kuvaukset.
  • IE813 Lähetä määränpään muutos
    • Vastaanottajan nimi- ja osoitetiedot (ConsigneeTrader) vaaditaan, kun vientimenettelyyn asettamisjäsenvaltio on Suomi (DestinationType = 6).
  • IE801 Hae e-AD/e-SAD
    • Uusi kenttä pientuottajatiedon antamiseen: IndependentSmallProducersDeclaration.

Vientiin liittyvät uudet sanomat:

  • IE829–v2 Hae vientimenettelyyn hyväksymisen tiedot:
    • IE829 APIn uusi versio (versio 2) julkaistaan ​​13.2.2024.
    • IE829 APIn versiota 1 ei voi enää käyttää 13.2.2024 alkaen.
    • Kun e-AD:n tiedot on haettu IE829–v2 APIn kautta, e-AD:n tilaksi pitää vaihtaa Hyväksytty vienti-ilmoitus
    • kun ExportDeclarationAcceptanceOrGoodsReleasedForExport = 0). Kun tietoa samasta e-AD:sta on haettu toisen kerran IE829–v2 APIn kautta, e-AD:n tilaksi pitää vaihtaa Exporting (kun ExportDeclarationAcceptanceOrGoodsReleasedForExport = 1.
  • IE836 Hae viennin luovutuksen mitätöintitiedot
    • Uusi sanomatyyppi on lisätty. Tämä sanoma sisältää tietoja vienti-ilmoituksen mitätöimisestä. Kun e-AD:n tiedot on haettu IE836 API:n kautta, e-AD:n tilaksi pitää muuttaa Hyväksytty ja lähettää joko uusi vienti-ilmoitus tullijärjestelmässä, peruutus (IE810) tai Määräpaikan muutos (IE813).
  • IE839 Hae viennin luovutuksen epäämistiedot
    • Uusi sanomatyyppi on lisätty. Tämä sanoma sisältää tietoja viennin epäämisestä. Kun tiedot on haettu e-AD:sta IE839 APIn kautta, e-AD:n tilaksi pitää muuttaa Hyväksytty ja lähettää joko uusi vienti-ilmoitus tullijärjestelmässä, peruutus (IE810) tai Määräpaikan muutos (IE813).
  • Huom. Kun saat notifikaation IE829–v2-, IE836- tai IE839-tyyppisestä sanomasta on suositeltavaa kutsua kutakin IE829–v2-, IE836- ja IE839 Get API -rajapintaa ilmoituksen sisältämällä URI-arvolla. Järjestä sen jälkeen näiltä rajapinnoilta vastaanotetut sanomat päivämäärän ja kellonajan mukaan ja päivitä e-AD:n tilat yllä olevien ohjeiden mukaisesti määrittääksesi e-AD:n historian ja nykyisen tilan. Käytä seuraavia parametreja sanomien lajitteluun:
    • IE829–v2: DateAndTimeOfIssuance
    • IE836:  ReturnReceivedDate
    • IE839: DateAndTimeOfIssuance

Sanomien kuvaukset ovat hiekkalaatikossa: APIs: Details - Vero API Sandbox - developer portal

Uudet EMCS-APIt ja vanhojen APIen muutokset julkaistaan Vero API-portaalissa sekä Vero API -hiekkalaatikossa. Sieltä voit tarkistaa muun muassa muuttuneet kentät ja skeemat.

Suorasanoma-asiointi on Json-muodossa

EMCS-järjestelmän asiakasrajapinta on Verohallinnon API -rajapintapalvelussa.
API-rajapinnat ovat reaaliaikaisia Rest API -rajapintoja, joissa sanomamuotona on Json.

EMCS-sanomaliikenne ja tietosisältövaatimukset perustuvat EU-komission tekemiin EMCS-järjestelmän määrityksiin. Vero API -rajapinnat ovat Json-muotoisia.

Lisätietoa EMCS-järjestelmästä ja määrityksistä EU-komission sivuilla.

Käyttöönotossa huomioitavaa

Ennen käyttöönottoa rajapintojen käyttäjän on hankittava tuotantovarmenne. EMCS-rajapintoja käyttävä ohjelmisto pitää rekisteröidä API-portaalissa ja rakentaa ohjelmistoon API-avaimen käsittely. Jos ohjelmistoon otetaan käyttöön uusia EMCS-rajapintoja, ne pitää valita API-portaalissa ja testata siellä ennen käyttöönottoa.

Katso lisätietoja Vero API -rajapintojen käyttöönotosta tuotantoympäristössä.

Rajapintojen kuvaukset

Sanomakuvaukset on julkaistu Vero API -hiekkalaatikossa sekä Vero API-portaalissa. Rajapintojen testiversiot hiekkalaatikossa eivät sisällä rajapinnassa sanomasisältöön liittyvien tarkistussääntöjen validointia. Validoinnit sisältävät testiversiot ovat käytettävissä API-portaalissa julkaistuissa testiosoitteissa.

Notifikaatiopalvelu

Yritys voi ottaa ohjelmistoonsa käyttöön notifikaatiopalvelun (Notification Service API). Notifikaatiopalvelun avulla yritys saa tiedon saapuneista EMCS-sanomista. Notifikaatio sisältää avaintiedot, jonka perusteella ohjelmisto voi hakea varsinaiset EMCS:ään liittyvät tietosisällöt.

Notifikaatiot haetaan kyselyrajapinnasta

Ohjelmiston pitää kysellä notifikaatiopalvelussa notifikaatioita Verohallinnon rajapinnasta, sillä notifikaatiopalvelu ei ensimmäisessä vaiheessa lähetä tiedotteita ilman saapuvaa kyselyä. Helmikuussa 2024 palveluun on tulossa push notifikaatio -toiminto, jonka avulla ohjelmisto saa automaattisesti uusimmat notifikaatiot EMCS:stä.

Notifikaatiopalvelun kuvaukset on julkaistu Vero API -hiekkalaatikossa.

API-koodistot

EMCS-API -rajapinnoissa käytettävät koodistot voi hakea API-koodistot -rajapinnan kautta. Koodistorajapintaan voi tutustua Vero API -hiekkalaatikossa. API-koodistot löytyvät kategoriasta: General > Codes. Koodistot on julkaistu Vero API-hiekkalaatikossa ja API-portaalissa: Koodistot - API-portaali (vero.fi)

API-avain

Ohjelmistotalon tai ohjelmiston kehittäjän on rekisteröitävä rajapintoja käyttävä ohjelmisto Vero API -portaalissa. Ohjelmistokohtaista API-avainta edellytetään myös EMCS-rajapinnoissa käyttäjäkohtaisen varmenteen lisäksi. API-avain asetetaan rajapintakutsuissa vero-softwarekey-headeriin. 

Lisätietoa:

Sivu on viimeksi päivitetty 2.2.2024