DHX

Dokumendivahetusprotokoll DHX

Lisa 1 sendDocument spetsifikatsioon

Päring võimaldab saata dokumente kasutades DHX protokolli.

Päringu parameeter documentAttachment viitab SOAP swaRef manusele, milles on edastatava dokumendi kapsel XML kujul (vt [PR-MESS]). Päring aktsepteerib manusena DHX protokollis spetsifitseeritud Kapsli versiooni.

Päringu vastuses tagastatakse dokumendi vastuvõtmisel genereeritud unikaalne id.

Päringu X-tee versioon 6 täisnimi on formaadis:

<xRoadInstance>/<memberClass>/<memberCode>/DHX/sendDocument

Näiteks EE/GOV/<registrikood>/DHX/sendDocument või EE/COM/<registrikood>/DHX/sendDocument

Päringu WSDL kirjeldus

Päringu WSDL kirjeldus asub siin.

Päringu sisend

Päringu sisendi parameetrid Body/sendDocument XML elemendi sees:

nimetus	kirjeldus	väärtuse tüüp	väärtuse näide	kohustuslik
DHXVersion	Kasutatav DHX protokolli versioon. Päringu saatja annab teada, millise DHX protokolli versiooni kohaselt päring on moodustatud. Vastuvõttev süsteem PEAB kontrollima parameetri DHXVersion olemasolu. Vastuvõttev süsteem PEAKS versiooninumbri alusel otsustama, kas suudab päringsõnumit töödelda ja suutlikkuse puudumisel päringu tagasi lükkama.	String, mis sisaldab versiooni numbrit semantilise versioneerimise (vt nt http://semver.org/) vormingus ja tähenduses	“1.0”	jah
recipient	Vahendatava asutuse registrikood. PEAB olema täidetud juhul kui dokument edastatakse vahendatavale asutusele. Kui toimub DHX otsevõimekusega asutusele saatmine, siis parameeter PEAB olema tühi.	String	10560025	ei
recipientSystem	Vahendatava asutuse süsteemi nimi, kuhu vahendaja süsteem peab dokumendi edastama. Mõeldud täiendava adresseerimisvahendina. Väärtuseks võib olla X-tee alamsüsteemi nimi või mõni muu infosüsteemi nimi.	String	system	ei
documentAttachment	Edastatava Kapsli XML dokument swaRef manuse viitena. Manuse `Content-Transfer-Encoding` PEAB olema `base64`. Manuse `Content-Type` PEAB olema: `text/xml; charset=UTF-8`.	ref:swaRef	cid:kapsel.xml	jah
consignmentId	Saadetise id. PEAKS olema unikaalne ühe saatja saadetiste piires. Juhul kui saatmise ebaõnnestumisel edastatakse dokument korduvalt, siis consignmentId PEAB jääma samaks. Vastuvõttev süsteem PEAKS kontrollima, kas sellise saadetise id-ga dokument on talle juba saabunud – unikaalne on X-tee päringus saabunud parameetrite kombinatsioon: `Header/client: EE/MEMBERCLASS/ MEMBER1/SUBSYSTEM1` + `Body/sendDocument/consignmentId: <consignmentId>`. Kui sama saadetis on juba saabunud ja vastu võetud, siis vastuvõttev süsteem PEAB väljastama vea koodiga `DHX.Duplicate` (vaata allpool “Veakoodid”). Siin “PEAKS” tähendab unikaalsuse kontrollimist mõistliku ajaraami piires (1 nädal või 1 kuu). Vanemate saadetiste korral VÕIB vastuvõtja süsteem talle saabunud saadetiste ID-de logi kustutada või arhiveerida.	String	97522b98-cf27-452e-…	jah

Lisaks ülalnimetatud parameetritele VÕIB saatev süsteem kasutada Body/sendDocument XML elemendis muid parameetreid.

Vastuvõttev süsteem PEAB päringu töötlemisel parameetrid, millest ta aru ei saa, vahele jätma.

Päringu väljund

Kui vastuvõtja DHX süsteemis ilmnes ootamatu tehniline viga, siis PEAB tagastama SOAP Fault vea või madalama taseme protokoli veana (näiteks HTTP response code).

Kui vastuvõtja süsteem suutis SOAP paringu sisu avada, aga hilisemal DHX protokolli reeglite järgi valideerimisel tekkis viga, siis PEAB tagastama sendDocument päringu vastusena Body/sendDocumentResponse/fault XML elemendi sees (Vaata allpool “Veakoodid”).

Väljundparameetrid Body/sendDocumentResponse XML elemendi sees:

nimetus	kirjeldus	väärtuse tüüp	väärtuse näide	kohustuslik
receiptId	Vastuvõtva süsteemi poolt genereeritud unikaalne vastuse id või number. Kui vastuvõttev süsteem võttis saadetise vastu, siis `receiptId` PEAB olema täidetud ja `fault` element peab olema puudu või tühi. Kui ilmnes äriloogikaline viga või vastuvõtja lükkas dokumendi tagasi ja viga tagastatakse `fault` elemendis, siis `receiptId` PEAB olema tühi. `receiptId` ei pea olema dokumendi id ega number, sest vastuvõtja võib saadetisest dokumendi genereerida hiljem asünkroonselt. Saatja süsteem VÕIB vastuses saabunud `receiptId` salvestada või logida, selleks et hiljem oleks võimalik probleemide analüüs.	String	f5f28c9a-35d5-44bd-a012-…	ei
fault	Vea konteiner. Olemas, kui tekkis viga dokumendi vastuvõtmisel. Mõeldud näiteks valideerimise vigade jaoks. Ootamatu tehnilise vea korral PEAB tagastama `SOAP:Fault`.			ei
faultcode	Vea kood. Kui ilmnes äriloogikaline viga või vastuvõtja lükkas dokumendi tagasi, siis viga PEAB olema tagastatud `fault` elemendis ning `faultcode` PEAB olema väärtustatud.	String	Client.Validation	jah
faultstring	Vea kirjeldus. PEAKS sisaldama `faultcode` väärtusele täiendavat infot, näiteks mis XML element või adressaat ei valideerunud vms.	String	Container is invalid	jah

Lisaks ülalnimetatud parameetritele VÕIB vastussõnumi XML elemendis Body/sendDocument kasutada muid parameetreid.

Vastussõnumit töötlev süsteem PEAB sõnumi töötlemisel parameetrid, millest ta aru ei saa, vahele jätma.

Veakoodid

Vastuvõtja süsteem PEAB äriloogikalise või DHX protokolli reeglite vastu valideerimisel tekkinud vea tagastama sendDocuments vastuses, Body/sendDocumentResponse/fault XML elemendi sees, kasutades ühte järgmistest veakoodidest:

faultcode	kirjeldus	faultstring väärtuse näide
DHX.UnsupportedVersion	Vastuvõtja süsteem teatab saatjale, et ei toeta saatja poolt päringus näidatud protokolliversiooni	Version not supported
DHX.Duplicate	Samalt saatjalt saabus sama saadetise id väärtusega päring. Päringu parameetrite kombinatsioon `Header/client: EE/MEMBERCLASS/ MEMBER1/SUBSYSTEM1` + `Body/sendDocument/consignmentId: <consignmentId>` ei ole unikaalne.	Client sended duplicate document. Document with same consignmentId: 97522b98-cf27-452e-8… from EE/GOV/ MEMBER1/SUBSYSTEM1 is already received. Ignoring duplicate.
DHX.Validation	Kui DHX `sendDocuments` päringus saabunud Kapsli valideerimine vastu XML Schemat ebaõnnestub või SOAP päringu enda parameetrite sisu valideerimine ebaõnnestub, siis vastuvõttev süsteem PEAB väljastama vea `DHX.Validation`.	Container in documentAttachment is invalid. Required XML element “DecContainer/Transport” is missing. Container must validate against 2.1 schema.
DHX.InvalidAddressee	Kui vastuvõtva süsteemi enda registrikoodi või tema poolt vahendatava asutuse registrikoodi ei ole päringus saabunud Kapsli XML `DecContainer/Transport/DecRecipient/OrganisationCode` elementide väärtuste hulgas, siis vastuvõttev süsteem PEAB tagastama vea `DHX.InvalidAddressee`.	The container has unknown addressee 7000001.
DHX.SizeLimitExceeded	Kui vastuvõttev süsteem soovib seada limiidi enda poolt vastuvõetava dokumendi suurusele, siis suuremate dokumendi saabumisel VÕIB vastuvõttev süsteem tagastada vea `DHX.SizeLimitExceeded`. Selle vea tagastamine SOAP päringu vastusena ei tihtipeale tehniliselt võimalik, sest rakendusserverites on HTTP request liimit enamasti määratud globaalsel süsteemsel tasemel. Sel juhul enamasti rakendusserver vastab HTTP staatuskoodiga, näiteks `404.13` `content length too large`.	The server was not able to store the container because its bigger than server size limit (100Mb)

Näide

Päringu näide:

<?xml version="1.0" encoding="utf-8" ?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
  <SOAP-ENV:Header>
    <ns4:protocolVersion xmlns:ns2="http://dhx.x-road.eu/producer"
        xmlns:ns3="http://x-road.eu/xsd/identifiers" xmlns:ns4="http://x-road.eu/xsd/xroad.xsd"
        xmlns:ns5="http://www.riik.ee/schemas/deccontainer/vers_2_1/">4.0</ns4:protocolVersion>
    <ns4:id xmlns:ns2="http://dhx.x-road.eu/producer"
        xmlns:ns3="http://x-road.eu/xsd/identifiers" xmlns:ns4="http://x-road.eu/xsd/xroad.xsd"
        xmlns:ns5="http://www.riik.ee/schemas/deccontainer/vers_2_1/">64a3ddbd-1620-42c4-b2fe-60b854c2f32f</ns4:id>
    <ns4:client xmlns:ns2="http://dhx.x-road.eu/producer"
        xmlns:ns3="http://x-road.eu/xsd/identifiers" xmlns:ns4="http://x-road.eu/xsd/xroad.xsd"
        xmlns:ns5="http://www.riik.ee/schemas/deccontainer/vers_2_1/" ns3:objectType="SUBSYSTEM">
      <ns3:xRoadInstance>ee-dev</ns3:xRoadInstance>
      <ns3:memberClass>GOV</ns3:memberClass>
      <ns3:memberCode>40000001</ns3:memberCode>
      <ns3:subsystemCode>DHX</ns3:subsystemCode>
    </ns4:client>
    <ns4:service xmlns:ns2="http://dhx.x-road.eu/producer"
        xmlns:ns3="http://x-road.eu/xsd/identifiers" xmlns:ns4="http://x-road.eu/xsd/xroad.xsd"
        xmlns:ns5="http://www.riik.ee/schemas/deccontainer/vers_2_1/" ns3:objectType="SERVICE">
      <ns3:xRoadInstance>ee-dev</ns3:xRoadInstance>
      <ns3:memberClass>COM</ns3:memberClass>
      <ns3:memberCode>30000001</ns3:memberCode>
      <ns3:subsystemCode>DHX</ns3:subsystemCode>
      <ns3:serviceCode>sendDocument</ns3:serviceCode>
      <ns3:serviceVersion>v1</ns3:serviceVersion>
    </ns4:service>
  </SOAP-ENV:Header>
  <SOAP-ENV:Body>
    <ns3:sendDocument xmlns:ns2="http://www.riik.ee/schemas/deccontainer/vers_2_1/"
        xmlns:ns3="http://dhx.x-road.eu/producer" xmlns:ns4="http://x-road.eu/xsd/identifiers"
        xmlns:ns5="http://x-road.eu/xsd/xroad.xsd">
      <ns3:DHXVersion>1.0</ns3:DHXVersion>
      <ns3:consignmentId>fae1278b-9318-4b1c-9bea-49ccc6879055</ns3:consignmentId>
      <ns3:documentAttachment>cid:c48e2f41-3f53-4dc6-ae69-1d16a87682e2</ns3:documentAttachment>
    </ns3:sendDocument>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Manus:

------=_Part_12_1312957482.1467986355580
Content-Type: text/xml; charset=UTF-8
Content-ID: <c48e2f41-3f53-4dc6-ae69-1d16a87682e2>
Content-Transfer-Encoding: base64

PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiIHN0YW5kYWxvbmU9InllcyI/Pjxu
...
------=_Part_12_1312957482.1467986355580--

Vastuse näide:

<?xml version="1.0" encoding="utf-8" ?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
  <SOAP-ENV:Header>
    <ns4:protocolVersion xmlns:ns2="http://dhx.x-road.eu/producer"
        xmlns:ns3="http://x-road.eu/xsd/identifiers" xmlns:ns4="http://x-road.eu/xsd/xroad.xsd"
        xmlns:ns5="http://www.riik.ee/schemas/deccontainer/vers_2_1/">4.0</ns4:protocolVersion>
    <ns4:id xmlns:ns2="http://dhx.x-road.eu/producer"
        xmlns:ns3="http://x-road.eu/xsd/identifiers" xmlns:ns4="http://x-road.eu/xsd/xroad.xsd"
        xmlns:ns5="http://www.riik.ee/schemas/deccontainer/vers_2_1/">64a3ddbd-1620-42c4-b2fe-60b854c2f32f</ns4:id>
    <ns4:client xmlns:ns2="http://dhx.x-road.eu/producer"
        xmlns:ns3="http://x-road.eu/xsd/identifiers" xmlns:ns4="http://x-road.eu/xsd/xroad.xsd"
        xmlns:ns5="http://www.riik.ee/schemas/deccontainer/vers_2_1/" ns3:objectType="SUBSYSTEM">
      <ns3:xRoadInstance>ee-dev</ns3:xRoadInstance>
      <ns3:memberClass>GOV</ns3:memberClass>
      <ns3:memberCode>40000001</ns3:memberCode>
      <ns3:subsystemCode>DHX</ns3:subsystemCode>
    </ns4:client>
    <ns4:service xmlns:ns2="http://dhx.x-road.eu/producer"
        xmlns:ns3="http://x-road.eu/xsd/identifiers" xmlns:ns4="http://x-road.eu/xsd/xroad.xsd"
        xmlns:ns5="http://www.riik.ee/schemas/deccontainer/vers_2_1/" ns3:objectType="SERVICE">
      <ns3:xRoadInstance>ee-dev</ns3:xRoadInstance>
      <ns3:memberClass>COM</ns3:memberClass>
      <ns3:memberCode>30000001</ns3:memberCode>
      <ns3:subsystemCode>DHX</ns3:subsystemCode>
      <ns3:serviceCode>sendDocument</ns3:serviceCode>
      <ns3:serviceVersion>v1</ns3:serviceVersion>
    </ns4:service>
    <ns2:requestHash xmlns:ns2="http://x-road.eu/xsd/xroad.xsd"
        algorithmId="http://www.w3.org/2001/04/xmlenc#sha512">jHfl2GQ7wKXnroduhvIbf2AEoqN4wC0rrOtt8ECslDENjfz3NBSj4EIMYWs+B4bxoitwbVzjeiwByQPGZVtubQ==</ns2:requestHash>
  </SOAP-ENV:Header>
  <SOAP-ENV:Body>
    <ns3:sendDocumentResponse
        xmlns:ns2="http://www.riik.ee/schemas/deccontainer/vers_2_1/"
        xmlns:ns3="http://dhx.x-road.eu/producer" xmlns:ns4="http://x-road.eu/xsd/identifiers"
        xmlns:ns5="http://x-road.eu/xsd/xroad.xsd">
      <ns3:receiptId>89cf990b-0270-4592-bcb0-8f0c689de674</ns3:receiptId>
    </ns3:sendDocumentResponse>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Äriloogilise vea näide:

<?xml version="1.0" encoding="utf-8" ?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
	<SOAP-ENV:Header>
		<ns5:protocolVersion xmlns:ns2="http://dhx.x-road.eu/producer"
        xmlns:ns3="http://x-road.eu/xsd/identifiers" xmlns:ns4="http://www.riik.ee/schemas/deccontainer/vers_2_1/"
        xmlns:ns5="http://x-road.eu/xsd/xroad.xsd">4.0</ns5:protocolVersion>
		<ns5:id xmlns:ns2="http://dhx.x-road.eu/producer" xmlns:ns3="http://x-road.eu/xsd/identifiers"
        xmlns:ns4="http://www.riik.ee/schemas/deccontainer/vers_2_1/"
        xmlns:ns5="http://x-road.eu/xsd/xroad.xsd">d8be2b7d-25fc-4cce-88b9-09c7dfc78282</ns5:id>
		<ns5:client xmlns:ns2="http://dhx.x-road.eu/producer"
        xmlns:ns3="http://x-road.eu/xsd/identifiers" xmlns:ns4="http://www.riik.ee/schemas/deccontainer/vers_2_1/"
        xmlns:ns5="http://x-road.eu/xsd/xroad.xsd" ns3:objectType="SUBSYSTEM">
			<ns3:xRoadInstance>ee-dev</ns3:xRoadInstance>
			<ns3:memberClass>GOV</ns3:memberClass>
			<ns3:memberCode>40000001</ns3:memberCode>
			<ns3:subsystemCode>DHX</ns3:subsystemCode>
		</ns5:client>
		<ns5:service xmlns:ns2="http://dhx.x-road.eu/producer"
        xmlns:ns3="http://x-road.eu/xsd/identifiers" xmlns:ns4="http://www.riik.ee/schemas/deccontainer/vers_2_1/"
        xmlns:ns5="http://x-road.eu/xsd/xroad.xsd" ns3:objectType="SERVICE">
			<ns3:xRoadInstance>ee-dev</ns3:xRoadInstance>
			<ns3:memberClass>GOV</ns3:memberClass>
			<ns3:memberCode>40000001</ns3:memberCode>
			<ns3:subsystemCode>DHX</ns3:subsystemCode>
			<ns3:serviceCode>sendDocument</ns3:serviceCode>
			<ns3:serviceVersion>v1</ns3:serviceVersion>
		</ns5:service>
		<ns2:requestHash xmlns:ns2="http://x-road.eu/xsd/xroad.xsd"
			algorithmId="http://www.w3.org/2001/04/xmlenc#sha512">zyZ4mOoJae9miQoWjVpp70TDjsfBJBWOoBoY08tTTpnA7MhYRrs7IPieqlaifWGTe+J4X7TWTS1VJvRw+e+B0A==</ns2:requestHash>
	</SOAP-ENV:Header>
	<SOAP-ENV:Body>
		<ns3:sendDocumentResponse
        xmlns:ns2="http://www.riik.ee/schemas/deccontainer/vers_2_1/"
        xmlns:ns3="http://dhx.x-road.eu/producer" xmlns:ns4="http://x-road.eu/xsd/identifiers"
        xmlns:ns5="http://x-road.eu/xsd/xroad.xsd">
			<ns3:fault>
				<ns3:faultCode>DHX.InvalidAddressee</ns3:faultCode>
				<ns3:faultString>DHXException code: DHX.InvalidAddressee Recipient
					not found in capsule recipient list. recipient:40000001</ns3:faultString>
			</ns3:fault>
		</ns3:sendDocumentResponse>
	</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Tehnilise vea näide:

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
	<SOAP-ENV:Body>
		<SOAP-ENV:Fault>
			<faultcode>Server.TechnicalError</faultcode>
			<faultstring>Technical error occured while processing request. </faultstring>
			<faultactor />
			<detail>
				<faultDetail>More detail aboout error.</faultDetail>
			</detail>
		</SOAP-ENV:Fault>
	</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

This site is open source. Improve this page.