Latest revision as of 16:03, 17 April 2024

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

@@ Line 7: / Line 7: @@
 KiDocExchange on Creditinfo veebiteenus failide saatmiseks ja vastuvõtmiseks.
-= Failide edastamine =
-Faile saab Creditinfole edastada ja ka vastu võtta [[KiDocExchange]] SOAP liidese kaudu.
+= Failide edastamine ja vastuvõtmine=
 Creditinfosse saadetava faili nimi peab olema kujul:
 <pre>
-req_<Creditinfo_toote_kood>_<kliendi_faili_id>.xml.zip
+req_<kliendikood>_<toote_kood>_<kuupäev+kellaaeg>.<faililaiend>
+nt. req_123456_mhr_20230505124518.xml
 </pre>
+Creditinfo vastusfaili kuju (kui tegemist on vastust vajava tootega)
-* <Creditinfo_toote_kood> - Creditinfoga kokkulepitud toode, mille alusel koostatakse vastus fail.
-* <kliendi_faili_id> - kliendi poolt määratud unikaalne id, millega eristatakse faile üksteisest. Näiteks faili genereerimise aeg.
-Creditinfo vastusfaili kuju:
 <pre>
-resp_<Creditinfo_toote_kood>_<kliendi_faili_id>.zip
+resp_<kliendikood>_<toote_kood>_<kuupäev+kellaaeg>.<faililaiend>
+nt. resp_123456_mhr_20230505124518.xml
 </pre>
-* <Creditinfo_toote_kood> - Creditinfoga kokkulepitud toode, mille alusel koostatakse vastus fail.
+* <kliendikood> - Creditinfoga poolt jagatav väärtus.
-* <kliendi_faili_id> - kliendi poolt määratud unikaalne id, millega eristatakse faile üksteisest. Näiteks faili genereerimise aeg.
+* <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 http://services.krediidiinfo.ee/KiDocExchange.wsdl].
+KiDocExchange veebiteenuse WSDL fail on aadressil [https://services.krediidiinfo.ee/KiDocExchange.wsdl https://services.krediidiinfo.ee/KiDocExchange.wsdl].
@@ Line 48: / Line 46: @@
 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 ==
@@ Line 71: / Line 70: @@
 | xs:integer
 | Unikaalne faili id Creditinfo serveris.
+|}
+=== uploadFile ===
+Faili üleslaadimine Creditinfo failiserverisse ühe päringuga. Soovituslik kasutada meetodite uploadChunk ja finishUpload asemel.
+{| style="border-style: solid; border-width: 1px"
+!
+! style="text-align: left;" | Nimi
+! style="text-align: left;" | Tüüp
+! style="text-align: left;" | Kirjeldus
+|-
+| <b>Sisendparameetrid:</b>
+| docID
+| xs:integer
+| Faili identifikaator.
+|-
+|
+| fileContent
+| xs:base64Binary
+| Üles laetava faili sisu.
+|-
+| <b>Väljundparameeter:</b>
+| md5
+| xs:string
+| Üles laetud faili md5 hash.
 |}
@@ Line 127: / Line 153: @@
 |}
+=== downloadFile ===
+Terve faili allalaadimine Creditinfo failiserverist ühe päringuga.
+{| style="border-style: solid; border-width: 1px"
+!
+! style="text-align: left;" | Nimi
+! style="text-align: left;" | Tüüp
+! style="text-align: left;" | Kirjeldus
+|-
+| <b>Sisendparameetrid:</b>
+| docID
+| xs:integer
+| Faili identifikaator
+|-
+| <b>Väljundparameeter:</b>
+| fileContent
+| xs:base64Binary
+| Faili sisu
+|}
 === downloadChunk ===
@@ Line 308: / Line 355: @@
-= Silumine =
+= Testimine =
 Faili edastamiseks testserverisse tuleb lisada parameeter ''debug'' serveri aadressile, ehk 'https://services.krediidiinfo.ee/soap.php?name=KiDocExchange&debug'
-= Näidis PHP-s =
-Programm laeb faili Creditinfo serverisse ning seejärel laeb sama faili alla. Lõpus kontrollitakse, kas üles ja alla laetud faili sisu on sama. Programmi põhimõte sobib KiDocExchange liidese testimiseks. Kui soovite maksehäire sisestamiseks mõeldud faili testida siis ärge kasutage silumismoodi.
+= Näidis pseudokoodina =
 <pre>
-<?php
+/** DEFINE PARAMETERS */
-/**
+$wsdl = 'https://services.krediidiinfo.ee/KiDocExchange.wsdl';
- * Example of uploading and downloading files using KiDocExchange interface.
+$productionLocation = 'https://services.krediidiinfo.ee/soap.php?name=KiDocExchange';
- * @author Rait Kapp <rait@creditinfo.ee>
+$testLocation = 'https://services.krediidiinfo.ee/soap.php?name=KiDocExchange&debug'; // same as production, but with added 'debug' parameter
- * @created 27.04.2007
+$username = ''; // provided by Creditinfo
- */
+$password = ''; // provided by creditinfo
-$wsdl_url = 'http://services.krediidiinfo.ee/KiDocExchange.wsdl';
+$connectionParameters = [
-$params = array('location'      => 'https://services.krediidiinfo.ee/soap.php?name=KiDocExchange&debug'
+    'location' => 'https://services.krediidiinfo.ee/soap.php?name=KiDocExchange&debug',
-              , 'login'       => 'username' // <-- username. Make sure username is string type (PHP bug?).
+    'login' => 'username',
-              , 'password'    => 'password'   // <-- password
+    'password' => 'password'
-	        );
+];
+$testFileContent = 'test file content';
-$client = new SoapClient($wsdl_url, $params);
+$testFileName = 'test_file_name.txt';
+/** INIT CLIENT */
+$client = new SoapClient(
+    $wsdl,
+    [
+        'location' => IN_PRODUCTION_ENV ? $productionLocation : $testLocation,
+        'login' => $username,
+        'password' => $password
+    ]
+);
-// Uploading file.
+/** FILE TRANSFER */
-$content = 'I am a little test file!';
+$fileId = $client->startUpload($testFileName);
-$docID = $client->startUpload('test.txt');
+$md5Actual = $client->uploadFIle($fileId, $testFileContent);
-$client->uploadChunk($docID, $content);
+$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
+}
-$md5 = md5($content);
+/** DOWNLOAD FILE WITH ONE REQUEST (SUGGESTED) */
-$result = $client->finishUpload($docID, $md5);
+$fileId = 12345; // actual ID is aquired via getDownloadQueue response
-if ($result != 0) {
+$fileName = 'test_file.txt'; // can be anything but highly suggest using same as in getDownloadQueue response
-    die("upload failed.! Error code: {$result}\n");
+$fileContent = $client->downloadFile($fileId);
-}
+saveFile($fileName, $fileContent);
-// Downloading file
+/** 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;
-$count = 512; // can be a big number if you do not have to display download progress.
+$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
-$data = '';
+$fileContent = '';
-while ($chunk = $client->downloadChunk($docID, $start, $count)) {
+while ($chunk = $client->downloadChunk($fileId, $start, $chunkSize)) {
-     $start += $count;
+     $start += $chunkSize;
-     $data .= $chunk;
+     $fileContent .= $chunk;
-}
-if ($content != $data) {
-    echo "Something is not right!\n";
-} else {
-    echo "We got back: {$data}\n";
 }
-?>
+saveFile($fileName, $fileContent);
 </pre>

KiDocExchange: Difference between revisions

Latest revision as of 16:03, 17 April 2024

Contents

Tutvustus

Failide edastamine ja vastuvõtmine

WSDL

Järgnevusdiagramm

Meetodid

startUpload

uploadFile

uploadChunk

finishUpload

downloadFile

downloadChunk

getDownloadQueue

getStatusCode

getStatusMsg

Veakoodid

Testimine

Näidis pseudokoodina

Navigation menu

KiDocExchange: Difference between revisions

Latest revision as of 16:03, 17 April 2024

Tutvustus

Failide edastamine ja vastuvõtmine

WSDL

Järgnevusdiagramm

Meetodid

startUpload

uploadFile

uploadChunk

finishUpload

downloadFile

downloadChunk

getDownloadQueue

getStatusCode

getStatusMsg

Veakoodid

Testimine

Näidis pseudokoodina

Navigation menu

Search