KiDocExchange

From services.krediidiinfo.ee
Jump to navigation Jump to search
The printable version is no longer supported and may have rendering errors. Please update your browser bookmarks and please use the default browser print function instead.
Flag of the United Kingdom.svg 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 http://services.krediidiinfo.ee/KiDocExchange.wsdl.


Järgnevusdiagramm

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

KiDocExchange Upload Sequence Diagram.jpg

ja alla laadimisel

Download diagram.png


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 = '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);