¶ Veicamie soļi
| Nr. | Darbība | Apraksts |
|---|---|---|
| 0 | Iepazīties ar pieejamajiem datiem un servisiem. | Pirms uzsākt integrācijas darbus, rekomendējams iepazīties ar DAGR publicēto datu struktūrām un pieejamajiem datu izgūšanas servisiem. |
| 1 | Aizpildīt un iesniegt DAGR pieteikuma veidlapu. | Lai iegūtu piekļuvi DAGR pašapkalpošanās portālam un DAGR REST API saskarnei, ir jāaizpilda pieteikuma veidlapa. |
| 2 | Aizpildīt un iesniegt VIRSIS pieteikuma veidlapu. | Lai iegūtu piekļuvi VIRSIS sistēmai, kas ļauj pieprasīt piekļuvi DAGR publicētajām datu kopām, ir jāaizpilda pieteikuma veidlapa. |
| 3 | Pieteikties VIRSIS informācijas pakalpojumam. | Lai iegūtu piekļuvi datu kopai, VIRSIS sistēmā ir jāatrod datu devēja informācijas pakalpojums un uz to jāpiesakās. |
| 4 | Reģistrēt DAGR pašapkalpošanās portālā savienojumu. | DAGR pašapkalpošanās portālā ir jāreģistrē viens vai vairāki tehniskie pieslēgumi jeb savienojumi. |
| 5 | Izgūt datus izmantojot DAGR REST API. | Izmantojot reģistrēto savienojumu un VIRSIS atļaujas numuru, iespējams izgūt datus. |
¶ 0. Iepazīšanās ar pieejamajiem datiem
DAGR API ir aprakstīts OpenAPI (https://www.openapis.org/) standartam atbilstošā formātā un pieejams adresē: https://test.dagr.gov.lv/api
Datu izgūšanas servisu apraksti pieejami https://test.dagr.gov.lv/api sadaļā “Datu servisi”.
Savukārt saraksts ar visām datu kopām, kas tiek izplatītas caur DAGR, pieejams izmantojot servisu: https://test.dagr.gov.lv/service_list, kur katrai datu kopai ir norādīts:
- Datu kopas tehniskais un pilnais nosaukums;
- Datu devēja (īpašnieka) reģistrācijas numurs un nosaukums.
Katrai no datu kopām ir pieejams serviss, kas ļauj izgūt datu kopas ierakstus pēc objekta identifikatora, un serviss, kas ļauj izgūt sarakstu ar izmainītajiem ierakstiem. Izmainīto ierakstu servisu var izmantot gan pirmreizējai visu datu kopas ierakstu atklāšanai, gan jaunāko izmaiņu monitoringam. Atsevišķām datu kopām ir pieejami arī papildus izmaiņu saraksti, kas satur tikai noteiktus biznesa notikumus.
¶ 1. DAGR pieteikuma veidlapa
Lai iegūtu piekļuvi DAGR, ir jāaizpilda DAGR pieteikuma veidlapa. Vairāk informācijas: https://www.vraa.gov.lv/lv/datu-izplatisanas-un-parvaldibas-platforma
Kad ir saņemta atbilde par pieteikuma apstrādi, iesniegumā norādītās personas varēs pieslēgties DAGR pašapkalpošanās portālam.
¶ 2. VIRSIS pieteikuma veidlapa
Lai iegūtu piekļuvi VIRSIS, ir jāaizpilda veidlapa VIRSIS sistēmas iestādes lietotāja administratora izveidei un jānosūta uz VDAA e-adresi. Vairāk informācijas: https://www.vraa.gov.lv/lv/valsts-informacijas-resursu-sistemu-un-sadarbspejas-informacijas-sistema
Kad piekļuve saņemta, VIRSIS sistēmas iestādes lietotājs var izveidot lietotāju kontus pārējiem iestādes darbiniekiem, kam tas nepieciešams.
¶ 3. Pieteikšanās VIRSIS informācijas pakalpojumam
VIRSIS informācijas sistēmā ir jāatrod un jāizvēlas datu devēja informācijas pakalpojums, kas satur datu ņēmējam nepieciešamos datus.
Kad informācijas pakalpojums ir izvēlēts, uz to jāpiesakās. Pieteikšanās procesā būs jānoslēdz un jāparaksta vienošanās par pakalpojuma izmantošanu.
Parakstītās vienošanās numurs tālāk izmantojams kā datu piekļuves atļaujas numurs DAGR sistēmā.
¶ 4. Savienojuma reģistrēšana DAGR portālā
Pēc tam, kad ir apstiprināts datu ņēmēja pieteikums, ir jāreģistrē datu ņēmēja savienojums. Ja datu ņēmējam ir vairākas informācijas sistēmas, kas izgūst datus no DAGR, katrai rekomendējams reģistrēt savu savienojumu.
Datu ņēmēja savienojumus iespējams reģistrēt pašapkalpošanās portāla sadaļas “Piekļuve DAGR” apakšsadaļā “Savienotāji”. Šajā sadaļā ir pieejams saraksts ar visiem savienotājiem / savienojumiem:
Lai reģistrētu jaunu savienotāju, jāaizpilda forma:
Šajā formā jānorāda portālā savienotāja nosaukums (informatīva nozīme), identifikators (tiek izmantots REST API), pazīme, vai savienojums aktīvs, drošības talona dzīves cikla ilgums sekundēs un opcionāls apraksts.
Kad savienojums ir saglabāts, tam iespējams pievienot X.509 standarta drošības sertifikātu:
¶ Informācija par sertifikātu
DAGR pievienotos sertifikātus izmantoto, lai validētu drošības talonu pieprasījums. DAGR pievienojamais x509 sertifikāts var būt arī pašparakstīts. Pastāv vairāki varianti, kā iegūt pašparakstītu X.509 sertifikātu. MS Windows vidē to var izdarīt, uzinstalējot OpenSSL komandrīku un izpildot komandas:
openssl genrsa -out c:\temp\nosaukums.key 2048
Šī komanda ģenerē privāto atslēgu, kas pēc tam būs nepieciešama, lai parakstītu drošības talona pieprasījumu. Privātā atslēga paliek pie datu patērētāja un tās aizsargāšana ir datu patērētāja pienākums.
openssl req -key c:\temp\nosaukums.key -new -x509 -subj "/C=LV/ST=Riga/L=Riga/O=Iestades_nosaukums/OU=IT/CN=nosaukums" -days 365 -out c:\temp\nosaukums.crt
Šī komanda ģenerē pašparakstītu X.509 sertifikātu, kuru jāpievieno DAGR reģistrētajam datu patērētāja savienotājam.
¶ 5. Datu izgūšana
¶ Autentifikācija (drošības talona pieprasīšana)
Datu patērētāja savienotāji tiek autentificēti un autorizēti saskaņā ar OAuth 2.0 OpenId Connect standarta Client Credentials Flow plūsmu.
Lai izgūtu datus no DAGR, vispirms ir jāiegūst JWT drošības talons. Drošības talona pieprasīšanas adrese (testa vidē): https://test.dagr.gov.lv/jwt/connect/token
Drošības talona izsaukuma piemērs:
curl --location 'https://parvaldiba-test.dagr.gov.lv/Identities.STS/connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Cache-Control: no-cache' \
--data-urlencode 'client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer' \
--data-urlencode 'client_assertion=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJWQVJBTV90ZXN0X2Nvbm5lY3Rvcl8xIiwianRpIjoiMmFiYWIyOTctNDViNC00ZjdkLTg5NWYtOTMxM2JlN2Q0ZTE1IiwiaXNzIjoiVkFSQU1fdGVzdF9jb25uZWN0b3JfMSIsImF1ZCI6InVybjpURVNULUxOQjpEQUdSLlNUUy9jb25uZWN0L3Rva2VuIiwiZXhwIjoiMTY4MTgyNDkzOSIsIm5iZiI6IjE2ODE4MjEzMzkifQ.cDurogXmRZljUQ7WHrF9A_pV26WSeljBZCKPx3QSDs4lA_c2oxSRVdn_laqSpNydlmGAEpD9o0dgvP7efwq-w7jldf_4lY8TJyrju_niPaE3krIVIlA_Auwv7q66k_TW6jjWUd2jGuqgDLYGuRMgIGTMYVv9qVN70ctEBRAJzLyVFZAK3Z72EOzv_YkKGxb4NnVf4CAbXl6qQSU5dAYz0DPbMvdHGH2AsMNsXeGTuSf7SVQvIl5CShMm1Kwr2D0B6tsruuAGcdj92Z8tupy2InDB-rti6cpTorTdNPQcClcegGbQDSt1SK9k7XsVJf4_Youe3EBCXIcCGindtxc2AQ' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=VARAM_test_connector_1' \
--data-urlencode 'scope=consumer' `
Šajā izsaukumā client_id ir jānorāda datu patērētāja savienotāja identifikators un client_assertion ir jāsagatavo atbilstoši RFC 7515 JSON Web Signature(JWS) standartam. Respektīvi, client_assertion sastāv no 'Header' un 'Payload', kas parakstīti ar datu patērētāja savienotāja privāto atslēgu. ‘Header’ veidojams kā JSON objekts, kas satur paraksta parametrus, piemēram:
{
"typ" : "JWT",
"alg" : "RS256"
}
'Payload' ir iekļaujama šāda informācija (testa videi):
{
"sub": {datu patērētāja savienotāja id},
"jti": {uuid},
"iss": {datu patērētāja savienotāja id},
"aud": urn:TEST-LNB:DAGR.STS/connect/token,
"exp": {derīguma termiņš, max nbf + 1 stunda},
"nbf": {parakstīšanas datums un laiks}
}
Drošības talona izsaukuma atbildes piemērs:
{
"access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjIxMEZCQkFCNzE3NzFCRTcyOTIyNTk0NTBBMjhDMjcyNzc5NTZFNkVSUzI1NiIsInR5cCI6ImF0K2p3dCIsIng1dCI6IklRLTdxM0YzRy1jcElsbEZDaWpDY25lVmJtNCJ9.eyJuYmYiOjE2Nzk1MDYwODYsImV4cCI6MTY3OTUwOTY4NiwiaXNzIjoidXJuOlRFU1QtTE5COkRBR1IuU1RTIiwiYXVkIjoidXJuOlRFU1QtTE5COmRhZ3IuY29yZS5hcGkiLCJjbGllbnRfaWQiOiJVTklTT190ZXN0X2Nvbm5lY3Rvcl8xIiwibGVnYWxlbnRpdHkiOiI0MDAwMzU2Mjg2MyIsImp0aSI6IjA5OERGMTYyQ0Y2OEY0Mjk4OTJENTk3Qjk3RjlCNTBBIiwiaWF0IjoxNjc5NTA2MDg2LCJzY29wZSI6WyJkYWdyX2NvcmVfYXBpIl19.Cm0kgNBKfNR0Mo63ZLkCYMzPZ9v8XbfHWE1Lgvz907k1Ama2SqiWE68oMcBlAXJEUyYJ8ipQCY7aCmjVEN3AZ6qV1lcRPtURQ53EUKXs5B8S3aQfxOu2ne3rnDKhaZXi0rHRMTAUcTJWmeXWFA5m-FcvFrhZgTYuM2zq-L5VY-mgJ1VOzOXj9_5eUALBLHBLJF9lLPZQckao4VAn-Zwvly_sn1iojFK6409AJVzC5pVdAL4AqaMrQ6QtrrxIkOEa8c6qxOMKGiXTMncc_uwjtEES3HhVsrJuZkQdDW0zCMKIoKXj8UGkD6PskJdP3b28aHAlogGcoZkL5m80sXvfhQ",
"expires_in": 3600,
"token_type": "Bearer",
"scope": "consumer"
}
Izsniegtais drošības talons atbilst RFC 7519 standartam un drošības talona satura pārlūkošanai ērti izmantot: https://jwt.io/
Postman piemērs drošības talona izsaukumam un datu izguves izsaukumiem pieejams: https://api.postman.com/collections/9631194-e7289644-5aa8-4639-8d4f-80c8591f2a49?access_key=PMAT-01GPE6A92NR3T5PNH5MTB9KMWD
Lai Postman programmā ielādētu kolekciju, jāizvēlas darbība “File” -> “Import” un jāiekopē augstākminētajā adresē pieejamais teksts. Lai varētu izpildīt drošības talona pieprasīšanas piemēru, Postman programmā ir jāpievieno un jāaktivizē mainīgo vide (environment). Instrukcija, kā izveidot un pārvaldīt mainīgo vides pieejama Postman ražotāja mājas lapā: https://learning.postman.com/docs/sending-requests/variables/managing-environments
¶ Atļauju noskaidrošana
Lai izgūtu datus, pieprasījumā ir jānorāda VIRSIS izsniegtās atļaujas numurs. Datu patērētājam pieejamās atļaujas var izgūt arī no DAGR. Ar katru datu kopu var būt saistīta viena vai vairākas aktīvas datu piekļuves atļaujas. DAGR atļauju sarakstu regulāri aktualizē no VIRSIS.
Datu piekļuves atļaujas apskatāmas DAGR pašapkalpošanās portāla sadaļā “Patērēšana” -> “VIRSIS atļaujas”.
Alternatīvi, atļauju sarakstu var izgūt arī ar metodi: https://test.dagr.gov.lv/current_user_permissions
Metodes izsaukuma piemērs:
curl --location --request GET 'https://test.dagr.gov.lv/current_user_permissions' \
--header 'Authorization: Bearer {autentifikācijas ietvaros saņemtais drošības talons}'
Atbildes piemērs (servisa nosaukums un atļaujas numurs iekrāsoti spilgti sarkanā):
{
"service_name": "fpr_person",
"permission_number": "32423536",
"purpose_of_use": "testēšanai, pilnas tiesības uz personas datiem",
"use_count": 0,
"use_count_quota": 0,
"valid_from": null,
"valid_to": null,
"access_control_tree": {
"name": "fpr_person",
"read_access": "full"
}
},
{
"service_name": "fpr_person",
"permission_number": "23532235",
"purpose_of_use": "testēšanai, daļējas tiesības uz personas datiem",
"use_count": 0,
"use_count_quota": 0,
"valid_from": null,
"valid_to": null,
"access_control_tree": {
"name": "fpr_person",
"read_access": "partial",
"properties": [
{
"name": "PersonCode",
"read_access": "full"
},
{
"name": "ActualPersonCode",
"read_access": "full"
},
{
"name": "PersonsCode",
"read_access": "none"
},
{
"name": "PersonsName",
"read_access": "partial",
"properties": [
{
"name": "ReasonCode",
"read_access": "none"
},
{
"name": "ReasonName",
"read_access": "none"
},
{
"name": "ValidFrom",
"read_access": "none"
},
{
"name": "FirstName",
"read_access": "full"
},
{
"name": "LastName",
"read_access": "full"
},
{
"name": "OtherNames",
"read_access": "full"
}
]
},
{
"name": "PersonsBirth",
"read_access": "none"
},
{
"name": "PersonsDocument",
"read_access": "none"
},
{
"name": "PersonsResidence",
"read_access": "none"
},
{
"name": "PersonsDeath",
"read_access": "none"
}
]
}
}
]
¶ Datu objekta izgūšana pēc objekta identifikatora
Visām DAGR izplatāmajām datu kopām ir nodrošināta datu izgūšana pēc objekta identifikatora.
Katrai datu kopai ir savs datu izgūšanas serviss. Katram datu izgūšanas servisam ir savs noteikts objekta identifikators, pēc kā ieraksts tiek meklēts. Šis identifikators ir norādīts servisa aprakstā. Par objektu identifikatoriem tiek izmantotas faktiskas biznesa vērtības, piemēram – personas kods, reģistrācijas numurs, dokumenta numurs, adreses kods. Dažos gadījumos tiek izmantoti salikti kodi, kas sastāv no vairākām vērtībām, piemēram, uzņēmumu gada pārskatiem tiek izmantots gads un uzņēmuma reģistrācijas numurs.
Datu izgūšanas pēc objekta identifikatora servisi veidoti kā GET RESTful tipa pakalpes ar adresi šādā formā: https://test.dagr.gov.lv/{datu_kopa}/{objekta_identifikators}
Servisa galvenē “X-DAGR-Permission” ir jānorāda VIRSIS atļaujas numurs.
Servisa izsaukuma piemērs – Valsts adrešu reģistra adrese pēc adreses koda:
curl --location --request GET 'https://test.dagr.gov.lv/vzd_address/112022722' \
--header 'Authorization: Bearer {autentifikācijas ietvaros saņemtais drošības talons}' \
--header 'X-DAGR-Permission: {VIRSIS atļaujas numurs}'
Atbilde būs pilni objekta dati JSON formātā.
Atbildes piemērs – adreses dati JSON formātā:
{
"ielCode": 100300132,
"novName": null,
"zipCode": "LV-1057",
"dzvName": "18",
"nltCode": 101848550,
"code": 112022722,
"cieName": null,
"pagAtvk": null,
"typ": 109,
"address": "Aglonas iela 31 - 18\nRīga",
"lksCoordLat": 307682.939,
"pilAtvk": "0001000",
"pagName": null,
"pagCode": null,
"adr_code": "112022722",
"dzvCode": 112022722,
"novAtvk": null,
"ielName": "Aglonas iela",
"novCode": null,
"nltName": "31",
"irAdrese": true,
"history": [
{
"adrese": "Aglonas iela 31, dz. 18, Rīga"
}
],
"lksCoordLong": 511254.388,
"pilCode": 100003003,
"cieCode": null,
"pilName": "Rīga"
}
Papildus servisa izsaukuma piemērs – UR juridiskā persona pēc reģistrācijas numura:
curl --location --request GET 'https://test.dagr.gov.lv/ur_legal_entity/40001016757' \
--header 'Authorization: Bearer {autentifikācijas ietvaros saņemtais drošības talons}' \
--header 'X-DAGR-Permission: {VIRSIS atļaujas numurs}'
Atbilde būs pilni objekta dati JSON formātā.
¶ Datu izmaiņu izgūšana un pilnas datu kopas pārlasīšana
Visām DAGR izplatāmajām datu kopām ir nodrošināta iespēja izgūt datu izmaiņas.
Izmaiņu izgūšanas servisi veidoti kā GET RESTful tipa pakalpes ar adresi šādā formā: https://test.dagr.gov.lv/{datu_kopa}_changes
Servisa galvenē “X-DAGR-Permission” ir jānorāda VIRSIS atļaujas numurs.
Šiem servisiem ir trīs opcionāli parametri:
- offset – izmaiņu ieraksta kārtas numurs, no kura sākt izmaiņu atlasi. Var izmantot arī negatīvus skaitļus, tādā gadījumā serviss atgriezīs norādītā skaita pēdējos ierakstus. Piemēram, norādot -2, tiks atgriezti divi pēdējie ieraksti;
- timestamp – datums un laiks, no kura sākt izmaiņu atlasi;
- limit – atbildē atgriežamo ierakstu skaits. Noklusētā vērtība ir 100.
Ja netiek norādīts ne offset, ne timestamp parametrs, tad serviss atgriezīs vienu pēdējo izmaiņu ierakstu.
Izmaiņu servisa atbilde satur izmaiņu ierakstus JSON formātā, kur katram ierakstam ir šāda struktūra:
{
"offset": izmaiņu_kārtas_numurs,
"key": "ieraksta_identifikators",
"timestamp": "izmaiņu_pievienošanas_datums_un_laiks",
"value": { ieraksta_dati_kā_JSON_objekts
},
}
BŪTISKI: Datu kopas izmaiņu rinda satur tikai informāciju par pēdējo reizi, kad konkrētais ieraksts ir mainīts. Līdz ar to, izmaiņu servisu var izmantot visu datu kopas ierakstu atklāšanai un aktuālo izmaiņu monitoringam, bet to nevar izmantot vēstures datu atlasei. Gadījumos, kur datu kopa satur vēsturisku izmaiņu datus, tās ir iekļautas ierakstu datu struktūrā. Kā blakus efekts, izmaiņu kārtas numuri var izkrist, bet, izgūstot izmaiņu datus, tie vienmēr tiks atgriezti augošā secībā.
Datu izmaiņu izgūšanas pielietojumi:
- Ierakstu atklāšana. Lai atklātu visus datu kopas datu ierakstus, ir vispirms jāizsauc izmaiņu serviss bez offset vai timestamp parametriem. Tad jānolasa atbilde un jāpiefiksē offset vērtība pēdējam saņemtajam izmaiņu ierakstam. Tālāk jāveido nākamais pieprasījums, offset parametrā norādot piefiksēto pēdējo nolasīto izmaiņu kārtas numuru. Šādā veidā iterējot cauri visiem izmaiņu ierakstiem, līdz tiek saņemta tukša atbilde, var atklāt visus datu kopas ierakstus.
- Izmaiņu monitorings. Lai sekotu aktīvajām izmaiņām, var izmantot izmaiņu offset vai timestamp vērtības. Sistēmā, kas monitorē datu kopu, ir jāizveido process, kas ar noteiktu regularitāti pieprasa datus atbilstošajam DAGR izmaiņu servisam. Pēc datu nolasīšanas sistēmā, kas monitorē datu kopu, ir jāpiefiksē pēdējo nolasīto izmaiņu offset vai timestamp, lai pie nākamās datu nolasīšanas reizes tiktu saņemtas tikai jaunākās izmaiņas.
Izmaiņu servisa izsaukuma piemērs:
curl --location 'https://test.dagr.gov.lv/ur_legal_entity_changes?offset=0&limit=100' \
--header 'Authorization: Bearer {autentifikācijas ietvaros saņemtais drošības talons}' \
--header 'X-DAGR-Permission: {VIRSIS atļaujas numurs}'
Izmaiņu servisa atbildes piemērs:
[{
"key": "40900000031",
"offset": 0,
"timestamp": "2023-03-20T09:53:03.031",
"value": {
"address": {
"addressComplete": "\"Striķu skola\", Zvārdes pag., Saldus nov., LV-3883",
"addressRegisterCode": 106245206,
"county": "Saldus nov.",
"houseName": "Striķu skola",
"parish": "Zvārdes pag.",
"postalCode": "LV-3883"
},
"cleanedShortName": "STRIKU SAKUMSKOLA",
"isAnnulled": false,
"lastModifiedAt": "2022-03-24T09:14:53.615Z",
"links": {
"self": "/legal-entity/40900000031"
},
"liquidations": [],
"name": "Striķu sākumskola",
"officers": [
{
"appointedOn": "2001-07-05",
"id": 100010293,
"isAnnulled": false,
"lastModifiedAt": "2019-10-31T14:12:00.114Z",
"naturalPerson": {
"forename": "Daina",
"latvianIdentityNumber": "071063-12857",
"surname": "Zandberga"
},
"position": "GENERAL_MANAGER",
"positionDetails": "Iestādes direktore",
"registeredOn": "2019-10-31"
}
],
"publicAuthorityDetails": {
"contactDetails": {
"email": "striku.sakumskola@saldus.lv",
"phone": "+37163846132",
"website": "http://strikuskola.saldus.lv/"
},
"delegatedEntities": [],
"establishingAct": {
"date": "2016-01-28",
"legislatorName": "Saldus novada dome",
"legislatorNumber": "90009114646",
"number": "1.7.",
"title": "Saldus novada domes lēmums",
"type": "DECISION"
},
"registrationDetails": {
"authorityType": "INSTITUTION_OF_INDIRECT_ADMINISTRATION",
"establishedOn": "2016-01-28",
"higherAuthorityCurrentName": "Saldus novada pašvaldība",
"higherAuthorityNumber": "90009114646",
"isIndependentTaxpayer": false,
"isInstitutionOfHigherEducation": false,
"subordinationType": "CONTROL",
"taxpayerUnitNumber": "90009189123"
},
"schoolBranches": []
},
"register": "PUBLIC_PERSONS_INSTITUTIONS",
"registeredOn": "2018-03-08",
"registrationNumber": "40900000031",
"registrationNumberAssignedOn": "2018-03-08",
"reorganizations": [],
"status": "REGISTERED",
"type": "PUBLIC_BODY"
}
}
]