Difference between revisions of "Data exchange system X-road interface"

From services.krediidiinfo.ee
Jump to: navigation, search
(Undo revision 895 by Julia (talk))
 
(One intermediate revision by the same user not shown)
Line 4: Line 4:
  
 
= Overview =
 
= Overview =
The '''Positive Register''' (Positiivne Register) is the data exchange system, through which creditors that are members of the register are able to share information about person’s credit obligations with consent of the person in question. The Positive Register allows a creditor to fulfill statutory requirements of responsible lending and to ensure a person’s ability to fulfill his or her debt obligations. Loan applicants will no longer have to collect documents from other creditors. Customer will also be better protected from the problems associated with making emotional decisions about loans and excessive debts.  
+
'''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.
  
= Definitions =
+
= 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.
  
* '''Data''' – information about existing obligations of a private person that allows the Member to assess creditworthiness of the individual.
+
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.
* '''Data exchange system''' – the IT solution used by the Member to exchange the Data;
 
* '''Manager of the data exchange system''' – Creditinfo Eesti AS;
 
* '''Codebtor''' – a private person together with whom the Applicant applies for credit and who is taken into account while making the Credit decision;
 
* '''Credit decision''' – the decision made by the Member with regard to concluding the Consumer credit contract with the Applicant;
 
* '''Borrower''' – a private person to whom the Member issues the credit based on the Consumer credit contract;
 
* '''Applicant''' – a private person who turns to the Member with the wish to conclude the Consumer credit contract and provides his/her Agreement for using the Data possessed by the Members;
 
* '''Guarantor''' – a person who assumes the obligation before the Member to be liable for performance of the Consumer credit contract obligations of the Applicant;
 
* '''Consent '''– consent of the Applicant for providing the Member making the inquiry with the Data of the Members being the recipients of the inquiry;
 
* '''Member''' – an Estonian that joins the Data exchange system and shares the Data about the Applicant with other Members;
 
* '''Consumer credit contract''' – the contract on the basis of which the Member issues the credit to the Applicant;
 
* '''Subject''' – a party to the contract;
 
* '''Consumer credit''' – the credit issued to the Applicant by the Member.
 
  
 +
= 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.
  
= Business rules =
+
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.
  
* Users of the system are the ''Members''.
+
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.
* A ''Member'' must join X-road.  
 
* The ''Member'' inputs ''Data'' to the database of ''Data exchange system'' or provides ''Manager of the data exchange system'' with an IT-based solution to obtain the ''Data'' from him's database.
 
* The ''Member'' updates the ''Data'' by sending to the ''Data exchange system'' all current ''Data or Consumer credit contract data one by one''.
 
* The ''Member'' updates the ''Data'' every 24 hours. At least every 7 days.
 
* The ''Member'' requests the ''Data'' only with the ''Applicant'' prior ''Consent''. If the ''Consent'' is not assigned digitally, then the requester has no permission to request ''Data'' from databases of other Members, who has a condition of existence of digitally signed ''Consent''  for data requesting and forwarding.
 
* The ''Consent'' document is stored in the ''Data exchange system'' for 3 years.
 
* The response to the ''Data'' request does not reflect information about the ''Member''.
 
* Composition of the response to the ''Data'' request is described in “Data composition” chapter.
 
* The ''Members'' share the ''Data'' with other Members in equal data composition.
 
  
= Data composition=
+
= WSDL =
 +
POSR system WSDL can be downloaded on link http://services.krediidiinfo.ee/posr.wsdl
  
# Date and time of updating data;
+
= X-road message =
# Person identity code;
+
X-road message is corresponding to the service description
# Role of the person within the scope of the contract;
+
* SOAP envelope
# Contract number;
+
* or is in MIME multipart/related format. First part of the message is SOAP envelope.
# Type of consumer credit;
+
Response is a SOAP envelope.
# Effective date of credit agreement – date of commencement of the Consumer credit contract;
 
# End date of credit – the date of repayment of the Consumer credit;
 
# Consumer credit sum – the maximum sum of the Consumer credit paid or payable to the Applicant;
 
# Currency – currency of the Consumer credit;
 
# Schedule payments – the sum and the due date of the next or the closest three payments;
 
# Balance – the amount of the obligation of the consumer before the Member;
 
# Overdue balance – the sum of payments overdue for more than 7 days;
 
# Requests – dates of requests made with regard to the Data of the Applicant made during the past three years.
 
'''Roles of the person'''
 
#Borrower
 
#Codebtor
 
#Guarantor
 
'''Types of credit'''
 
#Secured loan
 
#Hire-purchase
 
#Unsecured loan
 
#Lease
 
#Credit card
 
#Other
 
  
 +
SOAP envelope consists of a header and a body.
  
= Use cases =
+
== SOAP envelope header ==
 +
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].
  
[[File:Positive register use cases.jpg]]
+
== SOAP envelope body ==
 +
Composition of data of the SOAP envelope body is described in the present documentation.
  
 +
== Request soap envelope example ==
 +
<pre>
 +
<?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>
 +
</pre>
  
 +
== Response soap envelope example==
  
== Members list request ==
+
<pre>
'''Prerequisite:''' <u>Data exchange system manager</u> has given a permission to <u>Member</u> to make a request.
+
<?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>
 +
</pre>
  
Member requests the list of other Members for using it while consent document creation.
+
= Services =
  
==  Consent document creation ==
+
The member can use services if Creditinfo Eesti AS has given him the rights to use them.
'''Prerequisite:''' <u>Data exchange system manager</u> has given a permission to <u>Member</u> to make a request.
 
  
Member requests the consent document of the Applicant for inquiring hims/hers Data possessed by the Members;
+
== '''generateConsent.v1''' ==
== Credit report request  ==
+
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===
 +
[[File:GenerateConsentReq.png|link=]]
 +
===Response soap envelope body parameters===
  
'''Prerequisite:''' <u>Data exchange system manager</u> has given a permission to <u>Member</u> to make a request.
+
[[File:GenerateConsentResp.png]]
  
'''Prerequisite:''' If the consent document is an input of the request, this should had been generated in the Data exchange system.
+
=== Testing of the service ===
# Member sends a request to the Data exchange system to get Applicant's credit obligations;
+
The input parameter ident_code is the identity code of Estonia citizen.
# Data exchange system queries the Data from the database;
 
# Data exchange system responses to the requester with the Data.
 
Extension
 
* Member has a condition of existence of the digitally signed ''Consent'' for data requesting from repository and the digitally signed consent is not an input of the request
 
::2a. Data Exchange System does not request the Data from Member's repository;
 
  
::3a. Data Exchange System response includes information about undone request.
+
== '''getMembers.v1''' ==
 +
The request of members list, to use it while creating the consent document.
  
* Data repository of the member is stored in Member's system
+
=== Request soap envelope body parameters ===
::2a. Data exchange system queries the Data from Members' systems
 
* Quering of the Data from Member's system fails
 
::3a. Data exchange system responses to the requester with the Data and with the error message that includes the number of failed queries.
 
  
== Credit data management  ==
+
[[File:GetMembersReq.png]]
  
'''Prerequisite:''' <u>Data exchange system manager</u> has given a permission to <u>Member</u> to make a request.
+
=== Response soap envelope body parameters ===
  
'''Prerequisite:''' The <u>Member</u> has concluded the authorization agreement with Data exchange system manager, under which the Member issues to Data exchange system manager the rights of authorized data processor with regard to the database held by the Member.  
+
[[File:GetMembersResp.png]]
  
The Member forwards credit data from the database held by the Member to Data exchange system.
 
  
[[File:Credit data management use case.jpg]]
+
=='''getCreditReport.v1'''==
 +
The request of person’s credit obligations from data repositories of creditors that are members of the data exchange system.
  
'''Scenarios'''
+
=== Request soap envelope body parameters ===
  
'''A)''' The <u>Member</u> forwards all current data on consumer credits to the Data exchange system.  
+
[[File:GetSubjectPositiveData.png | GetSubjectPositiveData]]
  
'''B)''' The <u>Member</u> changes the consumer credit data in the Data exchange system database.
 
  
 +
=== Response soap envelope body parameters ===
  
== Manager data management   ==
+
[[File:GetSubjectPositiveDataResponse.png | GetSubjectPositiveDataResponse]]
  
<u>Data exchange system manager</u> registers information about the Member in the Data exchange system / removes such information from the Data exchange system.
+
=== 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''' ==
  
= Sequence diagram =
+
Registration of the person’s credit obligation in data exchange system repository.  
The following diagram describes the process of credit decision when
 
::1. the Applicant signes the consent digitally
 
::[[File:Credit decision using digi consent.jpg]]
 
  
 +
=== Request soap envelope body parameters ===
  
::2. the Applicant do not sign the consent digitally
+
[[File:AddSubjectPositiveData.png | AddSubjectPositiveData]]
::[[File:Credit decision using digi consent.jpg]]
 
  
= Links =
+
 
[[X-road interface: subsystem POSR|Data exchange system X-road interface]]
+
=== Response soap envelope body parameters ===
 +
 
 +
[[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''' ==
 +
Update of the person’s credit obligation in data exchange system repository.
 +
 
 +
=== Request soap envelope body parameters ===
 +
 
 +
[[File:UpdateSubjectPositiveData.png | UpdateSubjectPositiveData]]
 +
 
 +
 
 +
=== Response soap envelope body parameters ===
 +
 
 +
[[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''' ==
 +
Deletion of the person’s credit obligation from data exchange system repository.
 +
 
 +
=== Request soap envelope body parameters ===
 +
 
 +
[[File:DeleteSubjectPositiveData.png | DeleteSubjectPositiveData]]
 +
 
 +
 
 +
=== Response soap envelope body parameters ===
 +
 
 +
[[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''' ==
 +
Importing of data of all current credit obligations in data exchange system repository.
 +
 
 +
=== Request ===
 +
 
 +
Request is in format <b>MTOM/XOP</b>, which responds to the standard SOAP <b>multipart/related</b>. 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:
 +
 
 +
[[File:UploadPositiveDataMtom.png | UploadPositiveDataMtom]]
 +
 
 +
 
 +
[[File:Loaninfo debtors.png]]
 +
 
 +
 
 +
'''Request example:'''
 +
 
 +
<pre>
 +
...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--
 +
</pre>
 +
 
 +
=== Response soap envelope body parameters ===
 +
 
 +
[[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''' ==
 +
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 ===
 +
 
 +
[[File:UploadPositiveDataStatus.png | UploadPositiveDataStatus]]
 +
 
 +
 
 +
=== Response soap envelope body parameters ===
 +
 
 +
[[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 =
 +
 
 +
<pre>
 +
<?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>
 +
</pre>
 +
 
 +
= Error codes =
 +
<table>
 +
  <tr>
 +
    <td>'''-50200'''</td>
 +
    <td>'''Internal service''' '''error'''</td>
 +
  </tr>
 +
  <tr>
 +
    <td></td>
 +
    <td>Internal service error</td>
 +
  </tr>
 +
  <tr>
 +
    <td>'''-50201'''
 +
'''-50301'''
 +
</td>
 +
    <td>'''Invalid request'''</td>
 +
  </tr>
 +
  <tr>
 +
    <td></td>
 +
    <td>Invalid request format or data</td>
 +
  </tr>
 +
  <tr>
 +
    <td>'''-50202'''</td>
 +
    <td>'''Access denied'''</td>
 +
  </tr>
 +
  <tr>
 +
    <td></td>
 +
    <td>User has no permission to use the system</td>
 +
  </tr>
 +
  <tr>
 +
    <td>'''-50203'''</td>
 +
    <td>'''Partial data'''</td>
 +
  </tr>
 +
  <tr>
 +
    <td></td>
 +
    <td>The data in response is partial</td>
 +
  </tr>
 +
  <tr>
 +
    <td>'''-50250'''</td>
 +
    <td>'''Credit data sync failed'''</td>
 +
  </tr>
 +
  <tr>
 +
    <td></td>
 +
    <td>Consumer credit data synchronization (insertion, updating, deletion) has failed</td>
 +
  </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>
 +
 
 +
= Links =
 +
[[Positive_register: functional_specification | Functional specification]]

Latest revision as of 13:03, 10 April 2017

Flag of Estonia.svg 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

GenerateConsentReq.png

Response soap envelope body parameters

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

GetMembersReq.png

Response soap envelope body parameters

GetMembersResp.png


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

GetSubjectPositiveData


Response soap envelope body parameters

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

Registration of the person’s credit obligation in data exchange system repository.

Request soap envelope body parameters

AddSubjectPositiveData


Response soap envelope body parameters

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

Update of the person’s credit obligation in data exchange system repository.

Request soap envelope body parameters

UpdateSubjectPositiveData


Response soap envelope body parameters

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

Deletion of the person’s credit obligation from data exchange system repository.

Request soap envelope body parameters

DeleteSubjectPositiveData


Response soap envelope body parameters

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

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:

UploadPositiveDataMtom


Loaninfo debtors.png


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

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

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

UploadPositiveDataStatus


Response soap envelope body parameters

UploadPositiveDataStatusResponse

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
-50252Invalid consent document
The consent document has not been pre-generated or is invalid digidoc container.
-50300Invalid xml
Xml is invalid

Links

Functional specification