Základní pojmy – Dokumentace

Jednoznačně najít firmu

Parametr q endpointu fetch-organization přijímá tři druhy vstupu. Příklady na této stránce jsou požadavky na Hetzner Online GmbH, Ansbach HRB 6089:

Jednoznačně najít firmu
Vstup	Příklad	Kdy se hodí
Název firmy	`Hetzner Online GmbH`	Na začátek. Napiš název tak úplně, jak je uveden v rejstříku.
Rejstříkový soud a rejstříkové číslo	`Ansbach HRB 6089`	Jednoznačné pro každou zapsanou firmu. Soud, typ rejstříku a číslo patří k sobě.
entity_id	`94eb910fef13f94585c48c263fa446d4`	Pro navazující požadavky. Dostaneš ho v každé odpovědi.

Samotné rejstříkové číslo nestačí, protože každý rejstříkový soud přiděluje vlastní čísla. Pořadí je naopak libovolné: v příkladu najde HRB 6089 Ansbach stejnou firmu.

curl -G "https://handelsregister.ai/api/v1/fetch-organization" \
  -H "x-api-key: TVUJ_API_KLIC" \
  --data-urlencode 'q=Ansbach HRB 6089'

import requests

response = requests.get(
    "https://handelsregister.ai/api/v1/fetch-organization",
    headers={"x-api-key": "TVUJ_API_KLIC"},
    params={
        "q": "Ansbach HRB 6089",
    },
)
data = response.json()

const url = new URL("https://handelsregister.ai/api/v1/fetch-organization");
url.searchParams.append("q", "Ansbach HRB 6089");

const response = await fetch(url, {
  headers: { "x-api-key": "TVUJ_API_KLIC" },
});
const data = await response.json();

Pokud má stejný název více firem, API může vrátit jednu z nich, ne nutně tu, kterou chceš, nebo odpovědět 404. Když záleží na správné firmě, ptej se podle rejstříkového soudu a rejstříkového čísla nebo podle entity_id.

Pokud API žádnou firmu nenajde, odpoví 404 a nic neúčtuje. Pro nepřesný vstup slouží AI režim (ai_search=on-default): najde firmu i z částí názvu a dohledá ji na webu. Stojí 20 kreditů navíc, i když žádnou firmu nenajde. Chceš-li několik kandidátů najednou, použij Vyhledávání a export.

Funkce

Každý profil firmy obsahuje základní údaje, mimo jiné název, právní formu, stav, zápis v rejstříku, adresu, předmět podnikání, odvětví, kapitál a způsob zastupování. Vše ostatní si vyžádáš jako funkci, například related_persons pro jednatele nebo financial_kpi pro finanční KPI.

Více funkcí předáš opakovaným feature nebo jako seznam: features=related_persons,financial_kpi. Každá funkce se v odpovědi objeví pod vlastním klíčem. Jen publications se tam jmenuje history.

curl -G "https://handelsregister.ai/api/v1/fetch-organization" \
  -H "x-api-key: TVUJ_API_KLIC" \
  --data-urlencode 'q=Hetzner Online GmbH' \
  --data-urlencode 'feature=related_persons' \
  --data-urlencode 'feature=financial_kpi'

import requests

response = requests.get(
    "https://handelsregister.ai/api/v1/fetch-organization",
    headers={"x-api-key": "TVUJ_API_KLIC"},
    params={
        "q": "Hetzner Online GmbH",
        "feature": ["related_persons", "financial_kpi"],
    },
)
data = response.json()

const url = new URL("https://handelsregister.ai/api/v1/fetch-organization");
url.searchParams.append("q", "Hetzner Online GmbH");
url.searchParams.append("feature", "related_persons");
url.searchParams.append("feature", "financial_kpi");

const response = await fetch(url, {
  headers: { "x-api-key": "TVUJ_API_KLIC" },
});
const data = await response.json();

Neznámé názvy API ignoruje bez chybové hlášky, proto kontroluj pravopis. Funkce, které tvůj tarif nezahrnuje, se vynechají a neúčtují.

Všechny funkce s cenami najdeš v fetch-organization, každé pole v Katalogu dat.

Kredity

Datové požadavky stojí kredity. Pro profil firmy platí tato pravidla:

Základní cena 5 kreditů platí, když API vrátí firmu.
Funkce stojí kredity jen tehdy, když v odpovědi vrátí data. Prázdná funkce je zdarma, včetně insolvency_publications bez záznamů.
Režim v reálném čase a AI režim nejsou funkce, ale příplatky s vlastními pravidly:
- Režim v reálném čase stojí 10 kreditů navíc, jakmile živé načtení uspěje. To platí i tehdy, když neukáže nic nového.
- AI režim stojí 20 kreditů navíc, i když žádnou firmu nenajde. Příplatek odpadá jen tehdy, když API požadavek ukončí s 408, protože trvá příliš dlouho.
Všechny ostatní chyby nestojí nic.

Pravidlo pro každou jednotlivou funkci je v části Účtování, ceny v fetch-organization.

Příklad: základní údaje s related_persons a financial_kpi stojí 5 + 2 + 1 = 8 kreditů, pokud obě funkce vrátí data.

Před každým požadavkem API zkontroluje, zda tvůj zůstatek pokryje nejvyšší možnou cenu. Pokud ne, odpoví 402 a nic neúčtuje. Co bylo skutečně zaúčtováno, je v meta.request_credit_cost, tvůj zůstatek poté v meta.credits_remaining.

1{2  "meta": {3    "request_credit_cost": 5,4    "credits_remaining": 1455  }6}

200 · meta z našeho ukázkového požadavku jen se základními údaji

Kredity dostáváš jako startovní kredity, každý měsíc s předplatným kreditů nebo jednorázově jako dobití kreditů. Bez předplatného kreditů platí startovní kredity a dobití kreditů 30 dní; s aktivním předplatným nepropadají. Vše ostatní najdeš v části Účtování.

Aktuálnost dat a režim v reálném čase

Ve výchozím stavu pochází profil firmy z naší databáze. Jak aktuální je určitý údaj, závisí na jeho zdroji.

Handelsregister

Základní údaje, osoby a rejstříková oznámení udržujeme v naší databázi aktuální podle rejstříku. Je to rychlé a pro většinu účelů to stačí.

V režimu v reálném čase (realtime_mode=handelsregister-default) API načte Aktueller Abdruck (AD, aktuální výpis) živě z Handelsregister (obchodní rejstřík) v okamžiku tvého požadavku a vrátí ho jako JSON. Navíc dostaneš aktuálně zapsané osoby v related_persons.current, aniž bys za funkci platil.

Zda živé načtení proběhlo, ukazuje _realtime_mode.status. Kredity 10 za režim v reálném čase účtujeme jen při success.

curl -G "https://handelsregister.ai/api/v1/fetch-organization" \
  -H "x-api-key: TVUJ_API_KLIC" \
  --data-urlencode 'q=Hetzner Online GmbH' \
  --data-urlencode 'realtime_mode=handelsregister-default'

import requests

response = requests.get(
    "https://handelsregister.ai/api/v1/fetch-organization",
    headers={"x-api-key": "TVUJ_API_KLIC"},
    params={
        "q": "Hetzner Online GmbH",
        "realtime_mode": "handelsregister-default",
    },
)
data = response.json()

const url = new URL("https://handelsregister.ai/api/v1/fetch-organization");
url.searchParams.append("q", "Hetzner Online GmbH");
url.searchParams.append("realtime_mode", "handelsregister-default");

const response = await fetch(url, {
  headers: { "x-api-key": "TVUJ_API_KLIC" },
});
const data = await response.json();

1{2  "name": "Hetzner Online GmbH",3  "_realtime_mode": {4    "mode": "handelsregister-default",5    "status": "success"6  },7  "related_persons": {8    "current": [9      {10        "entity_id": "78ad32e16ff779f589a9e88d23356f74",11        "label": "MANAGING_DIRECTOR",12        "role": {13          "en": {14            "long": "Managing Director",15            "short": "MD"16          },17          "de": {18            "long": "Geschäftsführer",19            "short": "GF"20          }21        },22        "name": "Max Mustermann",23        "name_parts": {24          "given": "Max",25          "family": "Mustermann",26          "maiden": null,27          "canonical_name": "Mustermann, Max",28          "aliases": [29            "Mustermann, Max"30          ],31          "previous_names": null32        },33        "start_date": null,34        "end_date": null,35        "birth_date": "1976-01-15",36        "location": {37          "home": {38            "city": "Musterheim"39          }40        },41        "organization_representation_scheme": {42          "current": [43            "Ist nur ein Geschäftsführer bestellt, so vertritt er die Gesellschaft allein. Sind mehrere Geschäftsführer bestellt, so wird die Gesellschaft durch zwei Geschäftsführer oder durch einen Geschäftsführer gemeinsam mit einem Prokuristen vertreten."44          ],45          "history": []46        },47        "role_representation_scheme": {48          "current": [49            "einzelvertretungsberechtigt",50            "mit der Befugnis, im Namen der Gesellschaft mit sich im eigenen Namen oder als Vertreter eines Dritten Rechtsgeschäfte abzuschließen"51          ],52          "history": []53        }54      },55      {56        "entity_id": "73549375ff7d709b9e7e2941ad1ffaa3",57        "label": "MANAGING_DIRECTOR",58        "role": {59          "en": {60            "long": "Managing Director",61            "short": "MD"62          },63          "de": {64            "long": "Geschäftsführer",65            "short": "GF"66          }67        },68        "name": "Paul Musterwald",69        "name_parts": {70          "given": "Paul",71          "family": "Musterwald",72          "maiden": null,73          "canonical_name": "Musterwald, Paul",74          "aliases": [75            "Musterwald, Paul"76          ],77          "previous_names": null78        },79        "start_date": null,80        "end_date": null,81        "birth_date": "1989-07-18",82        "location": {83          "home": {84            "city": "Probebrück"85          }86        },87        "organization_representation_scheme": {88          "current": [89            "Ist nur ein Geschäftsführer bestellt, so vertritt er die Gesellschaft allein. Sind mehrere Geschäftsführer bestellt, so wird die Gesellschaft durch zwei Geschäftsführer oder durch einen Geschäftsführer gemeinsam mit einem Prokuristen vertreten."90          ],91          "history": []92        },93        "role_representation_scheme": {94          "current": [95            "einzelvertretungsberechtigt"96          ],97          "history": []98        }99      },100      {101        "entity_id": "cfecded2c1d17946c8ab0379aa786eed",102        "label": "MANAGING_DIRECTOR",103        "role": {104          "en": {105            "long": "Managing Director",106            "short": "MD"107          },108          "de": {109            "long": "Geschäftsführer",110            "short": "GF"111          }112        },113        "name": "Jan Musterhuber",114        "name_parts": {115          "given": "Jan",116          "family": "Musterhuber",117          "maiden": null,118          "canonical_name": "Musterhuber, Jan",119          "aliases": [120            "Musterhuber, Jan"121          ],122          "previous_names": null123        },124        "start_date": null,125        "end_date": null,126        "birth_date": "1955-11-06",127        "location": {128          "home": {129            "city": "Probeingen"130          }131        },132        "organization_representation_scheme": {133          "current": [134            "Ist nur ein Geschäftsführer bestellt, so vertritt er die Gesellschaft allein. Sind mehrere Geschäftsführer bestellt, so wird die Gesellschaft durch zwei Geschäftsführer oder durch einen Geschäftsführer gemeinsam mit einem Prokuristen vertreten."135          ],136          "history": []137        },138        "role_representation_scheme": {139          "current": [140            "einzelvertretungsberechtigt"141          ],142          "history": []143        }144      }145    ]146  },147  "meta": {148    "request_credit_cost": 15,149    "credits_remaining": 145150  }151}

200 · Výňatek z ukázkové odpovědi v režimu v reálném čase pro Hetzner Online GmbH

Pokud živé načtení selže, API vrátí uložená data z naší databáze. Poznáš to podle _realtime_mode.status, který pak není success. Režim v reálném čase se pak neúčtuje, jak ukazuje i meta.request_credit_cost.

Režim v reálném čase se vyplatí, když záleží na dnešním stavu. Například prověřuješ nové obchodní partnery před podpisem nebo zjišťuješ, kdo smí firmu právě teď zastupovat.

Načtení v reálném čase trvá déle než běžné. Nastav časový limit svého klienta alespoň na 120 sekund. Pokud požadavek trvá příliš dlouho, API odpoví 408 a nic neúčtuje. Zkus to pak později znovu.

Účetní závěrky

Nově zveřejněné účetní závěrky hledáme každý den. Firmy však mají na jejich zveřejnění až dvanáct měsíců po konci účetního období (§ 325 HGB) a mnohé lhůtu plně využívají. Některé firmy zákonnou lhůtu vědomě nedodrží a zveřejňují ještě později.

Nejnovější závěrka se proto často týká předloňského roku. Více v části Aktuálnost.

Insolvenční oznámení

Insolvenční soudy zveřejňují svá oznámení obvykle v den rozhodnutí nebo krátce poté. Dostaneš je přes funkci insolvency_publications, každé se soudem, spisovou značkou a datem.

Zprávy

Funkce news vrací zprávy o firmě z webu, s titulkem, zdrojem, datem a odkazem. Jak jsou aktuální, závisí na tom, kdy se o firmě naposledy psalo. U malých firem bývá odpovídajících zpráv často jen málo.

Historie a platnost

Mnoho údajů se v čase mění. API proto vrací aktuální stav a historii vedle sebe:

current je stav k dnešnímu dni.
history uvádí každý zapsaný stav s effective_from a effective_to. Pokud je effective_to null, stav platí dodnes.
Osoby jsou v related_persons.current a related_persons.past, každá se start_date a end_date.

Každý údaj s historií pochází z rejstříků a zveřejnění, například z Chronologischer Abdruck (CD, chronologický výpis) z Handelsregister nebo ze všech zveřejněných účetních závěrek.

Takto to vypadá v našem příkladu u způsobu zastupování Hetzner Online GmbH. V ukázkové odpovědi uvádí do 28. července 2015 představenstvo a od té doby jednatele:

1{2  "representation_scheme": {3    "current": [4      "Ist nur ein Geschäftsführer bestellt, so vertritt er die Gesellschaft allein. Sind mehrere Geschäftsführer bestellt, so wird die Gesellschaft durch zwei Geschäftsführer oder durch einen Geschäftsführer gemeinsam mit einem Prokuristen vertreten."5    ],6    "history": [7      {8        "value": [9          "Ist nur ein Vorstandsmitglied bestellt, so vertritt es die Gesellschaft allein. Sind mehrere Vorstandsmitglieder bestellt, so wird die Gesellschaft durch zwei Vorstandsmitglieder oder durch ein Vorstandsmitglied gemeinsam mit einem Prokuristen vertreten."10        ],11        "effective_from": "2002-10-15",12        "effective_to": "2015-07-28"13      },14      {15        "value": [16          "Ist nur ein Geschäftsführer bestellt, so vertritt er die Gesellschaft allein. Sind mehrere Geschäftsführer bestellt, so wird die Gesellschaft durch zwei Geschäftsführer oder durch einen Geschäftsführer gemeinsam mit einem Prokuristen vertreten."17        ],18        "effective_from": "2015-07-28",19        "effective_to": null20      }21    ]22  }23}

Ukázková odpověď: representation_scheme Hetzner Online GmbH

Většina dat má formát YYYY-MM-DD. Jak daleko historie sahá, popisuje Stáří a historie.

Prázdné hodnoty

Ne každá firma má hodnotu pro každé pole. API to ukazuje dvěma způsoby:

null: pro toto pole neexistuje hodnota.
[]: seznam nemá žádné položky, například žádná insolvenční oznámení.

Požadovaná funkce bez dat přijde jako null nebo [] a nestojí nic.

1{2  "name": "dm-drogerie markt GmbH + Co. KG",3  "legal_form": "GmbH & Co. KG",4  "contact_data": {5    "website": "https://www.dm.de",6    "phone_number": "+49 721 55920",7    "email": null8  },9  "capital": {10    "current": null,11    "history": []12  },13  "mergers_and_acquisitions": null,14  "insolvency_publications": []15}

Výňatek z ukázkové odpovědi pro dm-drogerie markt GmbH + Co. KG, s prázdnými hodnotami

Ve svém kódu zacházej s chybějícím klíčem, null a [] stejně, protože některé prázdné objekty přicházejí jako []. Pole také čti podle názvů, protože pořadí klíčů není pevné.

Pokud hodnota chybí, firma ji většinou vůbec nemusí zveřejňovat. Co zákon vyžaduje podle právní formy a velikosti, popisuje Dostupnost dat. Některé údaje záměrně nezveřejňujeme; ty pak nesou redacted: true.

Stabilita a verze

API roste aditivně. Nová data a funkce přibývají jako nová pole. Stávající pole nikdy neodstraňujeme, nepřejmenováváme a neměníme jejich typ ani význam. Každá verze tak zůstává zpětně kompatibilní.

Změny, které by rozbily stávající kód, přicházejí jen v nové verzi API, například pod /v2. Aktuální verze běží pod /v1.

Nech proto svého klienta neznámá pole ignorovat a s neznámými hodnotami zacházet jako s obecným případem. Nová pole a funkce najdeš v Changelogu.

Tarify

Profil firmy, Dokumenty, Vyhledávání a export a Signals můžeš používat s každým účtem, i bez předplatného kreditů. Předplatné kreditů přináší každý měsíc nové kredity a odemyká další data:

Tarify
Co dostaneš navíc	Plus	Pro	Max
Profil osoby: Role a podíly osob	v ceně	v ceně	v ceně
Vyhledávání a export: Filtry podle vlastnictví, vedení a insolvence	není v ceně	v ceně	v ceně
Profil firmy: Přes 90 rozšířených finančních ukazatelů	není v ceně	v ceně	v ceně
Profil firmy: Závěrky za činnosti energetických společností (§ 6b EnWG)	není v ceně	není v ceně	v ceně
Profil firmy: Podrobní společníci (`shareholders_deep`)	není v ceně	není v ceně	v ceně
Síť firmy (`network`)	není v ceně	v ceně	v ceně
Signals: Insolvence	není v ceně	v ceně	v ceně
Signals: Přeměny a M&A	není v ceně	není v ceně	v ceně

Funkce mimo tvůj tarif API vynechá bez chyby a neúčtuje je. Profily osob a vyhledávací filtry mimo tvůj tarif odmítne s 403, rovněž bez poplatku. U Signals to platí pro témata, která si výslovně vyžádáš; bez toho jednoduše dostaneš všechna témata svého tarifu.

Ceny a kredity tarifů najdeš na stránce s ceníkem.

Dále

Načíst profil firmy Název, rejstříkové číslo nebo entity_id v praxi. Dostupnost dat Jaká data existují podle právní formy a velikosti. Účtování Všechny ceny a jak je dohledáš v každé odpovědi. Chyby Jak chyby vypadají a co s nimi můžeš dělat.