Kuidas alustada arendusega

Expand all Collapse all

Integratsiooni loomiseks vajalikud sammud

Tutvuda liitumisprotsessi juhendite ja muu dokumentatsiooniga
Arendada aruande jaoks sobiliku andmefaili koostamine majandustarkvaras. Selleks võib luua püsivad seosed kontoplaani, tehingute, registrite ja andmesilla klassifikaatorite vahel
Arendada välja isiku tuvastamise ja autoriseerimise protsess
Töötada välja sobilik andmefaili saatmise protsess
Sõlmida RIK-iga kokkulepe ja taotleda avalik client_id, mida kasutatakse isikute tuvastamiseks TARA keskkonda suunamisel
1. Lepingu projekt:

Kõige kiiremini saab ülevaate andmesillaga, kui tutvuda automaatse ja poolautomaatse liitumisprotsessi juhendiga ja kui tutvuda kitsamalt konkreetse aruande andmesektsioonide, näitefailide ja reeglite kirjeldustega. Näiteks annab hea ülevaate lehekülg https://rikpublic.atlassian.net/wiki/spaces/XBRLAvalik/pages/814842103, sellest kuidas sobiva faili kokkupanemisel majandusaasta aruannete portaalis aruanne luuakse.

Demokeskkonna ligipääsuandmed

Isikutuvastamise (Auth Code Flow) protsess

Public Client ID: public-demotarkvara

Tehnilised parameetrid Authorization Code Flow(PKCE) testimiseks:

* Code Verifier:
	dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk
* Code Challenge (S256):
	E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM

Demo keskkonnas redirect URL whitelist ei rakendu. Produktsioonikeskkonnas on vajalik täpsustada URL, kuhu kasutaja peale autentimist on vaja tagasi suunata. Vajadusel on võimalik teie redirect URL toimimine meiega koostöös ka demo keskkonnas läbi testida.

TARA isikukoodid testimiseks

60001019906(Mobiili ID telefoni number: 00000766) - ettevõtte 12345678 volitatud isik

Client Credentials

Client ID: demo_demotarkvara_12345678_1234

Client secret: demotarkvara

Postman collection - lihtsustab API testimist

Andmesilla demokeskkond ja teenuste loend koos tehniliste skeemidega

https://demo.andmesild.rik.ee/api/v1

Tehniline protsessikirjeldus

Siin on kiire tehniline ülevaade, mis päringuid võib olla vaja teha, et andmesilla kaudu edastada näiteks majandusaasta aruannet. Konkreetsed sammud võib läbi teha kasutades näidisfaile, et saada paremini aru kuidas ja mida enda tarkvara poolel oleks vaja arendada.

Aruannete loetelu küsimine

curl -X 'GET' \
  'https://demo.andmesild.rik.ee/api/v1/meta/reports' \
  -H 'accept: application/json'

Vastusest näeme, et meile pakutakse majandusaasta aruande esitamiseks raporti koodi “ANNUAL-ACCOUNTS-MICRO”.

[
  {
    "code": "ANNUAL-ACCOUNTS-MICRO",
    "name": {
      "et": "Mikroettevõtja aastaaruanne",
      "en": "Annual report of micro entity"
    },
    "links": {
      "get": "https://demo.andmesild.rik.ee/api/v1/meta/reports/ANNUAL-ACCOUNTS-MICRO"
    }
  }
]

Aruande detailsema info küsimine

curl -X 'GET' \
  'https://demo.andmesild.rik.ee/api/v1/meta/reports/ANNUAL-ACCOUNTS-MICRO' \
  -H 'accept: application/json'

Päringu vastusest on näha, et antud aruannet tuleb esitada iga aasta kohta, esitamiseks on aega 6 kuud. Samuti tagastatakse abistavaid linke aruande näitefailidele, tehnilistele skeemidele ning andmesektsioonidele.

{
  "code": "ANNUAL-ACCOUNTS-MICRO",
  "name": {
    "et": "Mikroettevõtja aastaaruanne",
    "en": "Annual report of micro entity"
  },
  "reporting_period": "year",
  "due_date": "6 months",
  "datasets": [
    {
      "code": "EE0301010",
      "name": {
        "et": "Perioodi saldod (mikro)",
        "en": "Period balances (micro)"
      },
      "links": {
        "get": "https://demo.andmesild.rik.ee/api/v1/meta/datasets/EE0301010"
      }
    }
  ],
  "links": {
    "help": "https://rikpublic.atlassian.net/wiki/spaces/zeroavalik/pages/815071237/L+hendatud+aruanne",
    "schemas": {
      "json": "https://demo.andmesild.rik.ee/api/v1/meta/schemas/ANNUAL-ACCOUNTS-MICRO/json",
      "xml": "https://demo.andmesild.rik.ee/api/v1/meta/schemas/ANNUAL-ACCOUNTS-MICRO/xml"
    },
    "examples": {
      "json": "https://demo.andmesild.rik.ee/api/v1/meta/examples/ANNUAL-ACCOUNTS-MICRO/json",
      "xml": "https://demo.andmesild.rik.ee/api/v1/meta/examples/ANNUAL-ACCOUNTS-MICRO/xml"
    }
  }
}

Aruande näidisfail

Võib-olla raske ette kujutada, milline üks esitatav aruandefail võiks välja näha. Selleks saab pärida näidisfaili näiteks JSON kujul.

curl -X 'GET' \
  'https://demo.andmesild.rik.ee/api/v1/meta/examples/ANNUAL-ACCOUNTS-MICRO/json?download=false' \
  -H 'accept: application/json'

Vastuses näeb, milliseid andmeid ja millisel kujul andmesild ootab. Kõikide väljade osas leiab täiendavat infot Majandusaasta aruanded alamsektsioonist.

{
  "documentInfo": {
    "uniqueID": "12345678-2025-01-31T09:35:50.30",
    "language": "iso639:et",
    "creationDate": "2025-01-31",
    "creator": "EE39901012239",
    "periodCoveredStart": "2024-01-01",
    "periodCoveredEnd": "2024-12-31",
    "sourceApplication": "majandustarkvara nimi",
    "defaultCurrency": "iso4217:eur"
  },
  "entityInformation": {
    "organizationIdentifier": "12345678",
    "organizationDescription": "ARIREGISTRIKOOD"
  },
  "datasets": [
    {
      "entryNumber": "EE0301010",
      "entryDetail": [
        {
          "lineNumberCounter": 1,
          "accountMainID": "101020",
          "accountMainDescription": "1020 Swedbank",
          "debitCreditCode": "D",
          "amount": 5431.91
        },
        {
          "lineNumberCounter": 111,
          "accountMainID": "101020",
          "accountMainDescription": "1021 LHV",
          "debitCreditCode": "C",
          "amount": 10
        },
        {
          "lineNumberCounter": 11,
          "accountMainID": "212010",
          "accountMainDescription": "2010 Võlad tarnijatele",
          "debitCreditCode": "C",
          "amount": 2381.47
        },
        {
          "lineNumberCounter": 14,
          "accountMainID": "315011",
          "accountMainDescription": "2920 Osakapital",
          "debitCreditCode": "C",
          "amount": 2556.47
        },
        {
          "lineNumberCounter": 17,
          "accountMainID": "418012",
          "accountMainDescription": "3010 Müügitulu Eestis",
          "debitCreditCode": "C",
          "amount": 23793.5,
          "accountSub": {
            "EMTAK2025ap": "07101"
          }
        },
        {
          "lineNumberCounter": 20,
          "accountMainID": "520102",
          "accountMainDescription": "4320 Elektrikulu",
          "debitCreditCode": "D",
          "amount": 561.2
        }
        ...
      ]
    }
  ]
}

Klassifikaatorite pärimine

Kuna andmefail sisaldab hulgaliselt erinevaid klassifikaatoreid, saab teha päringu, et oma tarkvaras sobivad andmed nendega ära siduda.

curl -X 'GET' \
  'https://demo.andmesild.rik.ee/api/v1/meta/classifications' \
  -H 'accept: application/json'

[
  {
    "code": "EMTAK2025ap",
    "name": {
      "en": "The Estonian Classification of Economic Activities",
      "et": "Eesti Majanduse Tegevusalade Klassifikaator"
    },
    "links": {
      "get": "https://demo.andmesild.rik.ee/api/v1/meta/classifications/EMTAK2025ap",
      "source": "https://ariregister.rik.ee/est/emtak_search",
      "help": "https://abiinfo.rik.ee/emtak"
    }
  },
  {
    "code": "MAJANDUSLIKSISU2024ap",
    "name": {
      "en": "Economic content of the transaction",
      "et": "Tehingu majanduslik sisu"
    },
    "links": {
      "get": "https://demo.andmesild.rik.ee/api/v1/meta/classifications/MAJANDUSLIKSISU2024ap",
      "help": "https://rikpublic.atlassian.net/wiki/x/PQAsBg",
      "source": "https://cl2.stat.ee/codelists/codelist/MAJANDUSLIKSISU2024ap"
    }
  },
  {
    "code": "ANDMETEESITLUSVIIS2024ap",
    "name": {
      "en": "Presentation of data",
      "et": "Andmete esitlusviis"
    },
    "links": {
      "get": "https://demo.andmesild.rik.ee/api/v1/meta/classifications/ANDMETEESITLUSVIIS2024ap",
      "help": "https://rikpublic.atlassian.net/wiki/x/KYAwBw",
      "source": "https://cl2.stat.ee/codelists/codelist/ANDMETEESITLUSVIIS2024ap"
    }
  },
  {
    "code": "MUUTUSELIIK2024ap",
    "name": {
      "en": "Type of debit or credit change",
      "et": "Deebet või kreedit muutuse liik"
    },
    "links": {
      "get": "https://demo.andmesild.rik.ee/api/v1/meta/classifications/MUUTUSELIIK2024ap",
      "help": "https://rikpublic.atlassian.net/wiki/x/IADCBg",
      "source": "https://cl2.stat.ee/codelists/codelist/MUUTUSELIIK2024ap"
    }
  },
  {
    "code": "RTK2T2013ap",
    "name": {
      "en": "Country Codes ISO-3166 (two-letter code)",
      "et": "Riikide koodid ISO-3166 (2 täheline kood)"
    },
    "links": {
      "get": "https://demo.andmesild.rik.ee/api/v1/meta/classifications/RTK2T2013ap",
      "source": "https://cl2.stat.ee/codelists/codelist/RTK2T2013ap"
    }
  },
  {
    "code": "SEOTUDOSAPOOL2024ap",
    "name": {
      "en": "Type of related party",
      "et": "Seotud osapoole liik"
    },
    "links": {
      "get": "https://demo.andmesild.rik.ee/api/v1/meta/classifications/SEOTUDOSAPOOL2024ap",
      "help": "https://rikpublic.atlassian.net/wiki/x/QwAtBw",
      "source": "https://cl2.stat.ee/codelists/codelist/SEOTUDOSAPOOL2024ap"
    }
  },
  {
    "code": "VARAGRUPP2024ap",
    "name": {
      "en": "Asset group",
      "et": "Vara grupp"
    },
    "links": {
      "get": "https://demo.andmesild.rik.ee/api/v1/meta/classifications/VARAGRUPP2024ap",
      "help": "https://rikpublic.atlassian.net/wiki/x/J4AsBw",
      "source": "https://cl2.stat.ee/codelists/codelist/VARAGRUPP2024ap"
    }
  }
]

Peakontode pärimine

Näidisfailis on näha, et on kasutatud “accountMainId” väljal põhiklassifikatsiooni koode. Neid on võimalik pärida MAJANDUSLIKSISU2024ap päringuga.

curl -X 'GET' \
  'https://demo.andmesild.rik.ee/api/v1/meta/classifications/MAJANDUSLIKSISU2024ap' \
  -H 'accept: application/json'

{
  "code": "MAJANDUSLIKSISU2024ap",
  "name": {
    "en": "Economic content of the transaction",
    "et": "Tehingu majanduslik sisu"
  },
  "elements": [
    {
      "code": "101010",
      "name": {
        "et": "Raha - Sularaha",
        "en": "Cash - Cash in hand"
      },
      "valid_from_date": "2024-01-01",
      "valid_until_date": null
    },
    {
      "code": "101020",
      "name": {
        "et": "Raha - Arvelduskontod",
        "en": "Cash - Bank accounts"
      },
      "valid_from_date": "2024-01-01",
      "valid_until_date": null
    },
    {
      "code": "101030",
      "name": {
        "et": "Raha - Hoiused",
        "en": "Cash - Deposits"
      },
      "valid_from_date": "2024-01-01",
      "valid_until_date": null
    }
    ...
  ]
}

Andmefaili koostamine skeemi järgi

Kui klassifikatsioonid on üle vaadatud, siis andmefaili koostamiseks saab kontrollida, mis reeglite järgi fail koostada tuleb.

curl -X 'GET' \
  'https://demo.andmesild.rik.ee/api/v1/meta/schemas/ANNUAL-ACCOUNTS-MICRO/json?download=false' \
  -H 'accept: application/json'

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://demo.andmesild.rik.ee/api/v1/meta/schemas/ANNUAL-ACCOUNTS-MICRO/json",
  "title": "Annual Accounts - micro",
  "type": "object",
  "required": [
    "documentInfo",
    "entityInformation",
    "datasets"
  ],
  "properties": {
    "documentInfo": {
      "type": "object",
      "required": [
        "uniqueID",
        "language",
        "creationDate",
        "creator",
        "periodCoveredStart",
        "periodCoveredEnd",
        "sourceApplication",
        "defaultCurrency"
      ],
      "properties": {
        "uniqueID": {
          "type": "string"
        },
        "language": {
          "type": "string",
          "const": "iso639:et"
        },
        "creationDate": {
          "type": "string",
          "format": "date",
          "pattern": "^([1-2]\\d{3})-([0][1-9]|[1][0-2])-([0][1-9]|[12][0-9]|[3][0-1])$"
        },
        "creator": {
          "type": "string"
        },
        "periodCoveredStart": {
          "type": "string",
          "format": "date",
          "pattern": "^([1-2]\\d{3})-([0][1-9]|[1][0-2])-([0][1-9]|[12][0-9]|[3][0-1])$"
        },
        "periodCoveredEnd": {
          "type": "string",
          "format": "date",
          "pattern": "^([1-2]\\d{3})-([0][1-9]|[1][0-2])-([0][1-9]|[12][0-9]|[3][0-1])$"
        },
        "sourceApplication": {
          "type": "string"
        },
        "defaultCurrency": {
          "type": "string",
          "const": "iso4217:eur"
        }
      }
    },
    "entityInformation": {
      "type": "object",
      "required": [
        "organizationIdentifier",
        "organizationDescription"
      ],
      "properties": {
        "organizationIdentifier": {
          "type": "string",
          "pattern": "^\\d{8}$"
        },
        "organizationDescription": {
          "type": "string",
          "const": "ARIREGISTRIKOOD"
        }
      }
    },
    "datasets": {
      "type": "array",
      "minItems": 1,
      "items": {
        "type": "object",
        "required": [
          "entryNumber",
          "entryDetail"
        ],
        "properties": {
          "entryNumber": {
            "type": "string",
            "const": "EE0301010"
          },
          "entryDetail": {
            "type": "array",
            "minItems": 1,
            "items": {
              "type": "object",
              "required": [
                "lineNumberCounter",
                "accountMainID",
                "debitCreditCode",
                "amount"
              ],
              "properties": {
                "lineNumberCounter": {
                  "type": "number"
                },
                "accountMainID": {
                  "type": "string",
                  "pattern": "^\\d{6}$"
                },
                "accountSub": {
                  "type": "object",
                  "properties": {
                    "SEOTUDOSAPOOL2024ap": {
                      "type": "string",
                      "pattern": "^SOP_\\d{2}$"
                    },
                    "EMTAK2025ap": {
                      "type": "string",
                      "pattern": "^\\d{5}$"
                    }
                  },
                  "additionalProperties": true
                },
                "debitCreditCode": {
                  "type": "string",
                  "pattern": "^[D|C]$"
                },
                "amount": {
                  "type": "number"
                }
              }
            }
          }
        }
      }
    }
  }
}

Juhatuse liikmele andmesilla kasutustingimuste kuvamine

Enne isikutuvastamist on vajalik, et tarkvarakasutaja nõustuks andmesilla kasutustingimustega. Selle jaoks on tehtud eraldi teenus, kus saab päringuga vaadata viimast seisu.

curl -X 'GET' \
  'https://demo.andmesild.rik.ee/api/v1/legal/terms-of-service?lang=et' \
  -H 'accept: application/pdf'

Saadame juhatuse liikme isikutuvastust tegema

Alltoodud link avatakse kasutaja poolt veebilehitsejas. Isikutuvastuseks sobib majandusaasta aruannete puhul näiteks juhatuse liige või isik, kellele juhatuse liige on andnud volitused majandusaasta aruannete sisestamiseks. Pärast edukat isikutuvastust suunatakse kasutaja tagasi enda programmi, mis on paigaldatud tema arvutisse aadressil: http://localhost:8082/auth/callback.

https://demo.andmesild.rik.ee/api/v1/auth/code-flow?client_id=e-arveldaja&code_challenge=<PKCE_CHALLENGE>&code_challenge_method=S256&response_type=code&redirect_uri=http://localhost:8082/auth/callback&scope=datahub_connect

Pärime, kas juhatuse liikmel on ka päriselt volitused olemas

Access tokeni küsimine kasutajale

curl -X 'POST' \
  'https://demo.andmesild.rik.ee/api/v1/auth/token' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'client_id=e-arveldaja&grant_type=authorization_code&code=<SAADUD_AUTH_KOOD>&redirect_uri=http://localhost:8082/auth/callback&code_verifier=<PKCE_VERIFIER>'

{
  "access_token": "eyJhbGciOiJSUsUxMiIzInR4cCIgO...",
  "token_type": "Bearer",
  "expires_in": 300,
  "scope": "datahub_connect"
}

Volituste kontroll & M2M ligipääsu võtmete väljastamine

curl -X 'POST' \
  'https://demo.andmesild.rik.ee/api/v1/auth/client-credentials' \
  -H 'accept: application/json' \
  -H 'Represented-Party: 12345678' \
  -H 'Content-Type: application/json' \
  -d '{
  "public_client_id": "e-arveldaja",
  "creator_national_id": "EE39901012239",
  "creator_name": "Test Kasutaja",
  "contact_email": "zero@rik.ee"
}'

Kuna volitused on olemas, siis saame ligipääsu jaoks vajaliku client_id ja client_secreti. Neid võib pärida mitmeid - vastavalt tarkvara ülesehitusele.

{
  "client_id": "test_andmesild_10000011_v2rAQ70jzmvzpnOZSX6m4g3I",
  "client_secret": "s3cr3t",
  "is_activated": false,
  "valid_until": "2027-09-09T18:26:42.979423+03:00",
  "message": "Agreement and API key created successfully"
}

Access tokeni küsimine M2M tarkvara kasutajale

curl -X 'POST' \
  'https://demo.andmesild.rik.ee/api/v1/auth/token' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'client_id=test_andmesild_10000011_v2rAQ70jzmvzpnOZSX6m4g3I&client_secret=s3cr3t&grant_type=client_credentials&code=&redirect_uri=&code_verifier='

{
  "access_token": "azLxbGciOsJSUgUxSiIzInR5cCIgO...",
  "token_type": "Bearer",
  "expires_in": 300,
  "scope": "datahub_connect"
}

Andmefaili edastamine

Edastame testimiseks andmesilla näitefaili, mille muutsime käsitsi vigaseks

curl -X 'POST' \
  'https://demo.andmesild.rik.ee/api/v1/ledger/submissions' \
  -H 'accept: application/json' \
  -H 'Represented-Party: 12345678' \
  -H 'Content-Type: multipart/form-data' \
  -F 'ledger_file=@ANNUAL-ACCOUNTS-MICRO_EXAMPLE.json;type=application/json' \
  -F 'report_code=ANNUAL-ACCOUNTS-MICRO' \
  -F 'overwrite_report=true'

Faili edastamine oli edukas ning saame tagasi tunnuse, millega töötlemise staatust pärida

{
  "submission_uuid": "464987fdfb2d7fae46b9d54a0dd06c9c02dd1db1933318ce8769d37d5689ffb1b5f6f4c3418ab5aa8d32daccba1caeb5f9426b06a220fc160eb61ec26b763e86"
}

Andmefaili staatuse pärimine

curl -X 'GET' \
  'https://demo.andmesild.rik.ee/api/v1/ledger/submissions/464987fdfb2d7fae46b9d54a0dd06c9c02dd1db1933318ce8769d37d5689ffb1b5f6f4c3418ab5aa8d32daccba1caeb5f9426b06a220fc160eb61ec26b763e86' \
  -H 'accept: application/json' \
  -H 'Represented-Party: 12345678'

Kuna fail osutus vigaseks ning saame tagasi erinevaid vigu

{
  "status": "ERROR",
  "unique_id": "12345678-2024-09-24T13:29:42:578",
  "errors": [
    {
      "descriptions": {
        "en": "The sub_account code used (01481) was not valid during the reporting period",
        "et": "Kasutatud sub_account kood (01481) ei olnud aruandeperioodil kehtiv"
      },
      "entry_number": "EE0301010",
      "level": "WARNING",
      "code": "NOT_VALID_CODE",
      "line_number_counter": 15
    },
    {
      "descriptions": {
        "en": "The total debit and credit of the dataset are not equal",
        "et": "Andmestiku deebet kokku ja kreedit kokku ei ole võrdsed"
      },
      "entry_number": "EE0301010",
      "level": "ERROR",
      "code": "DEBIT_NOT_EQUALS_CREDIT"
    },
    {
      "descriptions": {
        "en": "No unsubmitted obligations found for entity",
        "et": "Ühingul puuduvad täitmata aruande kohustused"
      },
      "entry_number": "N/A",
      "level": "WARNING",
      "code": "INCORRECT_PERIOD"
    }
  ]
}

Genereeritud raporti andmestiku pärimine

Täiendavalt on võimalik pärida edastatud andmefailist genereeritud tehniline raportifail, mis edastatakse majandusaasta aruannete portaali. Vahetulemusi on teinekord hea kontrollida, et saada aimu, kuidas lõplik aruanne moodustatakse.

curl -X 'GET' \
  'https://demo.andmesild.rik.ee/api/v1/ledger/submissions/464987fdfb2d7fae46b9d54a0dd06c9c02dd1db1933318ce8769d37d5689ffb1b5f6f4c3418ab5aa8d32daccba1caeb5f9426b06a220fc160eb61ec26b763e86/reports/json' \
  -H 'accept: application/json' \
  -H 'Represented-Party: 12345678'

{
  "registry_code": "12345678",
  "creator_id": "EE39901012239",
  "report_code": "ANNUAL-ACCOUNTS-MICRO",
  "overwrite_report": true,
  "period_start": "2023-07-01",
  "period_end": "2024-06-30",
  "elements": [
    {
      "name": "BS-AssetsShort-Cash",
      "amount": "20000"
    },
    {
      "name": "BS-AssetsShort-Total",
      "amount": "36391"
    },
    {
      "name": "BS-Assets-Total",
      "amount": "55297"
    },
    {
      "name": "IS-Revenue",
      "amount": "145",
      "custom_attributes": {
        "geographical_locations": [],
        "operating_activities": []
      }
    },
    {
      "name": "SRE-NetSurplusDeficitForPeriod",
      "amount": "-48023"
    }
  ]
}