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:
- existuje dokumentácia: http://www.registeruz.sk/cruz-public/static/api.html
- 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):
a získame odpoveď:
{"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ď:
{"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:
- účtovné závierky: dokumenty z ID 568588, 993104, 2054656, 284076 a 1713768
- 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ď:
{"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ď je však prázdna. To je čudné, lebo cez "ľudský interfejs" sa k tomu preklikať vieme: http://www.registeruz.sk/cruz-public/domain/financialreport/show/4037605 . Tento "bug" teda doriešime neskôr a návod dokončíme s náhradným ID 8810 (čo je výkaz Hlavného mesta Slovenskej republiky Bratislava za rok 2009).
Požiadavka:
http://www.registeruz.sk/cruz-public/api/uctovny-vykaz?id=8810
Odpoveď:
{"id":8810,"idUctovnejZavierky":5576,"idSablony":2, "obsah":{"titulnaStrana":{"nazovUctovnejJednotky":"Hlavné mesto Slovenskej republiky Bratislava","ico":"00603481", "adresa":{"ulica":"Primaciálne námestie 1","psc":"81499","mesto":"Bratislava - Staré Mesto"}, "typZavierky":"Riadna","obdobieOd":"012009","obdobieDo":"122009"}, "tabulky":[ {"nazov":"Strana aktív","data":[...]}, {"nazov":"Strana pasív","data":[...]}]}, "datumPoslednejUpravy":"2013-08-18","zdrojDat":"DataCentrum"}
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 (vrátil som sa späť k PosAm-u a teda ID 4037605):
http://www.registeruz.sk/cruz-public/domain/financialreport/pdf/4037605
Odpoveď:
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ť.
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 .