1(6) Sanomaliikenne Suora sanoma-asiointi Muutokset suoran sanoma-asioinnin webservicepalvelun XML-schemoihin v.1.5 muutos 4.12.2010
2(6) SISÄLLYSLUETTELO 1 Johdanto... 3 2 Aikataulu ja yhteensopivuus... 3 3 Jakelupaketin sisältämät tiedostot... 3 4 CustomsCorporateService.wsdl... 4 4.1 Location... 4 5 ApplicationMessageTypes.xsd... 4 5.1 Reference... 4 5.2 ContentFormat... 5 5.2.1 ApplicationRequest... 5 5.2.2 ApplicationResponse... 5
3(6) 1 Johdanto Tässä dokumentissa kuvataan suoran sanoma-asioinnin webservice-palvelun XMLschemoihin versiossa 1.5 toteutetut muutokset. Kyseisiä XML-schemoja hyödyntävät suoran sanoma-asioinnin webservice-palvelua käyttävät sanomaliikenneasiakkaat. Tehdyt muutokset liittyvät sanoman lähetyskerran tunnisteen rajoituksiin, sekä sanoman tietosisällön tyyppiä kuvaavaan XML-elementtiin. Asiakkaan on välttämätöntä ottaa uudet XML-schemat käyttöön, mikäli asiakkaan suunnitelmissa on ryhtyä antamaan vienti-ilmoituksia ELEX-järjestelmään Tullin suoran sanoma-asioinnin webservice-palvelun kautta. 2 Aikataulu ja yhteensopivuus Tullin järjestelmiin toteutetut muutokset, jotka liittyvät suoran sanoma-asioinnin webservice-palvelun XML-schemaversioon 1.5, viedään tuotantoon 4.12.2010. Asiakas voi ryhtyä hyödyntämään muutosten mahdollistamia uusia toiminnallisuuksia haluamallaan aikataululla, kuitenkin aikaisintaan Tullin käyttöönottopäivämäärän jälkeen. Tässä päivityksessä tehdyt muutokset ovat taaksepäin yhteensopivia. Tuki aikaisemmalle schemaversiolle 1.1 jatkuu toistaiseksi. Asiakkaiden, jotka eivät tarvitse muutosten mahdollistamaa toiminnallisuutta, ei tarvitse ottaa käyttöön päivitettyjä XML-schemoja tässä vaiheessa. 3 Jakelupaketin sisältämät tiedostot Suoran sanoma-asioinnin webservice-palvelun XML-schemat toimitetaan jakelupakettina, joka on noudettavissa Tullin nettisivuilta seuraavasta osoitteesta: http://www.tulli.fi/fi/yrityksille/sahkoinenasiointi/ws/directmessageexchange_v1_5.zip Jakelupaketti sisältää seuraavat tiedostot: ApplicationMessageTypes.xsd ApplicationRequest.xsd ApplicationResponse.xsd CustomsCorporateService.wsdl EchoContent.xsd WsdlTypes.xsd xmldsig-core-schema.xsd Tämä jakelupaketti korvaa aikaisemman jakelupaketin kaikki tiedostot. Yhdenmukaisuussyistä jakelupaketin kaikissa tiedostoissa on päivitetty minor-versiotiedon attribuutiksi version="v1_5". Aikaisemman jakelupaketin tiedostoissa minor-versiotiedon attribuutti oli version="v1_1". Minkään namespacen major-versio ei muutu, arvona säilyy v1. Ainoastaan tiedostoihin CustomsCorporateService.wsdl ja ApplicationMessageTypes.xsd on tehty myös muita kuin kommentteihin ja versiotietoon liittyviä muutoksia. Muutokset on kuvattu seuraavissa osioissa.
4(6) 4 CustomsCorporateService.wsdl Tiedostoon CustomsCorporateService.wsdl on tehty yksi muutos, joka on kuvattu seuraavassa osiossa. 4.1 Location Suoran sanoma-asioinnin WSDL-määrityksessä XML-elementin address attribuutti location uudeksi arvoksi on asetettu asiakastestiympäristön osoite: <soap:address location="https://ws-customertest.tulli.fi/services/directmessageexchange" /> Muutoksen taustalla ovat vahinkotapaukset, joissa asiakkaat ovat testausvaiheessa yrittäneet kytkeytyä tuotannon osoitteeseen. Tuotannon osoite on yhä WSDL-määrityksessä kommenttina: <!-- <soap:address location="https://ws.tulli.fi/services/directmessageexchange" />--> Siirtyminen asiakastestiympäristöstä tuotantokäyttöön on mahdollista usealla vaihtoehtoisella tavalla. Ennen tuotantoon siirtymistä asiakas voi, muokkaamalla WSDL-tiedostoa, poistaa kommenttimerkit tuotannon osoitteen ympäriltä, ja kommentoida asiakastestin osoitteen pois käytöstä. Mahdollisesti asiakkaan ohjelmistossa tarvitaan myös muita toimenpiteitä, ennen kuin osoitteen muutos tulee voimaan. Suositeltavampi vaihtoehto on, että Tullin palvelun osoitteesta tehdään asiakkaan ohjelmiston konfiguroitava parametri. Tällöin asiakkaan on mahdollista säätää ohjelmiston käyttämää Tullin palvelun osoitetta ilman, että WSDL-tiedostoa muokataan. 5 ApplicationMessageTypes.xsd Tiedostoon ApplicationMessageTypes.xsd on tehty kaksi eri muutosta, jotka on kuvattu seuraavissa osioissa. 5.1 Reference XML-elementtityypin Reference minimipituus on laskettu 14:sta merkistä 6:een merkkiin. Muutoksen jälkeen elementtityypin rajoitukset ovat: <xs:restriction base="xs:string"> <xs:maxlength value="14"/> <xs:minlength value="6"/> </xs:restriction> Elementtityyppiä Reference käytetään lähetyskerran tunnisteena. Sen tietosisällössä viisi ensimmäistä merkkiä koostuvat Tullin antamasta nimilyhenteestä, esim. FIRMA. Loput merkit ovat asiakkaan päätettävissä; yleensä loppusisältönä käytetään juoksevaa numeroa. Muutos mahdollistaa juoksevan numeron käyttämisen ilman etunollia.
5(6) 5.2 ContentFormat XML-elementtityypin ContentFormat rajoituksia on muutettu. Aiemmin elementtityypin rajoitukset olivat: <xs:restriction base="xs:string"> <xs:minlength value="1"/> <xs:maxlength value="8"/> </xs:restriction> Muutoksen jälkeen elementtityypin rajoitukset ovat: <xs:restriction base="xs:string"> <xs:pattern value="application/xml application/pdf application/zip [Xx][Mm][Ll]"/> </xs:restriction> Elementtityypissä käytetään nyt arvoina MIME-mediatyyppejä, jotka kuvaavat XMLelementin Content tietosisältöä. Muutos liittyy uuteen toiminnallisuuteen, jossa Tullin asiakkaalle osoittaman XML-sanoman liitteenä voi olla ZIP-arkisto. Uutta toiminnallisuutta käyttävät Tullin järjestelmät, jotka lähettävät asiakkaalle ZIParkistoon pakattuina yhden tai useamman PDF-tiedoston. 5.2.1 ApplicationRequest Asiakkaan muodostama UploadRequest-sanomat sisältää ApplicationRequest-dokumentin. Dokumentti sisältää aina Tulliin välitettävän XML-sanoman base64-enkoodatttuna XMLelementin ApplicationContent alielementissä Content: <req:applicationcontent> <mess:content>base64-enkoodattu XML-sanoma</mess:Content> <mess:contentformat>application/xml</mess:contentformat> </req:applicationcontent> XML-elementissä ContentFormat asetetaan Tulliin välitettävän tietosisällön tyyppi. Asiakkaat voivat välittää Tulliin vain XML-muotoisia sovellussanomia, joten asiakkaan tulee aina asettaa XML-elementin ContentFormat arvoksi application/xml. Ennen tässä kuvattua muutosta, XML-elementin ApplicationContent alielementin ContentFormat ainoa sallittu arvo oli XML. Asiakkaiden on sallittua jatkaa arvon XML käyttöä toistaiseksi. 5.2.2 ApplicationResponse Tullin muodostama DownloadResponse-sanoma sisältää ApplicationResponse-dokumentin. Dokumentti sisältää aina Tullin XML-sanoman base64-enkoodattuna XML-elementin ApplicationResponseContent alielementissä Content: <resp:applicationresponsecontent> <mess:content>base64-enkoodattu XML-sanoma</mess:Content> <mess:contentformat>application/xml</mess:contentformat> </resp:applicationresponsecontent> Mikäli ApplicationResponse sisältää liitetiedoston, se on base64-enkoodattuna XMLelementin AttachmentOfApplicationResponseContent alielementissä Content: <resp:attachmentofapplicationresponsecontent> <mess:content>base64-enkoodattu ZIP-arkisto</mess:Content>
6(6) <mess:contentformat>application/zip</mess:contentformat> </resp:attachmentofapplicationresponsecontent> Tulli asettaa XML-sanoman MIME-mediatyyppiksi application/xml ja ZIP-arkiston sisältävän liitteen MIME-mediatyyppiksi application/zip.