KiDocExchange

In English

Tutvustus

KiDocExchange on Creditinfo veebiteenus failide saatmiseks ja vastuvõtmiseks.

Failide edastamine ja vastuvõtmine

Creditinfosse saadetava faili nimi peab olema kujul:

req_<kliendikood>_<toote_kood>_<kuupäev+kellaaeg>.<faililaiend>
nt. req_123456_mhr_20230505124518.xml

Creditinfo vastusfaili kuju (kui tegemist on vastust vajava tootega)

resp_<kliendikood>_<toote_kood>_<kuupäev+kellaaeg>.<faililaiend>
nt. resp_123456_mhr_20230505124518.xml

• <kliendikood> - Creditinfoga poolt jagatav väärtus.
• <toote_kood> - Creditinfoga poolt jagatav väärtus.
• <kuupäev+kellaaeg> - Päringufaili genereerimise aeg. Formaat YYYYMMDDHHmmss. Näide: 2023-05-23 12:45:18 -> 20230523124518
  • kui tegemist on vastusefailiga, siis on tegu päringu kellaajaga, et kergelt kokku viia päringut ja vastust. Vastuse genereerimise aeg on reeglina failis sees.
• <faililaiend> - Creditinfoga kokkulepitud failiformaat (csv/xml/xlsx/jne). Teatud juhtudel on mõistlik kokkulepituna rakendada ka zip/gzip kompressiooni.

WSDL

KiDocExchange veebiteenuse WSDL fail on aadressil https://services.krediidiinfo.ee/KiDocExchange.wsdl.

Järgnevusdiagramm

Järgnevusdiagrammil on näidatud KiDocExchange meetodite väljakutsumise järjekorrad faili üles laadimisel.

ja alla laadimisel

Alla laetavate failide nimekirja saab pärida funkstiooniga getDownloadQueue(). Kord alla laetud fail kaob nimekirjast, aga faili ID säilitamisel saab faili alla laadida ka hiljem.

Meetodid

startUpload

Failide üleslaadimise initsialiseerimine.

	Nimi	Tüüp	Kirjeldus
Sisendparameeter:	fileName	xs:string	Faili nimi
Väljundparameeter:	docID	xs:integer	Unikaalne faili id Creditinfo serveris.

uploadFile

Faili üleslaadimine Creditinfo failiserverisse ühe päringuga. Soovituslik kasutada meetodite uploadChunk ja finishUpload asemel.

	Nimi	Tüüp	Kirjeldus
Sisendparameetrid:	docID	xs:integer	Faili identifikaator.
	fileContent	xs:base64Binary	Üles laetava faili sisu.
Väljundparameeter:	md5	xs:string	Üles laetud faili md5 hash.

uploadChunk

Laetakse serverisse ning lisatakse juba serveris olevale failile lõppu osa failist. Kliendid võivad kogu faili saata ka ühe osana. Failide jupitamist on soovitav kasutada desktop lahendustes suurte failide saatmisel.

	Nimi	Tüüp	Kirjeldus
Sisendparameetrid:	docID	xs:integer	Faili identifikaator.
	chunk	xs:base64Binary	Järgmine faili osa.
Väljundparameeter:			None

finishUpload

Faili üleslaadimise lõpetamine.

	Nimi	Tüüp	Kirjeldus
Sisendparameetrid:	docID	xs:integer	Faili identifikaator
	md5	xs:string	Üles laetud faili MD5 kontrollsumma.
Väljundparameeter:	errorCode	xs:integer	Kui 0, siis faili üleslaadimine õnnestus. Kui negatiivne, siis tekkis mingi viga (vt veakoodide).

downloadFile

Terve faili allalaadimine Creditinfo failiserverist ühe päringuga.

	Nimi	Tüüp	Kirjeldus
Sisendparameetrid:	docID	xs:integer	Faili identifikaator
Väljundparameeter:	fileContent	xs:base64Binary	Faili sisu

downloadChunk

Faili alamosa allalaadimine Creditinfo failiserverist.

	Nimi	Tüüp	Kirjeldus
Sisendparameetrid:	docID	xs:integer	Faili identifikaator
	start	xs:integer	Positsioon failis, millest alates andmeid alla laetakse (positsiooni lugemine algab nullist)
	count	xs:integer	Alla laetava tüki suurus baitides.
Väljundparameeter:	chunk	xs:base64Binary	Faili alamosa

getDownloadQueue

Creditinfo serveris kliendi poolt allalaadimist ootavate failide loetelu.

	Nimi	Tüüp	Kirjeldus
Väljundparameeter:	queue	DownloadQueueArray	Massiiv DownloadQueueType tüüpi elementidest

DownloadQueueType on assiotsiatiivne massiiv, millel on järgmised elemendid:

Nimi	Tüüp	Kirjeldus
docID	xs:integer	faili id
fileName	xs:string	faili nimi

getStatusCode

Tagastatakse üles laetud faili staatus serveris.

	Nimi	Tüüp	Kirjeldus
Sisendparameeter:	docID	xs:integer	Faili identifikaator
Output Parameters:	status_code	xs:integer	Faili staatuse kood:
			0	Fail on töödeldud
			2	Toimub faili üles laadimine
			3	Toimub faili töötlemine
			4	Fail on edukalt üles laetud ning ootab töötlemist
			-1	Tundmatu viga. Täpsema info saamiseks võtke ühendust tehnilise teoga. Rohkem infot vea teate kohta võib saada meetodiga getStatusMsg.
			-10003	MD5 kontroll ebaõnnestus. Kliendi saadetud MD5 kontrollsumma ei langenud kokku serveri poolt arvutatud MD5 kontrollsummaga.
			-xxxxx	Faili töötlemine ebaõnnestus. Täpsema info saamiseks võta ühendust tehnilise toega. Rohkem infot vea teate kohta võib saada meetodiga getStatusMsg.

getStatusMsg

Tagastatakse staatust täpsustav info.

	Nimi	Tüüp	Kirjeldus
Sisendparameeter:	docID	xs:integer	Faili identifikaator
Väljundparameeter:	statusMsg	xs:string	Faili staatust täpsustav info

Veakoodid

Kood	Kirjeldus
0	Success
	Päringu töötlus õnnestus.
-10001	Access denied
	Üritatakse pöörduda faili poole, mis kuulub kellelegi teisele.
-10002	File does not exists
	Kasutati faili identifikaatorit, mida ei eksisteeri.
-10003	MD5 failure
	Kliendi saadetud MD5 ei lange kokku serveri poolt arvutatud MD5-ga

Testimine

Faili edastamiseks testserverisse tuleb lisada parameeter debug serveri aadressile, ehk 'https://services.krediidiinfo.ee/soap.php?name=KiDocExchange&debug'

Näidis pseudokoodina

/** DEFINE PARAMETERS */
$wsdl = 'https://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);