KiDocExchange: Difference between revisions

From services.krediidiinfo.ee
Jump to navigation Jump to search
No edit summary
No edit summary
 
(18 intermediate revisions by 5 users not shown)
Line 5: Line 5:
= Tutvustus =  
= Tutvustus =  


KiDocExchange on Creditinfo veebiteenus failide saatmiseks Creditinfosse.  
KiDocExchange on Creditinfo veebiteenus failide saatmiseks ja vastuvõtmiseks.


= Failide edastamine =
Faile saab Creditinfole edastada [[KiDocExchange]] SOAP liidese kaudu.


= Failide edastamine ja vastuvõtmine=


Creditinfosse saadetava faili nimi peab olema kujul:
Creditinfosse saadetava faili nimi peab olema kujul:
<pre>
req_<kliendikood>_<toote_kood>_<kuupäev+kellaaeg>.<faililaiend>
nt. req_123456_mhr_20230505124518.xml
</pre>


Creditinfo vastusfaili kuju (kui tegemist on vastust vajava tootega)
<pre>
<pre>
<initsiaalid>_krediidihaldus_<id>.<laiend>
resp_<kliendikood>_<toote_kood>_<kuupäev+kellaaeg>.<faililaiend>
nt. resp_123456_mhr_20230505124518.xml
</pre>
</pre>


* <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.


* <initsiaalid> - ettevõtte initsiaalid. Näiteks Creditinfo puhul <i>ki</i>.
* <id> - faili saatja süsteemis unikaalne id, millega saab saadetud faili identifitseerida. Võib olla ka näiteks faili genereerimise aeg.
* <laiend> - saadetud faili laiend. XML või ZIP. Saadetud faile on soovitav pakkida.


= WSDL =


Näide 1: Creditinfo Eesti AS saadetav fail
KiDocExchange veebiteenuse WSDL fail on aadressil [https://services.krediidiinfo.ee/KiDocExchange.wsdl https://services.krediidiinfo.ee/KiDocExchange.wsdl].




<pre>
= Järgnevusdiagramm =
ki_krediidihaldus_20100613.zip
</pre>


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


= WSDL =
[[Image:KiDocExchange_Upload_Sequence_Diagram.jpg]]


KiDocExchange veebiteenuse WSDL fail on aadressil [http://services.krediidiinfo.ee/KiDocExchange.wsdl http://services.krediidiinfo.ee/KiDocExchange.wsdl].
ja alla laadimisel


[[Image:Download_diagram.png]]


= Järgnevusdiagramm =


Järgnevusdiagrammil on näidatud KiDocExchange meetodite väljakutsumise järjekorrad.
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.
 
[[Image:KiDocExchange_Upload_Sequence_Diagram.jpg]]




Line 67: Line 70:
| xs:integer
| xs:integer
| Unikaalne faili id Creditinfo serveris.
| 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 123: 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 ===
=== downloadChunk ===
Line 261: Line 312:
| Faili staatust täpsustav info
| Faili staatust täpsustav info
|}
|}


= Veakoodid =
= Veakoodid =
Line 305: Line 355:




= Silumine =
= Testimine =


Faili edastamiseks testserverisse tuleb lisada parameeter ''debug'' serveri aadressile, ehk 'https://services.krediidiinfo.ee/soap.php?name=KiDocExchange&debug'
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>
<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';


// Uploading file.
/** INIT CLIENT */
$content = 'I am a little test file!';
$client = new SoapClient(
$docID = $client->startUpload('test.txt');
    $wsdl,
$client->uploadChunk($docID, $content);
    [
        'location' => IN_PRODUCTION_ENV ? $productionLocation : $testLocation,
        'login' => $username,
        'password' => $password
    ]
);


$md5 = md5($content);
/** FILE TRANSFER */
$result = $client->finishUpload($docID, $md5);
$fileId = $client->startUpload($testFileName);
if ($result != 0) {
$md5Actual = $client->uploadFIle($fileId, $testFileContent);
     die("upload failed.! Error code: {$result}\n");
$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);


// 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;
$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>
</pre>

Latest revision as of 15:03, 17 April 2024

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 https://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 = '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);
Retrieved from "https://services.krediidiinfo.ee/wiki/index.php?title=KiDocExchange&oldid=1200"