Stáhnout dokumenty
Výpisy z rejstříku, seznamy společníků a společenské smlouvy jako soubory.
fetch-document načte dokument z Handelsregister (obchodní rejstřík) a vrátí ho jako soubor: jako PDF, nebo jako XML pro strukturovaný obsah rejstříku. Stačí ti entity_id firmy, viz Načíst profil firmy.
Zvolit typ dokumentu
Existuje pět typů dokumentů. Typ předáš v document_type, napsaný přesně jako v tabulce, včetně velkých a malých písmen.
| document_type | Dokument | Formát | Pro |
|---|---|---|---|
| AD | Aktueller Abdruck (aktuální výpis): všechny dnes platné zápisy | každou zapsanou firmu | |
| CD | Chronologischer Abdruck (chronologický výpis): všechny zápisy v chronologickém pořadí | každou zapsanou firmu | |
| SI | Strukturierter Registerinhalt (strukturovaný obsah rejstříku) ve formátu XJustiz, strojově čitelný | XML | každou zapsanou firmu |
| shareholders_list | Gesellschafterliste (seznam společníků) | GmbH a UG | |
| articles_of_association | Satzung nebo Gesellschaftsvertrag (stanovy nebo společenská smlouva) | Kapitálové společnosti a družstva |
Načíst dokument
Předej entity_id jako company_id a typ jako document_type. Odpovědí je samotný soubor, ne JSON. Náš ukázkový požadavek ukládá Aktueller Abdruck Hetzner Online GmbH, Ansbach HRB 6089.
curl -G "https://handelsregister.ai/api/v1/fetch-document" \ -H "x-api-key: TVUJ_API_KLIC" \ --data-urlencode "company_id=94eb910fef13f94585c48c263fa446d4" \ --data-urlencode "document_type=AD" \ --fail-with-body --max-time 120 \ -o hetzner-ad.pdf
import requests response = requests.get( "https://handelsregister.ai/api/v1/fetch-document", headers={"x-api-key": "TVUJ_API_KLIC"}, params={ "company_id": "94eb910fef13f94585c48c263fa446d4", "document_type": "AD", }, timeout=120, ) response.raise_for_status() with open("hetzner-ad.pdf", "wb") as file: file.write(response.content) print(response.headers["X-Credits-Charged"], "účtovaných kreditů")
import { writeFile } from "node:fs/promises"; const url = new URL("https://handelsregister.ai/api/v1/fetch-document"); url.searchParams.append("company_id", "94eb910fef13f94585c48c263fa446d4"); url.searchParams.append("document_type", "AD"); const response = await fetch(url, { headers: { "x-api-key": "TVUJ_API_KLIC" }, signal: AbortSignal.timeout(120_000), }); if (!response.ok) throw new Error(`HTTP ${response.status}`); await writeFile("hetzner-ad.pdf", Buffer.from(await response.arrayBuffer())); console.log(response.headers.get("x-credits-charged"), "účtovaných kreditů");
Protože odpověď není JSON, údaje o ní jsou v headerech:
| Pole | Význam |
|---|---|
| Content-Type |
application/pdf, pro strukturovaný obsah rejstříku application/xml. |
| Content-Disposition | Název souboru s entity_id, typem a dnem, kdy dokument přišel z rejstříku. |
| X-Credits-Charged | Kolik požadavek stál. |
| X-Credits-Remaining | Tvůj zůstatek poté. |
Pokud dokument pro firmu neexistuje, dostaneš HTTP 404 bez poplatku.
1{2 "error": "Document fetch failed",3 "message": "Document not available for this company. It may not exist or may become available later.",4 "meta": {5 "request_credit_cost": 0,6 "credits_remaining": 1457 }8}
Načíst na pozadí
Pokud tvůj klient nemůže čekat tak dlouho, nastav async=true. Pokud je dokument už k dispozici, přijde hned. Jinak API odpoví HTTP 202 a uvede čekací dobu v sekundách v Retry-After. V příkladu načítáme Chronologischer Abdruck SAP SE, Mannheim HRB 719915.
curl -G "https://handelsregister.ai/api/v1/fetch-document" \ -H "x-api-key: TVUJ_API_KLIC" \ --data-urlencode 'company_id=e3918174fb6c5d04e5e217e6ee4a6ffe' \ --data-urlencode 'document_type=CD' \ --data-urlencode 'async=true'
import requests response = requests.get( "https://handelsregister.ai/api/v1/fetch-document", headers={"x-api-key": "TVUJ_API_KLIC"}, params={ "company_id": "e3918174fb6c5d04e5e217e6ee4a6ffe", "document_type": "CD", "async": "true", }, ) data = response.json()
const url = new URL("https://handelsregister.ai/api/v1/fetch-document"); url.searchParams.append("company_id", "e3918174fb6c5d04e5e217e6ee4a6ffe"); url.searchParams.append("document_type", "CD"); url.searchParams.append("async", "true"); const response = await fetch(url, { headers: { "x-api-key": "TVUJ_API_KLIC" }, }); const data = await response.json();
1{2 "status": "processing",3 "meta": {4 "message": "The document is being retrieved. Repeat this request after Retry-After seconds to receive it.",5 "retry_after": 20,6 "request_credit_cost": 0,7 "credits_remaining": 1458 }9}
Po uplynutí této doby zopakuj stejný požadavek a soubor přijde s HTTP 200. Kredity stojí jen doručený soubor; odpověď 202 je zdarma. Pokud právě není volná kapacita, dostaneš HTTP 503, rovněž s Retry-After.
Každé opakování se započítává do limitu. Vyčkej proto uvedenou dobu, místo aby ses znovu ptal v krátkých intervalech.
Náklady a limity
| Co | Kredity |
|---|---|
| Jeden doručený dokument | 15 |
Limit: 5 požadavků za minutu. Vyhledávání, dokumenty a Signals sdílejí kvótu 60 požadavků za minutu.
Každý doručený dokument stojí 15 kreditů, bez ohledu na typ. Protože každý dokument pochází z rejstříku, má fetch-document vlastní, nižší limit 5 požadavků za minutu.
S Idempotency-Key zaplatíš za dokument jen jednou, i když požadavek po přerušení zopakuješ. Více v části Limity.
Retry-After. API nic neúčtuje. Zkus to znovu za pár minut.
Časté chyby
- Rejstříkové číslo místo entity_id:
company_idpřijímá jen 32znakové entity_id.Ansbach HRB 6089vrátí HTTP 400. - Seznam společníků u jiných právních forem: Existuje jen pro GmbH a UG. U KG nebo jednotlivce zapsaného jako kupec dostaneš HTTP 404.
- Dokumenty jako obrázky: Pokud je dokument v rejstříku k dispozici jen jako TIFF, API odpoví HTTP 415 a nic neúčtuje.