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:
- EMCS-järjestelmä
- Mikä on Valmisteveron alaisten tuotteiden siirtojärjestelmä (EMCS)?
- Lisätietoa EMCS-järjestelmästä ja määrityksistä EU-komission sivuilla
- Lisätietoa EU-komission tekemistä EMCS-järjestelmän määrityksistä: Download the latest version of FESS