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.htmlhttp://www.registeruz.sk/cruz-public/version/176425/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ď:
{"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ť. 
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 .