Skip to end of metadata
Go to start of metadata

Nadviažem na tému o Open Data API v SR (viď článoček OpenData API nemusí byť nič špeciálne). Tentoraz sa pozrieme na API portálu Register účtovných závierok, ktorý obstaralo Ministerstvo financií Slovenskej republiky. Obdobne ak v prípade portálu ZBGIS popíšem názorné ukážky toho, ako API použiť.

Upozornenie: Na rozdiel API portálu ZBGIS, ktoré vzniklo akoby náhodou, neplánovane a nechcene, API Registra účtovných závierok je jasne cielené na Open Data:

  1. existuje dokumentácia: http://www.registeruz.sk/cruz-public/static/api.html http://www.registeruz.sk/cruz-public/version/176425/static/api.html
  2. a špecificky sa v nej spomína: "Verejné RÚZ Open API poskytuje možnosť získať verejne dostupné údaje (t.j. všetko, čo je poskytované portálom registeruz.sk) v podobe vhodnej na spracovanie ..."

Takže k veci. Použitie API si ukážeme na veľmi jednoduchom praktickom príklade: Ako zistím či firma PosAm podala tohto roku účtovnú závierku?

Update k 6.6.2014: Ďalšie doplnkové čítanie: Aspoň jeden štátny IT projekt na európskej špici



Ako zistím či firma PosAm podala tohto roku účtovnú závierku?

Krok 0: zistenie IČO

Ako prvé si samozrejme preštudujeme už spomenutú dokumentáciu. Tam o.i. zistíme, že vyhľadávať možno napr. podľa IČO. Ale zatiaľ máme iba názov. Pomôžeme si Obchodným registrom: http://www.orsr.sk/vypis.asp?ID=8585&SID=2&P=0 -> 31365078 .

Krok 1: zistenie ID firmy podľa IČO

Zašleme na server požiadavku (pre potreby tohto návodu vkladáme URL rovno do browsera resp. naň klikáme a otvárame v novej záložke či novom okne):

http://www.registeruz.sk/cruz-public/api/uctovne-jednotky?zmenene-od=2014-01-01&max-zaznamov=100&ico=31365078

a získame odpoveď:

response
{"id":[156639],"pocetZostavajucichId":0}

Čiže ID je 156639.

Krok 2: zistenie ďalších atribútov k firme podľa ID

Požiadavka:

http://www.registeruz.sk/cruz-public/api/uctovna-jednotka?id=156639

Odpoveď:

response
{"id":156639,"ico":"31365078","dic":"2020315440","nazovUJ":"PosAm, spol. s r.o.",
"mesto":"Bratislava - mestská časť Nové Mesto","ulica":"Odborárska 21","psc":"83102",
"datumPoslednejUpravy":"2014-01-29","datumZalozenia":"1994-01-03","pravnaForma":"112","skNace":"62010",
"velkostOrganizacie":"23","druhVlastnictva":"2",
"kraj":"1","okres":"103","sidlo":"529346","konsolidovana":false,"zdrojDat":"ŠÚSR",
"idUctovnychZavierok":[568588,993104,2054656,284076,1713768],
"idVyrocnychSprav":[1913909]}

Overili sme si, že teda áno, je to firma PosAm a že doteraz zaslala:

  1. účtovné závierky: dokumenty z ID 568588, 993104, 2054656, 284076 a 1713768
  2. výročnú správu: dokument s ID 1913909

Krok 3: zistenie podrobností o účtovnej závierke podľa jej ID

Tu preskočím prehľadávanie viacerých ID a rovno poviem, že tá uzávierka ktorá nás zaujíma má ID 2054656:

Požiadavka:

http://www.registeruz.sk/cruz-public/api/uctovna-zavierka?id=2054656

Odpoveď:

response
{"id":2054656,
"obdobieOd":"2013-01-01","obdobieDo":"2013-12-31","datumPodania":"2014-03-31",
"datumZostavenia":"2014-03-07","datumSchvalenia":"2014-03-26","datumPrilozeniaSpravyAuditora":"2014-03-31","datumPoslednejUpravy":"2014-05-13",
"zdrojDat":"FRSR","nazovUJ":"PosAm,spol.s r.o.","ico":"31365078","dic":"2020315440","idUJ":156639,"typ":"Riadna",
"idUctovnychVykazov":[4037605,4037606,4037603,4037604]}

Takže máme odpoveď: Áno, firma PosAm podala za rok 2013 účtovnú závierku a to dňa 31.3.2014.

Ale sme zvedaví, takže poďme ešte ďalej.

Krok 4: zistenie podrobností o konkrétnom účtovnom výkaze podľa jeho ID

Opäť trochu preskočím a poviem, že nás zaujíma výkaz s ID 4037605.

Požiadavka:

http://www.registeruz.sk/cruz-public/api/uctovny-vykaz?id=4037605

Odpoveď:

response
{"prilohy":[
{"id":3390918,"meno":"POD101_2020315440_IR_2013_201801_631789.pdf","mimeType":"application/pdf",
"velkostPrilohy":264961,"digest":"c8b2017f8e5af3200beae04d8c5db2f2914dccb931f6c319d8306749c2c80d60","pocetStran":0}],
"id":4037605,"idUctovnejZavierky":2054656,"idSablony":21,
"obsah":{"titulnaStrana":{"nazovUctovnejJednotky":"PosAm,spol.s r.o.","ico":"31365078","dic":"2020315440",
"adresa":{"ulica":"Odborárska","cislo":"21","psc":"83102","mesto":"Bratislava 3 - Nové Mesto"},
"skNace":"62010","typZavierky":"Riadna",
"obdobieOd":"012013","obdobieDo":"122013","predchadzajuceObdobieOd":"012012","predchadzajuceObdobieDo":"122012",
"datumSchvalenia":"26032014","datumZostavenia":"07032014"},
"tabulky":[
{"nazov":"Strana aktív","data":[...]},
{"nazov":"Strana pasív","data":[...]}]},
"kodDanovehoUradu":"100","datumPoslednejUpravy":"2014-05-13","zdrojDat":"FRSR"}

To je kopa údajov. Kto si to doštuduje podrobnejšie, zrejme zistí čo potrebuje.

Ale teraz sme predsa len ľudia, nie programy, takže skúsme ešte niečo.

Krok 5: Stiahnutie PDF verzie účtovného výkazu podľa jeho ID

Požiadavka na PDF generované portálom z údajov:

http://www.registeruz.sk/cruz-public/domain/financialreport/pdf/4037605

Odpoveď:

report_31365078_20140605_S.pdf

Požiadavka na PDF zaslané samotnou firmou, t.j. "originál" (3390918 je ID prílohy výkaz s ID 4037605):

http://www.registeruz.sk/cruz-public/domain/financialreport/attachment/3390918

Odpoveď:

POD101_2020315440_IR_2013_201801_631789.pdf

Tu už samozrejme prestáva stačiť, že vieme volať API a k slovu prichádzajú naše znalosti účtovníctva. A tým teda končím tento praktický príklad.

Záver

API je jednoduché a funkčné (s ohľadom na bázu údajov, s ktorou pracujeme) a okrem tohto malého príkladu je schopné efektívne poskytnúť údaje aj zložitejším aplikáciám, keďže (v súlade s Výnosom o štandardoch pre ISVS č. 55/2014 Z. z.) poskytuje aj možnosť filtrovať výsledky podľa dátumu poslednej zmeny (parameter 'zmenene-od') a stránkovať (parametre 'pokracovat-za-id' a 'max-zaznamov').

Neostáva iné než pochváliť. (smile)


p.s.: Prečo práve PosAm? Lebo dodávali realizáciu portálu. Viď napr. http://otvorenezmluvy.sk/documents/703913-datacentrum-bratislava-posam-s-r-o-zmluva-o-dielo-pre-fu?q=Register+%C3%BA%C4%8Dtovn%C3%BDch+z%C3%A1vierok .