Äriregistri API: kuidas ettevõtte andmeid pärida

Kolm teed äriregistri andmeteni

Kui otsida „äriregistri API“, jõuab RIKi lehele, kus on korraga kolm erinevat teenust. Nende segi ajamine annab lahenduse, mis töötab demos ja laguneb toodangus, sest iga raja piirangud on erinevad.

Failid on hulgilaadimiseks, XML-päringuteenus reaalajas üksikküsimusteks ja REST API sama andme tänapäevase liidese kaudu. Kõik kolm loevad sama registrit.

Neljas rada tasub eraldi meelde jätta, sest see ei nõua lepingut: e-arvete vastuvõtjate register vastab, kas ettevõte saab e-arveid vastu võtta ja millise operaatori kaudu, ning automaatse nimepakkumise teenus (autocomplete) pakub ärinimesid trükkimise ajal. Mõlemad on avalikud. Kui ehitad ostuarve voogu, asenda esimene käsitsi kontroll nende kahega ja säästad hiljem terve vaidluse.

Leping ja testkeskkond enne esimest rida koodi

XML-teenus ja REST API eeldavad lepingut RIKiga. Taotlus esitatakse e-äriregistri portaalis, RIK vaatab selle läbi viie tööpäeva jooksul ja saadab seejärel vajaliku info administraatorkasutajale. Kui leping sõlmitakse ainult e-äriregistri API teenuste jaoks, on teenuse kasutamine tasuta. Igakuine abonenditasu ei rakendu, kui leping ei ava e-kinnistusraamatu teenuseid.

Teenuse kirjeldus on WSDL-failis. Toodangukeskkond on https://ariregxmlv6.rik.ee/?wsdl ja testkeskkond https://demo-ariregxmlv6.rik.ee/?wsdl; päringute aadress on sama host ilma ?wsdl-ita. Testkeskkond on ainus koht, kus tasub katseid teha, sest toodangus loetakse iga päring päevase kvoodi sisse.

Autentimine ei käi HTTP-päisega. Kasutajanimi ja parool pannakse päringu kehasse, iga päring kannab endaga kaasas oma volitust. See on vana X-tee stiilis muster ja see tähendab praktikas kahte asja: parool liigub igas päringus (seega ainult HTTPSi kaudu) ja päringu logimine ilma keha sisuta on kohustuslik, mitte lihtsalt kena tava.

Mitmel lepingulisel XML-päringul saab väljundit valida parameetriga ariregister_valjundi_formaat: väärtus json annab JSONi, vaikimisi tuleb XML. Kontrolli tuge konkreetse teenuse kirjeldusest. Rekvisiitide failiteenus kasutab eraldi parameetrit faili_formaat väärtustega csv, json või xml, ja e-arvete vastuvõtjate päring ei nõua kasutajanime ega parooli. Kui ehitad sinna peale tüübikindla kliendi, tee valik üks kord ja ära lase sellel hiljem kõikuda.

Esimene päring: rekvisiidid ühe registrikoodiga

Kõige väiksem kasulik päring on arireg.ettevotjaRekvisiidid_v1. See annab nime, registrikoodi, käibemaksukohustuslase numbri, staatuse, aadressi ja lingi ettevõtte lehele. Arve väljastamiseks on sellest enamasti küll.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
  xmlns:prod="http://arireg.x-road.eu/producer/">
  <soapenv:Body>
    <prod:ettevotjaRekvisiidid_v1>
      <prod:keha>
        <prod:ariregister_kasutajanimi>KASUTAJANIMI</prod:ariregister_kasutajanimi>
        <prod:ariregister_parool>PAROOL</prod:ariregister_parool>
        <prod:ariregistri_kood>70000310</prod:ariregistri_kood>
      </prod:keha>
    </prod:ettevotjaRekvisiidid_v1>
  </soapenv:Body>
</soapenv:Envelope>

Vastus tuleb sama nimeruumi all ja sisaldab plokki leitud_ettevotjate_arv. Kui see on 0, siis ettevõtet sellise koodiga ei ole või see on kustutatud. See väli on olulisem kui tundub, sest tühi ettevotjad plokk ilma loendurita on lihtne ekslikult õnnestunud vastuseks pidada.

Sama teenuse failiversioon arireg.ettevotjaRekvisiididFail_v1 annab rekvisiidid failina ja seda uuendatakse kord ööpäevas. Kui sinu vajadus on „kontrolli, kas see registrikood on olemas“ sadade tuhandete ridade kaupa, on fail kiirem ja viisakam kui päringuteenus.

Detailandmed: mida seal päriselt on

arireg.detailandmed_v2 on suurim päring ja seda tasub kutsuda ainult siis, kui vaja. Plokid lülitatakse sisse ühe ja nulliga: yandmed üldandmed, iandmed isikuandmed, kandmed kommertspandid, dandmed menetluses olevad avaldused, maarused määrused. Kui iandmed on 1, tulevad üldandmed automaatselt kaasa, sest isikuandmeid ei saa eraldi küsida.

Kolm parameetrit mõjutavad tulemuse suurust rohkem kui ükski teine. evarv piirab vastatavate ettevõtete arvu ja selle vaikeväärtus on 10. staatused lubab filtreerida R, L, N ja K vahel ning vaikimisi tulevad kõik. ainult_kehtivad jätab välja lõppenud kanded.

Kui teed nimeotsingut ilma evarv-i tõstmata ja staatused-i piiramata, saad kümmekond vastet ja järeldad, et rohkem ei ole. See on kõige levinum vaikne viga selle teenuse juures.

1. septembrist 2023 muutusid osanike rollid. Osanik, kes ei ole registrikaardil (aktsiad on NASDAQis või osaühing on loobunud vorminõudest), on rollis O, registrikaardile kantud osanik rollis OSAN. Korteriühistu liige ei ole enam H, vaid HUL. Kui sinu päring on kirjutatud enne seda kuupäeva, tasub rollifilter üle vaadata, sest muidu kaob osa andmeid vaikselt.

Tegelike kasusaajate jaoks on eraldi päring arireg.tegelikudKasusaajad_v2. Nende andmetele ligipääs eeldab TEKSA vastutava töötleja positiivset juurdepääsuotsust; tavalisest API-lepingust üksi ei piisa ja õigus antakse kuni kolmeks aastaks. Päringul on kaks valikulist välja, mida tasub täita: paringuPohjendus ja seosEttevottega. Nende täitmine ei ole formaalsus, vaid dokumenteerib, miks sinu süsteem nende inimeste andmeid üldse küsib, aga ligipääsuõigust need väljad ise ei anna.

REST tee: keyLogin ja /company/{registryCode}

REST API ehitab sama andme peale JSON-liidese. Autentimine käib kahes sammus. Esmalt kutsutakse GET /keyLogin/ päisega apiKey, mis on kasutajakontol loodud võti. Vastus on access_token ja token_type, tavaliselt bearer.

curl -s -H "apiKey: $ARIREG_API_KEY" https://ar-rest.rik.ee/keyLogin/

# vastus
{ "access_token": "eyJhbGciOi...", "token_type": "bearer" }

Seejärel pannakse token Authorization päisesse. Ettevõtte koondandmed tulevad aadressilt GET /company/{registryCode} ja plokid valitakse küsimärgiga: includeGeneralData, includeRelatedPersons, includeCommercialPledgeData, includeRulings, includeRegistryCards. Kõik on vaikimisi false. Ilma lisaplokkideta sisaldab vastus muu hulgas nime, registrikoodi ja sisemist companyId-d; vatID võib puududa, kui käibemaksukohustuslase numbrit ei ole.

Kaks päist mõjutavad sisu keelt ja versiooni: acceptLanguage väärtusega est või eng ning apiVersion väärtusega V1. Parameeter onlyValid on vaikimisi true, mis tähendab, et ajaloolised kanded jäävad vastusest välja. Ajaloo uurimiseks tuleb see eraldi välja lülitada.

Üldandmete jaoks on ka kitsam otspunkt GET /company/{registryCode}/generalData, mis vastab ainult üldandmete plokiga. See tagastab ainult vajaliku üldandmete ploki ja hoiab vastuse väiksemana, kui vaja kontrollida näiteks välja einvoiceProvider või seda, kas ettevõttel on kolme viimase aasta kohta esitamata majandusaasta aruandeid (hasUndeclaredReports). Viimane väli on arusaadavalt ainult informatiivne ja jääb vastusest välja, kui infot ei ole.

REST-teenuses on samade plokkide jaoks ka eraldi otspunktid /company/{kood}/relatedPersons, /commercialPledgeData ja /beneficialOwners, lisaks majandusaasta aruannete loend /company/documents/reports/financialYear. Kui vajad ainult üht plokki, on eraldi otspunkt selgem kui viie lippe kombinatsioon.

Tabelist nähtub, miks kolme raja segamine tekitab topeltkoodi: sama fakt on kolmes kohas ja iga rada nimetab väljad erinevalt. Kui kasutad mõlemat liidest, loo üks sisemine mudel ja kaks adapterit, mis selle mudeli täidavad. Vastupidine suund, kus iga rada kirjutab otse andmebaasi, lõpeb kahe erineva tõega sama ettevõtte kohta.

Mida teha, kui vastus on viga

XML-teenus vastab vigasele päringule SOAP-veaga, mitte tühja tulemusega. See on hea uudis, sest valesti vormindatud päringut ei ole võimalik ekslikult „ettevõtet ei leitud“ tõlgendada. Halb uudis on see, et SOAP-viga võib tulla ka siis, kui päring ise on korrektne ja probleem on kontoõigustes. Seetõttu tuleb veakood ja veatekst logida eraldi ning näidata kasutajale üldsõnalist teadet.

REST-teenuses on vead kodeeritud koodi ja identifikaatoriga. Puuduv või vale apiKey annab 404 koodiga API_KEY_NOT_FOUND, puuduv kohustuslik päis annab 422 valideerimisvea koos väljanimega. Korduskatsete loogika peab neid kahte eristama: 422 ei parane kunagi iseenesest ja seda ei tohi uuesti proovida, 404 võib tähendada aegunud võtit ja seda tuleb näidata inimesele, mitte tsüklisse jätta.

Üks harv, aga kallis juhtum on vaikselt aegunud andmed. Kui XML-teenus vastab tühja loendiga, sest ettevõte on kustutatud, ning sinu kood tõlgendab seda kui „andmeid veel ei ole“, jääb kirje sinu andmebaasi igavesti kehtima. Seetõttu salvesta alati vastuse aeg ja kontrolli staatused väärtust K eraldi. Kustutatud ettevõte ei ole sama asi kui puuduv ettevõte.

Piirangud, mis määravad arhitektuuri

Neist neljast piirangust tuleneb üks arhitektuuriline otsus: ära küsi registrist iga kasutaja klikiga. Hoia oma andmebaasis väike peegel — registrikood, nimi, käibemaksunumber, staatus, aadress ja viimase kontrolli aeg — ning värskenda seda öise faililaadimise ja sihitud päringutega. Päring läheb teele ainult siis, kui kasutaja sisestab uue registrikoodi või kui peegel on vanem kui kokkulepitud aeg.

Sama loogika kehtib e-arvete vastuvõtjate registri kohta. Seda ei ole mõtet küsida enne iga arve saatmist, kui tulemus muutub harva. Küsi üks kord ööpäevas nende ettevõtete kohta, kellega sul on aktiivne suhe, ja hoia vastus koos kuupäevaga.

Isikuandmed: mida tohib salvestada ja mida mitte

Avaandmete failides ei ole alates 1. novembrist 2024 isikukoodi infot. See ei tähenda, et failides ei ole isikuandmeid: juhatuse liikmete ja osanike nimed on isikuandmed ja kuuluvad isikuandmete kaitse üldmääruse kohaldamisalasse.

XML-teenusest saab isikukoodi taseme andmeid. Nende töötlemiseks on vaja õiguslikku alust, ja üks võimalik alus on õigustatud huvi. Õigustatud huvi hindamine tuleb dokumenteerida: sõnasta konkreetne huvi, põhjenda töötlemise vajalikkust ning kaalu seda inimese õiguste ja huvide vastu. Üksnes põhjendus, miks ettevõte välja soovib, ei tõenda töötlemise õiguspärasust.

Praktiline reegel, mida tasub koodi kirjutada: kui väli ei ole äriprotsessi jaoks vajalik, ära seda salvesta. Kui vajad ainult kontrolli, et isik on juhatuse liige, salvesta tulemus ja kontrolli aeg, mitte isikukood. Kui isikukood on siiski vajalik (näiteks allkirjastamise või maksekohustuse tuvastamiseks), sea kustutamise tähtaeg ja kirjuta see andmemudelisse, mitte ainult poliitikadokumenti.

Kontrollnimekiri enne integratsiooni

1. Otsusta, kas vajad reaalajas vastust

   Kui andmeid kasutatakse öiseks aruandluseks või kampaanianimekirjade täiendamiseks, piisab avaandmete failidest ja lepingut ei ole vaja. Reaalajas kontrolliks on vaja XML-teenust või REST APIt.

2. Tee leping ja testkeskkonna konto valmis

   Taotlus portaalis, kuni viis tööpäeva ootamist. Ära ehita toodangukonfiguratsiooni enne, kui testkeskkonnas on esimene edukas vastus käes.

3. Kirjuta järjekord ja vahemälu enne päringuloogikat

   Üks samaaegne päring tähendab, et konkurentsi korral peab klient ootama. Järjekord, korduskatsed ja vahemälu kuuluvad esimesse iteratsiooni, mitte järgmisesse.

4. Otsusta, milliseid välju sa salvestad

   Kirjuta see tabelisse enne koodi: väli, miks vaja, kui kaua hoiad, kes näeb. Ilma selle tabelita kasvab andmebaas isikuandmetest, mida keegi ei vaja.

5. Logi päringud ilma sisuta

   Kasutajanimi ja parool on päringu kehas. Logi aeg, päringu nimi, registrikood ja vastuse kood, mitte keha. See hoiab ära olukorra, kus parool satub logifaili.

Millal äriregistri API ei ole õige lahendus

RIK avaldab peale registri põhiandmete ka majandusaasta aruannete struktureeritud põhinäitajaid: näiteks müügitulu, kasumit ja keskmist töötajate arvu täistööajale taandatuna. Avaandmete CSV-andmestikud hõlmavad kolme viimast majandusaastat ja uuenevad algselt kord kuus; EMTAK-põhine müügitulu jaotus on samas andmestikus eraldi failina. Kõigi lisade ja üksikasjade jaoks võib siiski olla vaja aruannete dokumente.

Kui vajad ainult nime järgi otsingut, jäta API kõrvale ja kasuta automaatse nimepakkumise teenust. Sama kehtib siis, kui andmeid kasutatakse korra nädalas: integratsiooni ei ole mõtet ehitada sinna, kus piisab käsitsi kontrollist. Kui vajad dokumente, arvesta 20 päringu minutipiiranguga ja laadi need öösel.

Sama muster kordub kõigis Eesti riigiliidestustes: identiteet ja staatus tulevad registrist, sisu tuleb mujalt. Kui ehitad integratsiooni, mille eesmärk on vähendada käsitsi sisestamist, piirdu registri osas nime, koodi ja käibemaksunumbriga ning kontrolli neid uuesti enne arve väljastamist. See on odav ja hoiab ära kõige kallima vea, milleks on vale registrikoodiga väljastatud arve.

Kogu ahela mõtteka ülesehitus on kirjas API integratsioonide juhendis; kui arved liiguvad edasi raamatupidamisse, jätka Merit Aktiva API või e-arveldaja liidestamise juurest.