KiDocExchange en

eesti keeles

KiDocExchange Web Service

Introduction

KiDocExchange is a web service for uploading files into Creditinfo server. Web Service description can be found on http://services.krediidiinfo.ee/KiDocExchange.wsdl.

Filename guide for sending and receiving

Creditinfo file transfer file name guide for request file:

req_<client_code>_<product_code>_<date+time>.<file_extension>
nt. req_123456_mhr_20230505124518.xml

Creditinfo file name for request file (if necessary for product):

resp_<client_code>_<product_code>_<date+time>.<file_extension>
nt. req_123456_mhr_20230505124518.xml

• <client_code> - Supplied by Creditinfo.
• <product_code> - Supplied by Creditinfo.
• <date+time> - Datetime of file generation. Format YYYYMMDDHHmmss. Example: 2023-05-23 12:45:18 -> 20230523124518
  • in response file this is request file generation time to easily match response to request via file name. Actual response generation time is usually inside the file.
• <file_extension> - File extension agreed with Creditinfo (csv/xml/xlsx/jne). In some cases it can also make sense to use zip/gzip compression.

Sequence Diagram

Next squence diagram illustrates how to use KiDocExchange to upload files.

and to download

List of available files for download can be requested using getDownloadQueue() function. Once downloaded successfully the file is removed from the list. It is still possible to download the file later on if you keep the file id.

Methods

startUpload

Starts and initializes file upload.

	Name	Type	Description
Input Parameter:	fileName	xs:string	The name of file
Output Parameter:	docID	xs:integer	Unique file identification number in Creditinfo server.

uploadFile

File upload to Creditinfo server in a single request. Recommended to use instead of uploadChunk and finishUpload.

	Name	Type	Description
Input Parameters:	docID	xs:integer	File identification number.
	fileContent	xs:base64Binary	File content.
Output parameters:	md5	xs:string	md5 hash of uploaded file.

uploadChunk

Uploads and appends next chunk of data. Servers can send data in one chunk. Several chunks are needed when upload process is slow and there are a progress feedback needed (desktop application).

	Name	Type	Description
Input Parameters:	docID	xs:integer	File identification number
	chunk	xs:base64Binary	Next chunk of data
Output Parameters:			None

finishUpload

Finishes file upload.

	Name	Type	Description
Input Parameters:	docID	xs:integer	File identification number
	md5	xs:string	MD5 checksum of uploaded file
Output Parameters:	errorCode	xs:integer	If 0 then file upload succeeded. If negative then there was an error. See Error Codes for more information.

downloadFile

Download an entire file from the Creditinfo server in a single request.

	Name	Type	Description
Input Parameters:	docID	xs:integer	File identification number
Output Parameters:	fileContent	xs:base64Binary	File content

downloadChunk

Download file as chunks from Creditinfo server.

	Name	Type	Description
Input Parameters:	docID	xs:integer	File identification number
	start	xs:integer	Position in file from which the data will be downloaded (counting starts from zero)
	count	xs:integer	The size of the download chunk in bytes
Output Parameters:	chunk	xs:base64Binary	File chunk

getDownloadQueue

The list of files waiting for client to download them from Creditinfo server.

	Name	Type	Description
Output parameter:	queue	DownloadQueueArray	array of DownloadQueueType type

DownloadQueueType is an associative array with following elements:

Name	Type	Description
docID	xs:integer	file id
fileName	xs:string	file name

getStatusCode

Returns the status code of uploaded file

	Name	Type	Description
Input Parameters:	docID	xs:integer	File identification number
Output Parameters:	status_code	xs:integer	File status code:
			0	File has been processed
			2	Uploading in progress
			3	File is in processing
			4	File was successfully uploaded and is waiting for processing
			-1	Unknown error. Contact Creditinfo for more information. You might get usefull information with getStatusMsg method.
			-10003	MD5 check failed
			-xxxxx	File processing failed. Contact Creditinfo for more information. You might get usefull information with getStatusMsg method.

getStatusMsg

Returns the status message of uploaded file.

	Name	Type	Description
Input Parameters:	docID	xs:integer	File identification number
Output Parameters:	statusMsg	xs:string	Status message of the file

Error Codes

Code	Description
0	Success
	Request was processed successfully.
-10001	Access denied
	You are trying to access file owned by somebody else.
-10002	File does not exists
	You are using file identification that does not exist
-10003	MD5 failure
	Your sent MD5 does not match MD5 calculated by server

Debugging

Developers can use a test server for file uploading. For that they should add a parameter debug to the server url. The url would be 'https://services.krediidiinfo.ee/soap.php?name=KiDocExchange&debug'.

Example in pseudo code

/** DEFINE PARAMETERS */
$wsdl = 'http://services.krediidiinfo.ee/KiDocExchange.wsdl';
$productionLocation = 'https://services.krediidiinfo.ee/soap.php?name=KiDocExchange';
$testLocation = 'https://services.krediidiinfo.ee/soap.php?name=KiDocExchange&debug'; // same as production, but with added 'debug' parameter
$username = ''; // provided by Creditinfo
$password = ''; // provided by creditinfo
$connectionParameters = [
    'location' => 'https://services.krediidiinfo.ee/soap.php?name=KiDocExchange&debug',
    'login' => 'username',
    'password' => 'password'
];
$testFileContent = 'test file content';
$testFileName = 'test_file_name.txt';

/** INIT CLIENT */
$client = new SoapClient(
    $wsdl,
    [
        'location' => IN_PRODUCTION_ENV ? $productionLocation : $testLocation,
        'login' => $username,
        'password' => $password
    ]
);

/** FILE TRANSFER */
$fileId = $client->startUpload($testFileName);
$md5Actual = $client->uploadFIle($fileId, $testFileContent);
$md5Expected = md5($testFileContent); // md5 checksum to verify data integrity is optional
if ($md5Expected != $md5Actual) {
    // content upload failed, md5 returned does not match expected content md5
} 

/** DOWNLOAD FILE WITH ONE REQUEST (SUGGESTED) */
$fileId = 12345; // actual ID is aquired via getDownloadQueue response
$fileName = 'test_file.txt'; // can be anything but highly suggest using same as in getDownloadQueue response
$fileContent = $client->downloadFile($fileId);
saveFile($fileName, $fileContent);

/** DOWNLOAD FILE AS CHUNKS */
$fileId = 12345; // actual ID is aquired via getDownloadQueue response
$fileName = 'test_file.txt'; // can be anything but highly suggest using same as in getDownloadQueue response
$start = 0;
$chunkSize = 512; // was useful 30 years ago with lower download speeds, to monitor download progress. today you can use a large number which should cover the response file in one go
$fileContent = '';
while ($chunk = $client->downloadChunk($fileId, $start, $chunkSize)) {
    $start += $chunkSize;
    $fileContent .= $chunk;
}

saveFile($fileName, $fileContent);