Firmastat Firma API
The Firma API from Firmastat — 3 operation(s) for firma.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/firmastat-cz:firmastat-cz-firma-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: Firmastat Firma API
version: 1.0.0
description: 'Veřejné API nad daty o českých firmách (ARES, obchodní rejstřík, Sbírka listin). Bez přihlášení platí denní limit 30 dotazů na IP (kalendářní den, Europe/Prague). S účtem platí měsíční kvóta tarifu (Free 500/měs, zdarma) a žádný denní strop; autentizovat se dá API klíčem (Authorization: Bearer fs_…), OAuth 2.1 pro MCP klienty, nebo session cookie z webu. Při vyčerpání přijde 429.'
servers:
- url: https://firmastat.cz
security:
- {}
- apiKey: []
tags:
- name: Firma
paths:
/api/v1/firma/{ico}:
get:
summary: Detail firmy podle IČO
description: 'Vedle údajů z rejstříků nese objekt `dph` (DIČ, stav registrace, plátce / nespolehlivý plátce / identifikovaná osoba, zveřejněné účty) a `sidlo.textPlny` s nezkrácenou adresou včetně městské části. `dph: null` znamená NEOVĚŘENO, nikdy „není plátce".'
parameters:
- name: ico
in: path
required: true
schema:
type: string
responses:
'200':
description: Detail firmy
headers:
X-RateLimit-Limit:
schema:
type: integer
description: 'Strop: 30/den bez přihlášení, jinak měsíční kvóta tarifu.'
X-RateLimit-Remaining:
schema:
type: integer
description: Kolik dotazů ještě zbývá.
X-RateLimit-Reset:
schema:
type: integer
description: 'Sekund do obnovení: do pražské půlnoci u denního limitu, do začátku dalšího měsíce u kvóty účtu.'
content:
application/json:
schema:
type: object
properties:
ok:
type: boolean
data:
type: object
properties:
ico:
type: string
obchodniJmeno:
type: string
dic:
type: string
sidlo:
type: object
properties:
text:
type: string
textPlny:
type: string
description: Nezkrácená adresa z ARES vč. městské části a čísla obvodu.
example: Jankovcova 1522/53, Holešovice, 17000 Praha 7
kodKraje:
type: integer
nazevKraje:
type: string
psc:
type: integer
dph:
type: object
nullable: true
description: Stav DPH složený z ARES (registrace, DIČ) a CRPDPH MFČR (typ, nespolehlivost). `null` = NEOVĚŘENO — nikdy to neznamená „není plátce".
properties:
dic:
type: string
nullable: true
description: DIČ včetně prefixu. Neodvozuje se z IČO (u FO je z rodného čísla). `null` i po zániku registrace — mrtvé DIČ na faktuře je horší než žádné.
example: CZ27082440
registraceAktivni:
type: boolean
description: Běží registrace k DPH právě teď.
stav:
type: string
nullable: true
enum:
- platce
- nespolehlivyPlatce
- identifikovanaOsoba
- neplatce
nespolehlivyOd:
type: string
format: date
nullable: true
overenoK:
type: string
format: date-time
description: Stáří snapshotu, o který se odpověď opírá (starší z obou zdrojů).
cisloFu:
type: string
nullable: true
zverejneneUcty:
type: array
items:
type: string
description: Zveřejněné bankovní účty (§109 — platba jinam nese stejné riziko jako nespolehlivý plátce).
kategorieZamestnancu:
type:
- object
- 'null'
description: Kategorie KATPO (ČSÚ 579) z RES, nikoli přesný počet. null = údaj nemáme; 000 = neuvedeno, 110 = bez zaměstnanců.
required:
- kod
- nazev
properties:
kod:
type: string
example: '230'
nazev:
type:
- string
- 'null'
example: 25 - 49 zaměstnanců
description: Neznámý kód zachováme s názvem null.
insolvence:
type: object
description: Souhrn úspěšné uložené lustrace ISIR. Bez živé lustrace; stáří určuje overenoK. Starší záznamy bez doloženého úspěchu jsou nelustrovano; nelustrovano/chyba nejsou negativní výsledek.
required:
- stav
- pocetRizeni
- overenoK
properties:
stav:
type: string
enum:
- nelustrovano
- bez-zaznamu
- aktivni
- ukoncene
- chyba
pocetRizeni:
type: integer
minimum: 0
description: U nelustrovano/chyba nula neznamená ověřenou absenci řízení.
overenoK:
type:
- string
- 'null'
format: date
description: Datum poslední úspěšné uložené kontroly ISIR; null = není dostupné.
nejnovejsiZahajeni:
type: string
format: date
datumUkonceni:
type: string
format: date
spisovaZnacka:
type: string
faze:
type: string
urlDetail:
type: string
format: uri
finance:
type:
- object
- 'null'
description: Poslední uložená závěrka bez demo dat a bez spouštění scrapingu. Částky v CZK. null = nedostupná data, nikoli nulové hospodaření. Trend porovnává poslední dva dostupné roky, které nemusí navazovat.
required:
- rok
- trzby
- zisk
- predchoziRok
- trendTrzeb
- trendZisku
- zdroj
- zdrojUrl
- spolehlivost
- predchoziSpolehlivost
properties:
rok:
type: integer
example: 2025
trzby:
type:
- number
- 'null'
description: Tržby za rok závěrky v CZK; null = chybí ve výkazu.
zisk:
type:
- number
- 'null'
description: Čistý zisk v CZK, záporný = ztráta; null = chybí ve výkazu.
predchoziRok:
type:
- integer
- 'null'
description: Rok srovnávací závěrky.
trendTrzeb:
type:
- string
- 'null'
enum:
- rust
- pokles
- beze-zmeny
- null
trendZisku:
type:
- string
- 'null'
enum:
- rust
- pokles
- beze-zmeny
- null
description: Růst zahrnuje i snížení ztráty. null = chybí srovnatelná hodnota.
zdroj:
type:
- string
- 'null'
zdrojUrl:
type:
- string
- 'null'
format: uri
spolehlivost:
type:
- string
- 'null'
enum:
- overeno
- odhad
- null
description: Spolehlivost poslední závěrky; null = neuvedena.
predchoziSpolehlivost:
type:
- string
- 'null'
enum:
- overeno
- odhad
- null
description: Spolehlivost srovnávací závěrky; null = neuvedena nebo závěrka chybí.
'401':
description: Neplatný nebo zneplatněný API klíč.
'404':
description: Firma nenalezena
headers:
X-RateLimit-Limit:
schema:
type: integer
description: 'Strop: 30/den bez přihlášení, jinak měsíční kvóta tarifu.'
X-RateLimit-Remaining:
schema:
type: integer
description: Kolik dotazů ještě zbývá.
X-RateLimit-Reset:
schema:
type: integer
description: 'Sekund do obnovení: do pražské půlnoci u denního limitu, do začátku dalšího měsíce u kvóty účtu.'
'429':
description: 'Vyčerpaný limit: bez přihlášení 30 dotazů/den na IP, s účtem měsíční kvóta tarifu (Free 500/měs).'
headers:
X-RateLimit-Limit:
schema:
type: integer
description: 'Strop: 30/den bez přihlášení, jinak měsíční kvóta tarifu.'
X-RateLimit-Remaining:
schema:
type: integer
description: Kolik dotazů ještě zbývá.
X-RateLimit-Reset:
schema:
type: integer
description: 'Sekund do obnovení: do pražské půlnoci u denního limitu, do začátku dalšího měsíce u kvóty účtu.'
Retry-After:
schema:
type: integer
description: Za kolik sekund má smysl to zkusit znovu.
tags:
- Firma
operationId: getApiV1FirmaByIco
x-operation-id-source: derived
/api/v1/firma/{ico}/export:
get:
summary: Export detailu firmy (CSV)
description: Jen pro přihlášené (API klíč, OAuth token nebo session). Bez autentizace vrací 401.
parameters:
- name: ico
in: path
required: true
schema:
type: string
responses:
'200':
description: CSV soubor
headers:
X-RateLimit-Limit:
schema:
type: integer
description: 'Strop: 30/den bez přihlášení, jinak měsíční kvóta tarifu.'
X-RateLimit-Remaining:
schema:
type: integer
description: Kolik dotazů ještě zbývá.
X-RateLimit-Reset:
schema:
type: integer
description: 'Sekund do obnovení: do pražské půlnoci u denního limitu, do začátku dalšího měsíce u kvóty účtu.'
'401':
description: Chybí autentizace, nebo je neplatná.
'429':
description: 'Vyčerpaný limit: bez přihlášení 30 dotazů/den na IP, s účtem měsíční kvóta tarifu (Free 500/měs).'
headers:
X-RateLimit-Limit:
schema:
type: integer
description: 'Strop: 30/den bez přihlášení, jinak měsíční kvóta tarifu.'
X-RateLimit-Remaining:
schema:
type: integer
description: Kolik dotazů ještě zbývá.
X-RateLimit-Reset:
schema:
type: integer
description: 'Sekund do obnovení: do pražské půlnoci u denního limitu, do začátku dalšího měsíce u kvóty účtu.'
Retry-After:
schema:
type: integer
description: Za kolik sekund má smysl to zkusit znovu.
tags:
- Firma
operationId: getApiV1FirmaByIcoExport
x-operation-id-source: derived
/api/v1/firma/{ico}/finance:
get:
summary: Obrat firmy z poslední účetní závěrky
description: 'Obrat = „Tržby z prodeje výrobků a služeb" + „Tržby za prodej zboží" z výkazu zisku a ztráty (plný i zkrácený rozsah). Když výkaz ani jednu složku nemá, použije se „Čistý obrat za účetní období". Vrací nejnovější závěrku, ze které obrat jde určit — `rok` říká, za které období je. Strojově ze Sbírky listin (`spolehlivost`: `overeno` = strukturované XML, `odhad` = text PDF). Ukázková (demo) čísla se nevrací nikdy. Firma, kterou ještě nemáme zpracovanou, se zařadí ke zpracování a vrátí `stav: zpracovava-se` — zeptejte se znovu za pár minut. Tento stav trvá nejvýš 30 minut; když zpracování selže nebo nedoběhne, vrátí se `nedostupne` s důvodem v `duvod`.'
parameters:
- name: ico
in: path
required: true
schema:
type: string
responses:
'200':
description: Obrat firmy (nebo stav, proč ho nemáme)
headers:
X-RateLimit-Limit:
schema:
type: integer
description: 'Strop: 30/den bez přihlášení, jinak měsíční kvóta tarifu.'
X-RateLimit-Remaining:
schema:
type: integer
description: Kolik dotazů ještě zbývá.
X-RateLimit-Reset:
schema:
type: integer
description: 'Sekund do obnovení: do pražské půlnoci u denního limitu, do začátku dalšího měsíce u kvóty účtu.'
content:
application/json:
schema:
type: object
properties:
ok:
type: boolean
data:
type: object
properties:
obrat:
type:
- number
- 'null'
description: CZK, absolutní hodnota (ne v tisících).
rok:
type:
- integer
- 'null'
description: Účetní období.
typVykazu:
type:
- string
- 'null'
enum:
- plny
- zkraceny
- neznamy
- null
spolehlivost:
type:
- string
- 'null'
enum:
- overeno
- odhad
- null
description: '`overeno` jen když všechna pole, ze kterých je obrat, přišla ze strukturovaného XML; jinak `odhad`.'
zdroj:
type:
- string
- 'null'
format: uri
description: Dokument ve Sbírce listin, jinak stránka firmy na firmastat.cz.
stav:
type: string
enum:
- ok
- zpracovava-se
- nedostupne
description: '`ok` = obrat známe; `zpracovava-se` = závěrky se právě stahují, zkuste to znovu (nejvýš 30 min); `nedostupne` = obrat nemáme, proč říká `duvod`.'
duvod:
type:
- string
- 'null'
enum:
- neni-v-or
- bez-vykazu
- chyba-zdroje
- limit
- null
description: 'Jen u `stav: nedostupne`, jinak `null`. `neni-v-or` = firma není v obchodním rejstříku, výkazy ve Sbírce listin nemá (trvalé); `bez-vykazu` = závěrky jsme zpracovali, obrat z nich určit nejde (nezveřejněny, sken, výkaz bez tržeb); `chyba-zdroje` = zpracování selhalo nebo nedoběhlo, další pokus nejdřív za 24 h; `limit` = zpracování teď nejde zařadit, zkuste později.'
'400':
description: Neplatné IČO
headers:
X-RateLimit-Limit:
schema:
type: integer
description: 'Strop: 30/den bez přihlášení, jinak měsíční kvóta tarifu.'
X-RateLimit-Remaining:
schema:
type: integer
description: Kolik dotazů ještě zbývá.
X-RateLimit-Reset:
schema:
type: integer
description: 'Sekund do obnovení: do pražské půlnoci u denního limitu, do začátku dalšího měsíce u kvóty účtu.'
'401':
description: Neplatný nebo zneplatněný API klíč.
'429':
description: 'Vyčerpaný limit: bez přihlášení 30 dotazů/den na IP, s účtem měsíční kvóta tarifu (Free 500/měs).'
headers:
X-RateLimit-Limit:
schema:
type: integer
description: 'Strop: 30/den bez přihlášení, jinak měsíční kvóta tarifu.'
X-RateLimit-Remaining:
schema:
type: integer
description: Kolik dotazů ještě zbývá.
X-RateLimit-Reset:
schema:
type: integer
description: 'Sekund do obnovení: do pražské půlnoci u denního limitu, do začátku dalšího měsíce u kvóty účtu.'
Retry-After:
schema:
type: integer
description: Za kolik sekund má smysl to zkusit znovu.
'502':
description: Databáze dočasně nedostupná
headers:
X-RateLimit-Limit:
schema:
type: integer
description: 'Strop: 30/den bez přihlášení, jinak měsíční kvóta tarifu.'
X-RateLimit-Remaining:
schema:
type: integer
description: Kolik dotazů ještě zbývá.
X-RateLimit-Reset:
schema:
type: integer
description: 'Sekund do obnovení: do pražské půlnoci u denního limitu, do začátku dalšího měsíce u kvóty účtu.'
tags:
- Firma
operationId: getApiV1FirmaByIcoFinance
x-operation-id-source: derived
components:
securitySchemes:
apiKey:
type: http
scheme: bearer
bearerFormat: fs_<token>
description: API klíč vydaný v účtu na /ucet. Platí pro REST i MCP a čerpá jednu společnou měsíční kvótu účtu. Klíč posílej jen ze serveru.