Data exchange system X-road interface: Difference between revisions
(Created page with "{| align="right" | border|30px eesti keeles |} = Overview = '''POSR''' is a data exchange system, through...") |
No edit summary |
||
(10 intermediate revisions by 2 users not shown) | |||
Line 1: | Line 1: | ||
{| align="right" | {| align="right" | ||
| [[Image:Flag_of_Estonia. | | [[Image:Flag_of_Estonia.svg|border|30px]] [[Andmevahetussüsteemi_X-tee_liides|eesti keeles]] | ||
|} | |} | ||
Line 6: | Line 6: | ||
'''POSR''' is a data exchange system, through which creditors that are members of the system are able to share information about person’s credit obligations. | '''POSR''' is a data exchange system, through which creditors that are members of the system are able to share information about person’s credit obligations. | ||
This document is about services of the system provided by the X-road. | This document is about services of the system provided by the X-road. | ||
= Use of services in production environment = | |||
For using the services it is needed to be a member of X-Road, to install and configure the Security Server and to receive the rights for using the services from Creditinfo Eesti AS. | |||
To send the request in production environment should the parameter xRoadInstance be "EE" in the header of request. Also, the request should be sent to the production Security Server. | |||
= Use of services in test environment = | |||
Testing of the services is offered by the X-Road test environment. For using the services it is needed to be a member of test-X-Road, to install and configure the Test Security Server and to receive the rights for using the services from Creditinfo Eesti AS. | |||
To send the request in test environment should the parameter xRoadInstance be "ee-test" in the header of request. Also, the request should be sent to the Test Security Server. | |||
It is possible to test the services allowed to use or the [http://x-road.eu/docs/x-road_service_metadata_protocol.pdf X-Road metadata services] like "listMethods" or "allowedMethods". There is no need to have rights for using the metadata services. | |||
= WSDL = | = WSDL = | ||
Line 20: | Line 32: | ||
== SOAP envelope header == | == SOAP envelope header == | ||
Composition of data of the SOAP envelope header responds to X-road specification. | Composition of data of the SOAP envelope header responds to [http://x-road.eu/docs/x-road_message_protocol_v4.0.pdf X-road specification]. | ||
== SOAP envelope body == | == SOAP envelope body == | ||
Line 35: | Line 47: | ||
<SOAP-ENV:Header> | <SOAP-ENV:Header> | ||
<xrd:client id:objectType="SUBSYSTEM"> | <xrd:client id:objectType="SUBSYSTEM"> | ||
<id:xRoadInstance> | <id:xRoadInstance>EE</id:xRoadInstance> | ||
<id:memberClass>COM</id:memberClass> | <id:memberClass>COM</id:memberClass> | ||
<id:memberCode>00000000</id:memberCode> | <id:memberCode>00000000</id:memberCode> | ||
Line 41: | Line 53: | ||
</xrd:client> | </xrd:client> | ||
<xrd:service id:objectType="SERVICE"> | <xrd:service id:objectType="SERVICE"> | ||
<id:xRoadInstance> | <id:xRoadInstance>EE</id:xRoadInstance> | ||
<id:memberClass>COM</id:memberClass> | <id:memberClass>COM</id:memberClass> | ||
<id:memberCode>10256137</id:memberCode> | <id:memberCode>10256137</id:memberCode> | ||
Line 73: | Line 85: | ||
<SOAP-ENV:Header> | <SOAP-ENV:Header> | ||
<xrd:client id:objectType="MEMBER" xmlns:xrd="http://x-road.eu/xsd/xroad.xsd" xmlns:id="http://x-road.eu/xsd/identifiers"> | <xrd:client id:objectType="MEMBER" xmlns:xrd="http://x-road.eu/xsd/xroad.xsd" xmlns:id="http://x-road.eu/xsd/identifiers"> | ||
<id:xRoadInstance> | <id:xRoadInstance>EE</id:xRoadInstance> | ||
<id:memberClass>COM</id:memberClass> | <id:memberClass>COM</id:memberClass> | ||
<id:memberCode>00000000</id:memberCode> | <id:memberCode>00000000</id:memberCode> | ||
Line 79: | Line 91: | ||
</xrd:client> | </xrd:client> | ||
<xrd:service id:objectType="SERVICE" xmlns:xrd="http://x-road.eu/xsd/xroad.xsd" xmlns:id="http://x-road.eu/xsd/identifiers"> | <xrd:service id:objectType="SERVICE" xmlns:xrd="http://x-road.eu/xsd/xroad.xsd" xmlns:id="http://x-road.eu/xsd/identifiers"> | ||
<id:xRoadInstance> | <id:xRoadInstance>EE</id:xRoadInstance> | ||
<id:memberClass>COM</id:memberClass> | <id:memberClass>COM</id:memberClass> | ||
<id:memberCode>10256137</id:memberCode> | <id:memberCode>10256137</id:memberCode> | ||
Line 143: | Line 155: | ||
== '''generateConsent.v1''' == | == '''generateConsent.v1''' == | ||
Creation of the document | Creation of the document, which provides the requester to inquire person’s credit obligations, whoes consent is given by the digital signature of the document. The consent document format is pdf. | ||
===Request soap envelope body parameters=== | ===Request soap envelope body parameters=== | ||
[[File:GenerateConsentReq.png|link=]] | [[File:GenerateConsentReq.png|link=]] | ||
Line 150: | Line 162: | ||
[[File:GenerateConsentResp.png]] | [[File:GenerateConsentResp.png]] | ||
==''' | === Testing of the service === | ||
The input parameter ident_code is the identity code of Estonia citizen. | |||
== '''getMembers.v1''' == | |||
The request of members list, to use it while creating the consent document. | |||
=== Request soap envelope body parameters === | |||
[[File:GetMembersReq.png]] | |||
=== Response soap envelope body parameters === | |||
[[File:GetMembersResp.png]] | |||
=='''getCreditReport.v1'''== | |||
The request of person’s credit obligations from data repositories of creditors that are members of the data exchange system. | The request of person’s credit obligations from data repositories of creditors that are members of the data exchange system. | ||
Line 161: | Line 188: | ||
[[File:GetSubjectPositiveDataResponse.png | GetSubjectPositiveDataResponse]] | [[File:GetSubjectPositiveDataResponse.png | GetSubjectPositiveDataResponse]] | ||
=== Testing of the service === | |||
The input parameter ident_code is the identity code of Estonia citizen. | |||
The input parameter signed_consent could be the any string encoded by base64 encoding. | |||
== '''insertCredit.v1''' == | == '''insertCredit.v1''' == | ||
Line 174: | Line 206: | ||
[[File:AddSubjectPositiveDataResponse.png | AddSubjectPositiveDataResponse]] | [[File:AddSubjectPositiveDataResponse.png | AddSubjectPositiveDataResponse]] | ||
=== Testing of the service === | |||
Input parameters should meet the requirements. | |||
As the result the service do not insert the input data to the database. | |||
== '''updateCredit.v1''' == | == '''updateCredit.v1''' == | ||
Line 186: | Line 223: | ||
[[File:UpdateSubjectPositiveDataResponse.png | UpdateSubjectPositiveDataResponse]] | [[File:UpdateSubjectPositiveDataResponse.png | UpdateSubjectPositiveDataResponse]] | ||
=== Testing of the service === | |||
Input parameters should meet the requirements. | |||
As the result the service do not update the data in the database. | |||
== '''deleteCredit.v1''' == | == '''deleteCredit.v1''' == | ||
Line 198: | Line 240: | ||
[[File:DeleteSubjectPositiveDataResponse.png | DeleteSubjectPositiveDataResponse]] | [[File:DeleteSubjectPositiveDataResponse.png | DeleteSubjectPositiveDataResponse]] | ||
=== Testing of the service === | |||
Input parameters should meet the requirements. | |||
As the result the service do not delete the data from the database. | |||
== '''uploadCreditsMtom.v1''' == | == '''uploadCreditsMtom.v1''' == | ||
Line 233: | Line 280: | ||
<SOAP-ENV:Header> | <SOAP-ENV:Header> | ||
<xrd:client id:objectType="SUBSYSTEM"> | <xrd:client id:objectType="SUBSYSTEM"> | ||
<id:xRoadInstance> | <id:xRoadInstance>EE</id:xRoadInstance> | ||
<id:memberClass>COM</id:memberClass> | <id:memberClass>COM</id:memberClass> | ||
<id:memberCode>00000000</id:memberCode> | <id:memberCode>00000000</id:memberCode> | ||
Line 239: | Line 286: | ||
</xrd:client> | </xrd:client> | ||
<xrd:service id:objectType="SERVICE"> | <xrd:service id:objectType="SERVICE"> | ||
<id:xRoadInstance> | <id:xRoadInstance>EE</id:xRoadInstance> | ||
<id:memberClass>COM</id:memberClass> | <id:memberClass>COM</id:memberClass> | ||
<id:memberCode>10256137</id:memberCode> | <id:memberCode>10256137</id:memberCode> | ||
Line 275: | Line 322: | ||
[[File:UploadPositiveDataMtomResponse.png | UploadPositiveDataMtomResponse]] | [[File:UploadPositiveDataMtomResponse.png | UploadPositiveDataMtomResponse]] | ||
=== Testing of the service === | |||
The attachment in second part of the message could be any string encoded by base64 encoding. | |||
As the result the service do not import the input data to the database. | |||
== '''getUploadStatus.v1''' == | == '''getUploadStatus.v1''' == | ||
Requesting of the document status that was created by importing of data of all current credit obligations in data exchange system repository. | Requesting of the document status that was created by importing of data of all current credit obligations in data exchange system repository. | ||
Line 286: | Line 337: | ||
[[File:UploadPositiveDataStatusResponse.png | UploadPositiveDataStatusResponse]] | [[File:UploadPositiveDataStatusResponse.png | UploadPositiveDataStatusResponse]] | ||
=== Testing of the service === | |||
The input parameter doc_id could be any number. | |||
The result of the service is any status. | |||
= Technical error = | = Technical error = | ||
Line 310: | Line 366: | ||
<tr> | <tr> | ||
<td>'''-50200'''</td> | <td>'''-50200'''</td> | ||
<td>''' | <td>'''Internal service''' '''error'''</td> | ||
</tr> | </tr> | ||
<tr> | <tr> | ||
<td></td> | <td></td> | ||
<td> | <td>Internal service error</td> | ||
</tr> | </tr> | ||
<tr> | <tr> | ||
<td> | <td>'''-50201''' | ||
'''-50301''' | |||
</td> | |||
<td>'''Invalid request'''</td> | <td>'''Invalid request'''</td> | ||
</tr> | </tr> | ||
Line 333: | Line 383: | ||
</tr> | </tr> | ||
<tr> | <tr> | ||
<td>'''- | <td>'''-50202'''</td> | ||
<td>'''Access denied'''</td> | <td>'''Access denied'''</td> | ||
</tr> | </tr> | ||
Line 341: | Line 391: | ||
</tr> | </tr> | ||
<tr> | <tr> | ||
<td>'''- | <td>'''-50203'''</td> | ||
<td>'''Partial data'''</td> | <td>'''Partial data'''</td> | ||
</tr> | </tr> | ||
Line 354: | Line 404: | ||
<tr> | <tr> | ||
<td></td> | <td></td> | ||
<td>Consumer credit data synchronization has failed</td> | <td>Consumer credit data synchronization (insertion, updating, deletion) has failed</td> | ||
</tr> | </tr><tr><td>'''-50252'''</td><td>'''Invalid consent document'''</td></tr><tr><td></td><td>The consent document has not been pre-generated or is invalid digidoc container.</td></tr><tr><td>'''-50300'''</td><td>'''Invalid xml'''</td></tr><tr><td></td><td>Xml is invalid</td></tr></table> | ||
</table> | |||
= Links = | = Links = | ||
[[Positive_register: functional_specification | Functional specification]] | [[Positive_register: functional_specification | Functional specification]] |
Latest revision as of 13:03, 10 April 2017
eesti keeles |
Overview
POSR is a data exchange system, through which creditors that are members of the system are able to share information about person’s credit obligations.
This document is about services of the system provided by the X-road.
Use of services in production environment
For using the services it is needed to be a member of X-Road, to install and configure the Security Server and to receive the rights for using the services from Creditinfo Eesti AS.
To send the request in production environment should the parameter xRoadInstance be "EE" in the header of request. Also, the request should be sent to the production Security Server.
Use of services in test environment
Testing of the services is offered by the X-Road test environment. For using the services it is needed to be a member of test-X-Road, to install and configure the Test Security Server and to receive the rights for using the services from Creditinfo Eesti AS.
To send the request in test environment should the parameter xRoadInstance be "ee-test" in the header of request. Also, the request should be sent to the Test Security Server.
It is possible to test the services allowed to use or the X-Road metadata services like "listMethods" or "allowedMethods". There is no need to have rights for using the metadata services.
WSDL
POSR system WSDL can be downloaded on link http://services.krediidiinfo.ee/posr.wsdl
X-road message
X-road message is corresponding to the service description
- SOAP envelope
- or is in MIME multipart/related format. First part of the message is SOAP envelope.
Response is a SOAP envelope.
SOAP envelope consists of a header and a body.
SOAP envelope header
Composition of data of the SOAP envelope header responds to X-road specification.
SOAP envelope body
Composition of data of the SOAP envelope body is described in the present documentation.
Request soap envelope example
<?xml version="1.0" encoding="UTF-8"?> <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xrd="http://x-road.eu/xsd/xroad.xsd" xmlns:id="http://x-road.eu/xsd/identifiers" xmlns:posr="http://www.krediidiinfo.ee/services/posr" xmlns:rep="http://www.krediidiinfo.ee/schemas/positive_register/credit/v1/report.xsd"> <SOAP-ENV:Header> <xrd:client id:objectType="SUBSYSTEM"> <id:xRoadInstance>EE</id:xRoadInstance> <id:memberClass>COM</id:memberClass> <id:memberCode>00000000</id:memberCode> <id:subsystemCode>TEST</id:subsystemCode> </xrd:client> <xrd:service id:objectType="SERVICE"> <id:xRoadInstance>EE</id:xRoadInstance> <id:memberClass>COM</id:memberClass> <id:memberCode>10256137</id:memberCode> <id:subsystemCode>POSR</id:subsystemCode> <id:serviceCode>getCreditReport</id:serviceCode> <id:serviceVersion>v1</id:serviceVersion> </xrd:service> <xrd:id>test</xrd:id> <xrd:userId>EE00000000000</xrd:userId> <xrd:protocolVersion>4.0</xrd:protocolVersion> </SOAP-ENV:Header> <SOAP-ENV:Body> <posr:getCreditReport> <rep:subject> <rep:ident_code>00000000000</rep:ident_code> </rep:subject> <rep:signed_consent>TEST</rep:signed_consent> <rep:lang>et</rep:lang> </posr:getCreditReport> </SOAP-ENV:Body> </SOAP-ENV:Envelope>
Response soap envelope example
<?xml version="1.0" encoding="UTF-8"?> <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:posr="http://www.krediidiinfo.ee/services/posr"> <SOAP-ENV:Header> <xrd:client id:objectType="MEMBER" xmlns:xrd="http://x-road.eu/xsd/xroad.xsd" xmlns:id="http://x-road.eu/xsd/identifiers"> <id:xRoadInstance>EE</id:xRoadInstance> <id:memberClass>COM</id:memberClass> <id:memberCode>00000000</id:memberCode> <id:subsystemCode>Test</id:subsystemCode> </xrd:client> <xrd:service id:objectType="SERVICE" xmlns:xrd="http://x-road.eu/xsd/xroad.xsd" xmlns:id="http://x-road.eu/xsd/identifiers"> <id:xRoadInstance>EE</id:xRoadInstance> <id:memberClass>COM</id:memberClass> <id:memberCode>10256137</id:memberCode> <id:subsystemCode>POSR</id:subsystemCode> <id:serviceCode>getCreditReport</id:serviceCode> <id:serviceVersion>v1</id:serviceVersion> </xrd:service> <xrd:id xmlns:xrd="http://x-road.eu/xsd/xroad.xsd">test</xrd:id> <xrd:userId xmlns:xrd="http://x-road.eu/xsd/xroad.xsd">EE00000000000</xrd:userId> <xrd:issue xmlns:xrd="http://x-road.eu/xsd/xroad.xsd"/> <xrd:protocolVersion xmlns:xrd="http://x-road.eu/xsd/xroad.xsd">4.0</xrd:protocolVersion> <xrd:requestHash algorithmId="http://www.w3.org/2001/04/xmlenc#sha512">Test</xrd:requestHash> </SOAP-ENV:Header> <SOAP-ENV:Body> <posr:getCreditReportResponse> <credit_report xmlns:rep="http://www.krediidiinfo.ee/schemas/positive_register/credit/v1/report.xsd" xmlns:cid="http://www.krediidiinfo.ee/schemas/positive_register/credit/v1/identifiers.xsd"> <rep:consumer_credits> <rep:consumer_credit> <cid:type> <cid:code>CC</cid:code> <cid:name>Krediitkaart</cid:name> </cid:type> <cid:begin_date>2016-07-14</cid:begin_date> <cid:end_date>2017-07-14</cid:end_date> <cid:sum>200</cid:sum> <cid:balance>200</cid:balance> <cid:unpaid_sum>7</cid:unpaid_sum> <cid:currency>EUR</cid:currency> <cid:schedule_payments> <cid:schedule_payment> <cid:due_date>2016-10-22</cid:due_date> <cid:sum>100.0</cid:sum> </cid:schedule_payment> </cid:schedule_payments> <cid:subjects> <cid:subject> <cid:ident_code>00000000000</cid:ident_code> <cid:role> <cid:code>BRW</cid:code> <cid:name>Krediidivõtja</cid:name> </cid:role> </cid:subject> </cid:subjects> <cid:update_datetime>2017-01-01T03:00:00</cid:update_datetime> </rep:consumer_credit> </rep:consumer_credits> <rep:inquiries> <rep:inquiry> <cid:datetime>2017-01-02T08:17:30</cid:datetime> </rep:inquiry> </rep:inquiries> </credit_report> <posr:fault xsi:nil="true"/> </posr:getCreditReportResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>
Services
The member can use services if Creditinfo Eesti AS has given him the rights to use them.
generateConsent.v1
Creation of the document, which provides the requester to inquire person’s credit obligations, whoes consent is given by the digital signature of the document. The consent document format is pdf.
Request soap envelope body parameters
Response soap envelope body parameters
Testing of the service
The input parameter ident_code is the identity code of Estonia citizen.
getMembers.v1
The request of members list, to use it while creating the consent document.
Request soap envelope body parameters
Response soap envelope body parameters
getCreditReport.v1
The request of person’s credit obligations from data repositories of creditors that are members of the data exchange system.
Request soap envelope body parameters
Response soap envelope body parameters
Testing of the service
The input parameter ident_code is the identity code of Estonia citizen.
The input parameter signed_consent could be the any string encoded by base64 encoding.
insertCredit.v1
Registration of the person’s credit obligation in data exchange system repository.
Request soap envelope body parameters
Response soap envelope body parameters
Testing of the service
Input parameters should meet the requirements.
As the result the service do not insert the input data to the database.
updateCredit.v1
Update of the person’s credit obligation in data exchange system repository.
Request soap envelope body parameters
Response soap envelope body parameters
Testing of the service
Input parameters should meet the requirements.
As the result the service do not update the data in the database.
deleteCredit.v1
Deletion of the person’s credit obligation from data exchange system repository.
Request soap envelope body parameters
Response soap envelope body parameters
Testing of the service
Input parameters should meet the requirements.
As the result the service do not delete the data from the database.
uploadCreditsMtom.v1
Importing of data of all current credit obligations in data exchange system repository.
Request
Request is in format MTOM/XOP, which responds to the standard SOAP multipart/related. First part of the message is SOAP envelope. Second part of the message is XML which is zipped by gzip and encoded by base64. XML should be valid according to the schema https://services.krediidiinfo.ee/schemas/positive_register/credit/v1/insert.xsd.
Soap envelope body parameters:
Request example:
...Other headers Content-Type: multipart/related; type="application/xop+xml"; start="<xxx>"; start-info="text/xml"; boundary="MIME_boundary"' MIME-Version: 1.0 --MIME_boundary Content-Type: application/xop+xml; charset=UTF-8; type="text/xml" Content-Transfer-Encoding: 8bit Content-ID: <xxx> <?xml version="1.0" encoding="UTF-8"?> <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xrd="http://x-road.eu/xsd/xroad.xsd" xmlns:id="http://x-road.eu/xsd/identifiers" xmlns:posr="http://www.krediidiinfo.ee/services/posr"> <SOAP-ENV:Header> <xrd:client id:objectType="SUBSYSTEM"> <id:xRoadInstance>EE</id:xRoadInstance> <id:memberClass>COM</id:memberClass> <id:memberCode>00000000</id:memberCode> <id:subsystenCode>TEST</id:subsystenCode> </xrd:client> <xrd:service id:objectType="SERVICE"> <id:xRoadInstance>EE</id:xRoadInstance> <id:memberClass>COM</id:memberClass> <id:memberCode>10256137</id:memberCode> <id:subsystemCode>POSR</id:subsystemCode> <id:serviceCode>uploadCreditsMtom</id:serviceCode> <id:serviceVersion>v1</id:serviceVersion> </xrd:service> <xrd:id>test</xrd:id> <xrd:userId>EE00000000000</xrd:userId> <xrd:protocolVersion>4.0</xrd:protocolVersion> </SOAP-ENV:Header> <SOAP-ENV:Body> <posr:uploadCreditsMtom> <positive_data> <inc:Include href="cid:xxx"/> </positive_data> </posr:uploadCreditsMtom> </SOAP-ENV:Body> </SOAP-ENV:Envelope> --MIME_boundary Content-Type: application/octet-stream Content-Transfer-Encoding: base64 Content-ID: <xxx> Content-Disposition: attachment; H4sIAAAAAAAAA12PsW7CQAyGd6S+Q+Q9dxeoRIkIbEx0KpXYoujOCRbEh84uyeM3abtQyfLi///kb7sf+1v2wCQUuYLCOMiQfQzEXQWfp0P+Bvvdy2LrI8tXj6n2CQOpZFOPpaRQwUX1Xlo7DIO5zkeahttoEK34C/aN2HsUUnpgnbAjUUz2F1NTQFZqaXrAjBLgDzsKPXGHlYmps0vnCnt+P378YHNi0YY9QtYhY2oU6zAtpR4rmLN5scyL9cltypUrX9cwi9j/Jrtv1xHpQQQBAAA= --MIME_boundary--
Response soap envelope body parameters
Testing of the service
The attachment in second part of the message could be any string encoded by base64 encoding.
As the result the service do not import the input data to the database.
getUploadStatus.v1
Requesting of the document status that was created by importing of data of all current credit obligations in data exchange system repository.
Request soap envelope body parameters
Response soap envelope body parameters
Testing of the service
The input parameter doc_id could be any number.
The result of the service is any status.
Technical error
<?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>SOAP-ENV:Server</faultcode> <faultstring>Internal service error</faultstring> <faultactor/> <detail> <faultCode>-50200</faultCode> <faultString>Internal service error</faultString> </detail> </SOAP-ENV:Fault> </SOAP-ENV:Body> </SOAP-ENV:Envelope>
Error codes
-50200 | Internal service error |
Internal service error | |
-50201
-50301 |
Invalid request |
Invalid request format or data | |
-50202 | Access denied |
User has no permission to use the system | |
-50203 | Partial data |
The data in response is partial | |
-50250 | Credit data sync failed |
Consumer credit data synchronization (insertion, updating, deletion) has failed | |
-50252 | Invalid consent document |
The consent document has not been pre-generated or is invalid digidoc container. | |
-50300 | Invalid xml |
Xml is invalid |