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ď:
{"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 .