¶ Priekšnosacījumi
¶ Pieteikums
Lai varētu izveidot savienojumu un izgūt datus, DAGR portālā ir jābūt reģistrētam un apstiprinātam datu ņēmēja pieteikumam.
Pieteikšanās process detalizētāk aprakstīts datu ņēmēja ceļa kartē.
¶ Savienojums un drošības talons
Pieslēgšanās pie DAGR REST API notiek ar tehniskajiem lietotājiem jeb savienojumiem. Savienojumus datu ņēmēja kontaktpersonas reģistrē DAGR pašapkalpošanās portālā un tālāk ar savienojumā norādīto informāciju no DAGR REST API tiek pieprasīts drošības talons. Iegūtais drošības talons tālāk jāpievieno visiem datu pieprasījumiem galvenē ar nosaukumu "Authorization".
Savienojumu reģistrēšanas un drošības talona pieprasīšanas procesi detalizētāk arpakstīti autentifikācijas sadaļā.
¶ Atļaujas
Atļaujas piekļūt DAGR datu kopām tiek pārvaldītas VIRSIS sistēmā. Pieprasot datus pieprasījuma galvenē ar nosaukumu "X-DAGR-Permission" ir jānorāda atbilstošās atļaujas numurs.
Datu ņēmējam pieejamās atļaujas var aplūkot DAGR portālā vai arī noskaidrot ar DAGR REST API izsaukuma palīdzību. DAGR portālā VIRSIS atļaujas aplūkojamas sadaļā "VIRSIS atļaujas": 
Savukārt, izmantojot DAGR REST API, atļauju sarakstu var iegūt ar izsaukumu formā GET {dagr_adrese}/current_user_permissions, galvenē "Authorization" norādot izgūto drošības talonu.
Izsaukuma piemērs:
curl --location 'https://test.dagr.gov.lv/current_user_permissions' \
--header 'Authorization: ••••••'
Atbildes piemērs:
[
{
"service_name": "vzd_address",
"permission_number": "1321",
"purpose_of_use": "Vienošanās pieteikuma datu izmantošanas mērķis (TEST JH)",
"use_count": 1,
"use_count_quota": 1321,
"valid_from": null,
"valid_to": null,
"access_control_tree": {
"name": "vzd_address",
"read_access": "full",
"properties": null
}
},
{
"service_name": "fpr_person",
"permission_number": "22791",
"purpose_of_use": "Pilnvarojamās fiziskās personas datu pārbaude PMLP FPR, pilnvaras sagatavošanas procesa ietvaros.",
"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",
"properties": null
},
{
"name": "ActualPersonCode",
"read_access": "none",
"properties": null
},
{
"name": "PersonsCode",
"read_access": "partial",
"properties": [
{
"name": "ValidFrom",
"read_access": "none",
"properties": null
},
{
"name": "ValidUntil",
"read_access": "none",
"properties": null
},
{
"name": "PersonCode",
"read_access": "full",
"properties": null
}
]
},
{
"name": "PersonsName",
"read_access": "partial",
"properties": [
{
"name": "ReasonCode",
"read_access": "none",
"properties": null
},
{
"name": "ReasonName",
"read_access": "none",
"properties": null
},
{
"name": "ValidFrom",
"read_access": "none",
"properties": null
},
{
"name": "FirstName",
"read_access": "full",
"properties": null
},
{
"name": "LastName",
"read_access": "full",
"properties": null
},
{
"name": "OtherNames",
"read_access": "full",
"properties": null
}
]
},
{
"name": "PersonsBirth",
"read_access": "none",
"properties": null
},
{
"name": "PersonsDocument",
"read_access": "none",
"properties": null
},
{
"name": "PersonsResidence",
"read_access": "none",
"properties": null
},
{
"name": "PersonsDeath",
"read_access": "partial",
"properties": [
{
"name": "ReasonCode",
"read_access": "none",
"properties": null
},
{
"name": "ReasonName",
"read_access": "none",
"properties": null
},
{
"name": "ValidFrom",
"read_access": "none",
"properties": null
},
{
"name": "DeathDate",
"read_access": "full",
"properties": null
},
{
"name": "DeathTime",
"read_access": "none",
"properties": null
},
{
"name": "IsApproximateDeathDate",
"read_access": "none",
"properties": null
},
{
"name": "DeathPlaceCountryCode",
"read_access": "none",
"properties": null
},
{
"name": "DeathPlaceCountryName",
"read_access": "none",
"properties": null
},
{
"name": "PersonDeathPlaceFormatted",
"read_access": "none",
"properties": null
}
]
}
]
}
}
]
Atļaujas datu struktūras skaidrojums:
- service_name - nosaka DAGR datu izsniegšanas servisu, uz kuru atļauja attiecināta. Servisu saraksts aplūkojams https://test.dagr.gov.lv/api (testa vidē) un https://dagr.gov.lv/api (produkcijas vidē) sadaļā "Datu servisi";
- permission_number - atļaujas unikālais numurs, kas jānorāda pieprasījuma galvenē "X-DAGR-Permission", izsaucot datu servisus;
- purpose_of_use - atļaujas izmantošanas mērķis, kas tiek saglabāts datu pieprasījumu auditā;
- use_count - datu servisa izmantoto izsaukuma reižu skaits, kas tiek uzturēts tikai gadījumā, ja atļaujā ir noteikta datu izsaukumu reižu skaita kvota;
- use_count_quota - datu izsaukumu reižu skaitu kvota, kas nosaka, cik datu pieprasījumus ar šo atļauju kopumā var veikt;
- valid_from - atļaujas sākuma datums. Atļauja nav aktīva pirms šī datuma. Ja vērtība ir null, tad atļaujai nav sākuma datuma ierobežojuma;
- valid_to - atļaujas beigu datums. Atļauja nav aktīva pēc šī datuma. Ja vērtība ir null, tad atļaujai nav beigu datuma ierobežojuma;
- access_control_tree - koka veida struktūra, kas nosaka datu servisa atbildes datu struktūras datu laukus / hierarhijas elementus, kuriem datu ņēmējam ir piekļuve:
- name - datu lauka vai hierarhijas elementa nosaukums;
- read_access - piekļuves līmenis. Iespējamās vērtības - full, partial un none. "full" nozīmē, ka datu ņēmējam ir piekļuve datu laukam vai hierarhijas elementam ar visiem apakšelementiem. "partial" nozīmē, ka datu ņēmējam ir piekļuve datu laukam vai elementam, bet apakšelementiem katram ir noteikts atsevišķs piekļuves līmenis. "none" nozīmē, ka datu ņēmējam nav piekļuves datu laukam vai hierarhijas elementam un tā apakšelementiem. Ja apakšelementa piekļuves līmenis ir pretrunā ar virselementa piekļuves līmeni, tad par noteicošo tiek uzskatīts virselementa piekļuves līmenis.
- properties - pagaidām netiek izmantots.
Lai arī VIRSIS datu atļaujas ir apskatāmas DAGR, tās tiek piešķirtas un pārvaldītas VIRSIS sistēmā. Lai iegūtu datu piekļuves atļauju, datu ņēmējam VIRSIS sistēmā ir jāpiesakās uz datu devēja informācijas pakalpojumu un jānoslēdz vienošanās par tā izmantošanu. Vienošanās iekļautā informācija veido atļaujas saturu un vienošanās identifikators atbilst atļaujas numuram.
¶ Ierakstu atlase pēc 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. Servisu saraksts aplūkojams https://test.dagr.gov.lv/api (testa vidē) un https://dagr.gov.lv/api (produkcijas vidē) sadaļā "Datu servisi".
Datu izgūšanas pēc objekta identifikatora servisi veidoti kā GET tipa pakalpes ar adresi formā: https://{dagr_adrese}/{datu_kopa}/{objekta_identifikators}. Papildus, servisa galvenē “X-DAGR-Permission” ir jānorāda VIRSIS atļaujas numurs un servisa galvenē "Authorization" ir jānorāda drošības talons.
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 atlasītā objekta dati JSON formātā atļaujā norādītajā apmērā.
Atbildes piemērs:
{
"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}'
¶ PMLP datu īpatnības
PMLP fizisko personu datu kopai fpr_person ir īpašs PMLP noteikts veids, kā tiek izplatīti dati par personām, kurām ir mainījies personas kods. Ja atlasa personas datus pēc vecā personas koda, tad ierakstā visi lauki izņemot "PersonCode" un "ActualPersonCode" saturēs tukšas (null) vērtības. Lai iegūtu personas datus šajos gadījumos, tie ir jāpieprasa par jaunu, izmantojot jauno personas kodu. Vienkāršs veids, kā noteikt šos gadījumus, ir salīdzināt "PersonCode" un "ActualPersonCode" - ja tie atšķiras, tad jāpieprasa dati ar jauno personas kodu.
Izsaukuma piemērs - personas dati pēc vecā personas koda:
curl --location 'https://test.dagr.gov.lv/fpr_person/03109919998' \
--header 'X-DAGR-Permission: 1339' \
--header 'Authorization: ••••••'
Atbildes pimērs - personas dati pēc vecā personas koda:
{
"PersonCode": "03109919998",
"ActualPersonCode": "32777181979",
"PersonsCode": null,
"PersonsName": null,
"PersonsBirth": null,
"PersonsCitizenship": null,
"PersonsDocument": null,
"PersonsPoliticallyRepressedStatus": null,
"PersonsResidence": null,
"PersonsResistanceMemberStatus": null,
"PersonsStatusFPR": null,
"PersonsDeath": null
}
Izsaukuma piemērs - personas dati pēc jaunā personas koda:
curl --location 'https://test.dagr.gov.lv/fpr_person/32777181979' \
--header 'X-DAGR-Permission: 1339' \
--header 'Authorization: ••••••'
Atbildes pimērs - personas dati pēc jaunā personas koda:
{
"PersonCode": "32777181979",
"ActualPersonCode": "32777181979",
"PersonsCode": [
{
"PersonCode": "32777181979",
"ValidFrom": "2022-08-12T00:00:00+03:00",
"ValidUntil": null
},
{
"PersonCode": "03109919998",
"ValidFrom": "1999-10-05T00:00:00+03:00",
"ValidUntil": "2022-08-12T00:00:00+03:00"
}
],
"PersonsName": {
"LastName": "DAGRE",
"FirstName": "MAIGA",
"ReasonName": "LATVIJAS VALSTSPIEDERĪGĀ PIRMUZSKAITE",
"ReasonCode": "PUZL",
"ValidFrom": "1999-10-05T00:00:00+03:00",
"OtherNames": null
},
"PersonsBirth": {
"BirthPlaceCountryCode": "LVA",
"BirthPlaceFormatted": "LIEPĀJA",
"BirthDate": "1999-10-03T00:00:00+03:00",
"IsBornDead": false,
"ReasonName": "LATVIJAS VALSTSPIEDERĪGĀ PIRMUZSKAITE",
"BirthPlaceCountryName": "LATVIJA",
"ValidFrom": "1999-10-05T00:00:00+03:00",
"ReasonCode": "PUZL",
"BirthTime": "2024-01-04T15:25:00+02:00"
},
"PersonsCitizenship": [
{
"CountryCode": "LVA",
"CountryName": "LATVIJAS",
"ValidFrom": "1999-10-05T00:00:00+03:00",
"CitizenshipTypeCode": "P",
"CitizenshipTypeName": "PILSONIS"
}
],
"PersonsDocument": [
{
"DocumentIssuingCountryCode": "LVA",
"DocumentKindCode": "PRAP",
"ReasonName": "OTRA VEIDA DOKUMENTA SAŅEMŠANA",
"DocumentNumber": "PA4091765",
"ValidFrom": "2022-08-12T00:00:00+03:00",
"DocumentIssuingDate": "2022-08-12T00:00:00+03:00",
"DocumentKindName": "PERSONAS APLIECĪBA",
"ReasonCode": "OTRADOKS",
"DocumentIssuingPlace": null,
"DocumentIssuingCountryName": "LATVIJA",
"DocumentValidityDate": "2032-08-11T00:00:00+03:00",
"DocumentIssuingOrganizationName": "PMLP RĪGAS 4.NODAĻA"
}
],
"PersonsPoliticallyRepressedStatus": null,
"PersonsResidence": {
"CountryCode": "LVA",
"LocalGovernmentCode": "0044000",
"CountryName": "LATVIJA",
"ArisCode": "118747094",
"AddressFormatted": "\"ACONES STACIJA\" - 1, STOPIŅU PAGASTS, ROPAŽU NOVADS, LV-2130",
"ReasonName": "DEKLARĒTĀS DZĪVESVIETAS ZIŅAS",
"RegionCode": null,
"ValidFrom": "2003-06-16T00:00:00+03:00",
"ReasonCode": "DKDZ",
"TerritorialUnitCode": "0044420"
},
"PersonsResistanceMemberStatus": null,
"PersonsStatusFPR": {
"StatusValidFrom": "1999-10-05T00:00:00+03:00",
"StatusValueCode": "1",
"StatusValueTitle": "ir statuss AKTĪVS"
},
"PersonsDeath": null
}
¶ SOPA datu īpatnības
Caur DAGR tiek izplatīti pašvaldību SOPA sistēmas trūcīgo un maznodrošināto dati. Katra pašvaldība šajā gadījumā ir atsevišķs datu devējs, kurš uz savu datu izmantošanu VIRSIS sistēmā piešķir atsevišķu atļauju.
Neskatoties uz to, ka datu devēji ir vairāki un atļaujas ir vairākas, servisi datu izgūšanai pēc identifikatora (personas koda) ir tikai divi. Tie ir formā:
GET /sopa_needy/{district_atvk}/{person_code}serviss trūcīgo datu datu izguvei pēc personas koda;GET /sopa_underprivileged/{district_atvk}/{person_code}serviss maznodrošināto datu izguvei pēc personas koda.
Lai izgūtu datus no dažādām pašvaldībām, servisa izsaukumā ir jāmaina ATVK kods (district_atvk) un atbilstošais atļaujas numurs galvenē "X-DAGR-Permission".
¶ Izmaiņu atlase
Visām DAGR izplatāmajām datu kopām ir nodrošināta iespēja izgūt datu izmaiņas.
Servisa adrese. Izmaiņu izgūšanas servisi veidoti kā GET tipa pakalpes ar adresi formā:
https://test.dagr.gov.lv/{datu_kopa}_changes
Servisa galvenes. Servisa galvenē “X-DAGR-Permission” ir jānorāda VIRSIS atļaujas numurs un servisa galvenē "Authorization" ir jānorāda drošības talons.
Servisa parametri. Izmaiņu izgūšanas 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. Ja netiek norādīts ne offset, ne timestamp parametrs, tad serviss atgriezīs vienu pēdējo izmaiņu ierakstu.
- timestamp – datums un laiks, no kura sākt izmaiņu atlasi. Ja netiek norādīts ne offset, ne timestamp parametrs, tad serviss atgriezīs vienu pēdējo izmaiņu ierakstu.
- limit – atbildē atgriežamo ierakstu skaita limits. Noklusētā vērtība ir 100.
Servisa atbilde. Izmaiņu servisa atbilde satur sarakstu ar izmaiņu ierakstiem JSON formātā, kur katram ierakstam ir šāda struktūra:
{
"offset": izmaiņu_kārtas_numurs,
"timestamp": "izmaiņu_pievienošanas_datums_un_laiks",
"key": "ieraksta_identifikators",
"value":
{
ieraksta_dati_kā_JSON_objekts
}
}
Ja ieraksta atbildē "value" vērtība ir null, tad tas nozīmē, ka ieraksts ar norādīto atslēgu ir iepriekš pastāvējis, bet pēdējā izmaiņa ir ieraksta dzēšanas darbība.
BŪTISKI: Datu kopas izmaiņu rinda veidota tā, lai tā saturētu tikai informāciju par pēdējo reizi, kad katrs unikālais ieraksts ir mainīts. Līdz ar to izmaiņu servisu var izmantot visu datu kopas ierakstu atklāšanai un sekošanai līdzi aktuālajām izmaiņām, 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ā.
Mehānisms, kas no izmaņu rindas dzēš neaktuālās ieraksta vērtības, ir asinhrons. Tamdēļ var gadīties situācijas, kur izmaiņu rindā īslaicīgi atrodami divi ieraksti ar vienādām atslēgām. Šajos gadījumos par ieraksta aktuālo vērtību jāuzskata pēdējā izmaiņa (ar lielāko offset vērtību). 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 servisa pielietojumi:
- Ierakstu atklāšana. Lai atklātu visus datu kopas datu ierakstus, ir vispirms jāizsauc izmaiņu serviss ar offset vērtību 0. 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.
- Sekošana izmaiņām. Lai sekotu aktīvajām izmaiņām, var izmantot izmaiņu offset vai timestamp vērtības. Sistēmā, kas seko līdzi datu izmaiņām, 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 seko līdzi datu izmaiņām, ir jāpiefiksē pēdējo nolasīto izmaiņu offset vai timestamp, lai pie nākamās datu nolasīšanas reizes to izmantotu kā ieejas parametru, tādējādi saņemot tikai jaunākās izmaiņas. Izmaiņu serviss pēc noklusējuma ļauj sekot līdzi izmaiņām visos datu kopas ierakstos, bet ir arī iespēja sekot līdzi izmaiņām tikai specifiskos sevi interesējošos ierakstos, kas aprakstīta sadaļā "izmaiņu monitorings".
Izmaiņu servisa izsaukuma piemērs:
curl --location 'https://test.dagr.gov.lv/vzd_address_changes?offset=-3&limit=100' \
--header 'X-DAGR-Permission: 54654' \
--header 'Authorization: ••••••'
Izmaiņu servisa atbildes piemērs:
[
{
"key": "119575762",
"offset": 1447457,
"timestamp": "2024-11-15T04:55:34.556Z",
"value": {
"adr_code": "119575762",
"address": "Gaujas iela 5C - 27\nMārupe\nMārupes nov.",
"code": 119575762,
"cieCode": null,
"cieName": null,
"dzvCode": 119575762,
"dzvName": "27",
"ielCode": 100391101,
"ielName": "Gaujas iela",
"lksCoordLong": 503335.553,
"lksCoordLat": 306236.786,
"nltCode": 104467817,
"nltName": "5C",
"novCode": 100016583,
"novName": "Mārupes nov.",
"pagCode": null,
"pagName": null,
"pilCode": 100003815,
"pilName": "Mārupe",
"typ": 109,
"pilAtvk": "0039200",
"novAtvk": "0039000",
"pagAtvk": null,
"zipCode": "LV-2167",
"irAdrese": true,
"history": []
}
},
{
"key": "119576112",
"offset": 1447458,
"timestamp": "2024-11-15T04:55:37.158Z",
"value": {
"adr_code": "119576112",
"address": "Murjāņu iela 61A - 16\nRīga",
"code": 119576112,
"cieCode": null,
"cieName": null,
"dzvCode": 119576112,
"dzvName": "16",
"ielCode": 100308942,
"ielName": "Murjāņu iela",
"lksCoordLong": 514852.251,
"lksCoordLat": 315282.343,
"nltCode": 101956050,
"nltName": "61A",
"novCode": null,
"novName": null,
"pagCode": null,
"pagName": null,
"pilCode": 100003003,
"pilName": "Rīga",
"typ": 109,
"pilAtvk": "0001000",
"novAtvk": null,
"pagAtvk": null,
"zipCode": "LV-1064",
"irAdrese": true,
"history": []
}
},
{
"key": "105390046",
"offset": 1447459,
"timestamp": "2024-11-15T04:55:39.010Z",
"value": null
}
]
Uzmanību piemērā var pievērst pēdējam ierakstam, kas satur "value" ar vērtību null. Tas nozīmē, ka adrese ar adreses kodu 105390046 no adrešu reģistra ir dzēsta.
¶ PMLP izmaiņu datu īpatnības
PMLP datu kopai fpr_person izmaiņas uz DAGR tiek nodotas nevis uzreiz visam ierakstam, bet pa daļām. Katra daļa atbilst atsevišķam biznesa notikumam. Līdz ar to izmaiņu nolasīšanai ir pieejami vairāki pielāgoti servisi:
/fpr_person_all_changesvisas izmaiņas/fpr_person_status_fpr_changesizmaiņas statusa datos/fpr_person_birth_changes izmaiņasdzimšanas datos/fpr_person_citizenship_changesizmaiņas pilsonības datos/fpr_person_code_changes izmaiņaspersonas koda datos/fpr_person_death_changes izmaiņasmiršanas datos/fpr_person_document_changes- izmaiņas personas apliecinošo dokumentu datos/fpr_person_name_changes- izmaiņas personas vārda datos/fpr_person_politically_repressed_status_changes- izmaiņas personas politiski represētās personas statusa datos/fpr_person_residence_changes- izmaiņas dzīvesvietas datos/fpr_person_resistance_member_status_changes- izmaiņas personas nacionālās pretošanās kustības dalībnieka statusa datos
Arī servisā /fpr_person_all_changes, kas satur visa veida izmaiņas, izmaiņu dati ir sadalīti pa biznesa notikumiem jeb datu blokiem. Katram notikumam ir sava atslēga formā "{personas_kods}/{notikuma_veids}".
Izsaukuma piemērs:
curl --location 'https://test.dagr.gov.lv/fpr_person_all_changes?limit=1000×tamp=2024-10-07T08%3A17%3A33.985Z' \
--header 'X-DAGR-Permission: 23091' \
--header 'Authorization: ••••••'
Atbildes piemērs:
[
{
"key": "14097314007/ActualPersonCode",
"offset": 47008638,
"timestamp": "2024-10-07T10:17:31.631Z",
"value": {
"PersonCode": "14097314007",
"ActualPersonCode": "32190664656"
}
},
{
"key": "14097314007/PersonsCode",
"offset": 47008639,
"timestamp": "2024-10-07T10:17:31.655Z",
"value": {
"PersonCode": "14097314007",
"PersonsCode": null
}
},
{
"key": "14097314007/PersonsName",
"offset": 47008640,
"timestamp": "2024-10-07T10:17:31.664Z",
"value": {
"PersonCode": "14097314007",
"PersonsName": null
}
},
{
"key": "14097314007/PersonsBirth",
"offset": 47008641,
"timestamp": "2024-10-07T10:17:31.670Z",
"value": {
"PersonCode": "14097314007",
"PersonsBirth": null
}
},
{
"key": "14097314007/PersonsCitizenship",
"offset": 47008642,
"timestamp": "2024-10-07T10:17:31.677Z",
"value": {
"PersonCode": "14097314007",
"PersonsCitizenship": null
}
},
{
"key": "13087215007/PersonsDocument",
"offset": 47008643,
"timestamp": "2024-10-07T10:17:31.689Z",
"value": {
"PersonCode": "13087215007",
"PersonsDocument": null
}
},
{
"key": "14097314007/PersonsPoliticallyRepressedStatus",
"offset": 47008644,
"timestamp": "2024-10-07T10:17:31.690Z",
"value": {
"PersonCode": "14097314007",
"PersonsPoliticallyRepressedStatus": null
}
},
{
"key": "140973140077/PersonsResidence",
"offset": 47008645,
"timestamp": "2024-10-07T10:17:31.694Z",
"value": {
"PersonCode": "14097314007",
"PersonsResidence": null
}
},
{
"key": "14097314007/PersonsResistanceMemberStatus",
"offset": 47008646,
"timestamp": "2024-10-07T10:17:31.696Z",
"value": {
"PersonCode": "14097314007",
"PersonsResistanceMemberStatus": null
}
},
{
"key": "14097314007/PersonsStatusFPR",
"offset": 47008647,
"timestamp": "2024-10-07T10:17:31.702Z",
"value": {
"PersonCode": "14097314007",
"PersonsStatusFPR": null
}
},
{
"key": "14097314007/PersonsDeath",
"offset": 47008648,
"timestamp": "2024-10-07T10:17:31.703Z",
"value": {
"PersonCode": "14097314007",
"PersonsDeath": null
}
},
{
"key": "32180763556/PersonsCode",
"offset": 47008649,
"timestamp": "2024-10-07T10:17:31.705Z",
"value": {
"PersonCode": "32180763556",
"PersonsCode": [
{
"ValidFrom": "2024-10-07T00:00:00+03:00",
"ValidUntil": null,
"PersonCode": "32180763556"
},
{
"ValidFrom": "1989-10-01T00:00:00+03:00",
"ValidUntil": "2024-10-07T00:00:00+03:00",
"PersonCode": "14097314007"
}
]
}
},
{
"key": "32180763556/ActualPersonCode",
"offset": 47008650,
"timestamp": "2024-10-07T10:17:31.705Z",
"value": {
"PersonCode": "32180763556",
"ActualPersonCode": "32180763556"
}
},
{
"key": "32180763556/PersonsName",
"offset": 47008651,
"timestamp": "2024-10-07T10:17:33.195Z",
"value": {
"PersonCode": "32180763556",
"PersonsName": {
"ReasonCode": "PUZL",
"ReasonName": "LATVIJAS VALSTSPIEDERĪGĀ PIRMUZSKAITE",
"ValidFrom": "1988-10-01T00:00:00+03:00",
"FirstName": "JURIS",
"LastName": "KAULIŅŠ",
"OtherNames": null
}
}
},
{
"key": "32180763556/PersonsBirth",
"offset": 47008652,
"timestamp": "2024-10-07T10:17:34.894Z",
"value": {
"PersonCode": "32180763556",
"PersonsBirth": {
"ReasonCode": "PUZL",
"ReasonName": "LATVIJAS VALSTSPIEDERĪGĀ PIRMUZSKAITE",
"ValidFrom": "1989-10-01T00:00:00+03:00",
"BirthDate": "1973-08-13T00:00:00+03:00",
"BirthTime": null,
"IsBornDead": false,
"BirthPlaceCountryCode": "LVA",
"BirthPlaceCountryName": "LATVIJA",
"BirthPlaceFormatted": "RĪGA"
}
}
},
{
"key": "32180763556/PersonsDocument",
"offset": 47008653,
"timestamp": "2024-10-07T10:17:41.019Z",
"value": {
"PersonCode": "32180763556",
"PersonsDocument": [
{
"ReasonCode": "PUZL",
"ReasonName": "LATVIJAS VALSTSPIEDERĪGĀ PIRMUZSKAITE",
"ValidFrom": "1989-10-01T00:00:00+03:00",
"DocumentKindCode": "LNPS",
"DocumentKindName": "NEPILSOŅA PASE",
"DocumentIssuingDate": "1989-08-14T00:00:00+03:00",
"DocumentNumber": "LN000007",
"DocumentIssuingCountryCode": "XXX",
"DocumentIssuingCountryName": "PSRS",
"DocumentIssuingOrganizationName": null,
"DocumentIssuingPlace": "2. PASU DAĻA",
"DocumentValidityDate": null
}
]
}
},
{
"key": "32180763556/PersonsCitizenship",
"offset": 47008654,
"timestamp": "2024-10-07T10:17:42.713Z",
"value": {
"PersonCode": "32180763556",
"PersonsCitizenship": [
{
"ValidFrom": "1989-10-01T00:00:00+03:00",
"CountryCode": "LVA",
"CountryName": "LATVIJAS",
"CitizenshipTypeCode": "N",
"CitizenshipTypeName": "NEPILSONIS"
}
]
}
},
{
"key": "32180763556/PersonsStatusFPR",
"offset": 47008655,
"timestamp": "2024-10-07T10:17:44.508Z",
"value": {
"PersonCode": "32180763556",
"PersonsStatusFPR": {
"PersonCode": "32180763556",
"StatusValueCode": "2",
"StatusValueTitle": "ir statuss PASĪVS",
"StatusValidFrom": "2024-10-05T00:00:00+03:00"
}
}
}
]
Šajā piemērā redzamas izmaiņas, kur personai tiek mainīts personas kods. Piemērs balstīts uz faktiskiem datiem, personu identificējošās daļas aizstājot ar iedomātām vērtībām.
¶ SOPA izmaiņu datu īpatnības
Caur DAGR tiek izplatīti pašvaldību SOPA sistēmas trūcīgo un maznodrošināto dati. Katra pašvaldība šajā gadījumā ir atsevišķs datu devējs, kurš uz savu datu izmantošanu VIRSIS sistēmā piešķir atsevišķu atļauju.
Neskatoties uz to, ka datu devēji ir vairāki un atļaujas ir vairākas, servisi arī izmaiņu datu izgūšanai ir tikai divi. Tie ir formā:
GET /sopa_needy_changes/{district_atvk}serviss trūcīgo datu izmaiņu izguvei;GET /sopa_underprivileged_changes/{district_atvk}serviss maznodrošināto datu izmaiņu izguvei.
Lai izgūtu datus no dažādām pašvaldībām, servisa izsaukumā ir jāmaina ATVK kods (district_atvk) un atbilstošais atļaujas numurs galvenē "X-DAGR-Permission".
¶ Izmaiņu monitorings (patreiz nav pieejams)
Ja izmaiņu servisi ļauj sekot visu ierakstu izmaiņām datu kopā, tad izmaiņu monitorings ļauj sekot specifisku datu ņēmēja noteiktu ierakstu izmaiņām datu kopā.
Lai uzsāktu datu izmaiņu monitoringu, ir jādefinē izmaiņu monitoringa kopa jeb jānosaka, kura datu kopa un kādas VIRSIS atļaujas ietvaros tiks monitorēta. Kad izmaiņu monitoringa kopa ir definēta, tai jāpievieno saraksts ar identifikatoriem - ierakstiem, kuri tiks monitorēti. Identifikatoru saraksta izmēram nav ierobežojumu.
Tālāk datu patērētājam ir iespēja atlasīt izmaiņu datus, kuros parādīsies informācija par tiem datu kopas ierakstiem, kam dati mainījušies kopš brīža, kad ieraksta identifikators tika pievienots monitoringa kopai. Gadījumā, ja ieraksta identifikatoru pēc tam no izmaiņu monitoringa kopas noņem, tad dati par ieraksta izmaiņām pieejami tikai līdz brīdim, kad šis identifikators tika no datu izmaiņu kopas noņemts.
¶ Izmaiņu monitoringa kopas definēšana
Izmaiņu monitoringa kopu iespējams definēt DAGR pašapkalpošanās portālā:
Vispirms automātiskās uzmeklēšanas logā ir jāizvēlas datu patērētājs, kura vārdā lietotājs darbojas, no datu patērētājiem, kuru pieteikumos lietotājs norādīts kā kontaktpersona.
Tālāk parādās saraksts ar visām definētajām izmaiņu monitoringa kopām, kur par katru izmaiņu monitoringa kopu parādās izmaiņu monitoringa kopas nosaukums, datu kopas nosaukums un VIRSIS atļaujas numurs:
No saraksta iespējams atvērt apskatei eksistējošu izmaiņu monitoringa kopu vai definēt jaunu izmaiņu monitoringa kopu. Definējot jaunu izmaiņu monitoringa kopu ir jānorāda izmaiņu monitoringa kopas nosaukums, tad jāizvēlas monitorējamā datu kopa no datu kopu saraksts un visbeidzot jāizvēlas VIRSIS atļaujas no datu patērējām esošajām atļaujām uz izvēlēto datu kopu:
¶ Monitorējamo ierakstu pārvaldība
Kad izmaiņu monitoringa kopa ir definēta, tad tai var pievienot, pārbaudīt, dzēst monitorējamo ierakstu identifikatorus. Identifikatoriem ir jābūt tieši tādiem, kādi tie tiek izmantoti monitorējamā datu kopā.
Darbības ar monitorējamo ierakstu identifikatoriem var izdarīt gan DAGR pašapkalpošanās portālā, gan izmantojot DAGR REST API. DAGR pašapkalpošanās portālā tas ir izdarāms izmaiņu monitoringa kopas kartiņā. Ņemot vērā, ka monitorējamo identifikatoru var būt ļoti daudz, kartiņā tiek attēloti tikai pēdējie 20. Kartiņā var ievadīt monitorējamā ieraksta identifikatoru un izmantojot spiedpogas vai nu to pievienot, dzēst vai pārbaudīt tā esamību izmaiņu monitoringa kopā:
Pēc noklusējuma monitorēt var tikai tādus ierakstus, kas ir pamata datu kopā. Piemēram, fizisko personu reģistram varētu monitorēt tikai tādas personas, kas faktiski ir šajā reģistrā. Taču datu kopām konfigurācijā var norādīt, ka monitorējami ir arī ieraksti, kas vēl nav pamata datu kopā.
Izmaiņu monitoringa automatizācijas vajadzībām visas ar izmaiņu monitoringa kopām veicamās darbības ir pieejamas arī DAGR REST API servisu formā. Servisu pilns apraksts pieejams: https://dev.dagr.gov.lv/api-docs/portal
Servisus var izsaukt izmantojot datu patērētāja drošības talonu.
Izmaiņu monitoringa vajadzībām pieejami šādi DAGR REST API servisi:
GET /monitoring_setIzgūst sarakstu ar datu patērētāja izmaiņu monitoringa kopāmPUT /monitor/{monitoring_set_name}/{registration_number}/{dataset}/{key}Pievieno jaunu identifikatoru izmaiņu monitoringa kopai. Viens un tas pats identifikators var tikt pievienots vairākas reizes. DAGR darbību tas negatīvi neietekmē, bet pašam datu patērētājam tad zūd iespēja noteikt pirmreizējo identifikatora pievienošanas datumu un laiku.DELETE /monitor/{monitoring_set_name}/{registration_number}/{dataset}/{key}Dzēs izmaiņu monitoringa kopai pievienotu identifikatoruGET /monitoring_is_on/{monitoring_set_name}/{registration_number}/{dataset}/{key}Pārbauda, vai identifikators tiek monitorētsGET /monitored_keys_changes/{monitoring_set_name}/{registration_number}/{dataset}Ļauj izgūt sarakstu ar visiem monitorējamajiem identifikatoriem. Piebilde, identifikatoru saraksts tiek glabāts rindas formā un vienādu identifikatoru gadījumā aktuāla ir saraksta pēdējā vērtība. Neaktuālās identifikatoru vērtības pēc laika no rindas tiek dzēstas.
Augstākminēto servisu kontekstā {registration_number} ir datu patērētāja reģistrācijas numurs, {dataset} ir datu kopas nosaukums un {monitoring_set_name} ir izmaiņu monitoringa kopas nosaukums.
¶ Izmaiņu monitoringa kopas nolasīšana
Izmaiņu monitoringa kopas dati ir nolasāmi tāpat kā izmaiņu dati (Datu izmaiņu izgūšana) ar divām atšķirībām:
- Izsaukumam jāpievieno parametrs “monitoring_set”, kurā tiek norādīts monitoringa kopas nosaukums;
- Izsaukuma galvenē “'X-DAGR-Permission” jānorāda tā pati atļauja, kas izmantota monitoringa kopas definēšanai.
Vispārīgā formā izmaiņu monitoringa dati nolasāmi, izsaucot šādu servisu:
https://{dagr_vides_adrese}/{datu_kopas_nosaukums}_changes/?monitoring_set={izmaiņu_monitoringa_kopas_nosaukums}
Piebilde: PMLP datu kopas fpr_person gadījumā ir atkāpe no formas {datu_kopas_nosaukums}_changes. Šajā gadījumā "fpr_person_changes" vietā jānorāda "fpr_person_all_changes".
Izsaukuma piemērs:
curl --location 'https://dev.dagr.gov.lv/vbtai_orphan_certificate_changes/?offset=0&limit=100&monitoring_set=VBTAI_demo_1' \
--header 'X-DAGR-Permission: 40003562863/vbtai' \
--header 'Authorization: ••••••'
Šim izsaukumam 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.
Piebilde par sekošanu līdzi izmaiņu datiem: DAGR neatzīmē, kuri izmaiņu monitoringa dati jau ir nolasīti. Sekot līdzi izmaiņu nolasīšanas stāvoklim ir datu patērētāja uzdevums. Tas ir viegli izdarāms, izmantojot parametru offset vai timestamp. Ja datu patērētājam savā informācijas sistēmā ir process, kas ar noteiktu regularitāti pieprasa izmaiņu monitoringa datus, tad pēc datu nolasīšanas ir jāsaglabā pēdējā nolasītā ieraksta timestamp vai offset vērtība. Šo saglabāto vērtību nākošajā procesa izpildes ciklā jāpadod izmaiņu monitoringa datu izgūšanas servisam kā ieejas parametru un tas garantēs, ka nolasītas tiek tikai jaunpienākušās izmaiņas.
Piebilde par datu dzēšanu: DAGR izmaiņu monitoringa kopā katram ierakstam ilglaicīgi uzglabā tikai pēdējās izmaiņas.
¶ Palīgiespējas
¶ Pēdējo izmaiņu datums
Ja datu ņēmējam ir atļauja izmantot izmaiņu servisus, tad pēdējo datu aktualizācijas datumu un laiku var noteikt, izsaucot izmaiņu servisu bez parametriem – tas atgriezīs pēdējo izmainīto ierakstu, izmaiņu kārtas numuru un izmaiņu datumu un laiku.
Savukārt ja datu ņēmējam ir atļauja izgūt datus tikai pēc ieraksta identifikatora, tad pēdējo izmaiņu datumu un laiku var uzzināt, izmantojot palīg-servisu: GET /updates_last_timestamp/{datu_kopas_nosaukums}
Tāpat kā datu izgūšanas servisiem, arī šim servisam galvenē ar nosaukumu "Authorization" ir jānorāda drošības talons talons un galvenē ar nosaukumu “X-DAGR-Permission” ir jānorāda atbilstošās datu atļaujas numurs.
Servisa izsaukuma piemērs:
curl --location 'https://test.dagr.gov.lv/updates_last_timestamp/fpr_person' \
--header 'X-DAGR-Permission: 1339' \
--header 'Authorization: ••••••'
Atbildes piemērs:
[
{
"key": "328681-81130",
"offset": 3551,
"timestamp": "2024-04-23T07:02:01.093Z"
}
]