Dokumentumok letöltése
Cégkivonatok, tagjegyzékek és társasági szerződések fájlként.
A fetch-document lekér egy dokumentumot a Handelsregisterből (német cégnyilvántartás), és fájlként adja vissza: PDF-ként, vagy a strukturált nyilvántartási tartalomhoz XML-ként. Csak a cég entity_id-jára van szükséged, lásd Cégprofil lekérése.
A dokumentumtípus kiválasztása
Öt dokumentumtípus van. A típust a document_type paraméterben adod meg, pontosan úgy írva, ahogy a táblázatban áll, a kis- és nagybetűket is beleértve.
| document_type | Dokumentum | Formátum | Kinek |
|---|---|---|---|
| AD | Aktueller Abdruck (aktuális kivonat): a ma érvényes összes bejegyzés | minden bejegyzett cég | |
| CD | Chronologischer Abdruck (kronologikus kivonat): az összes bejegyzés időrendben | minden bejegyzett cég | |
| SI | Strukturierter Registerinhalt (strukturált nyilvántartási tartalom) XJustiz formátumban, géppel olvasható | XML | minden bejegyzett cég |
| shareholders_list | Gesellschafterliste (tagjegyzék) | GmbH és UG | |
| articles_of_association | Satzung vagy Gesellschaftsvertrag (alapszabály, társasági szerződés) | Tőketársaságok és szövetkezetek |
Dokumentum lekérése
Add meg az entity_id-t company_id-ként és a típust document_type-ként. A válasz maga a fájl, nem JSON. A példakérésünk a Hetzner Online GmbH (Ansbach HRB 6089) Aktueller Abdruck dokumentumát menti el.
curl -G "https://handelsregister.ai/api/v1/fetch-document" \ -H "x-api-key: AZ_API_KULCSOD" \ --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": "AZ_API_KULCSOD"}, 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"], "kredit felszámítva")
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": "AZ_API_KULCSOD" }, 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"), "kredit felszámítva");
Mivel a válasz nem JSON, az adatai a headerekben vannak:
| Mező | Jelentés |
|---|---|
| Content-Type |
application/pdf, a strukturált nyilvántartási tartalomnál application/xml. |
| Content-Disposition | A fájlnév entity_id-val, típussal és azzal a nappal, amikor a dokumentum a nyilvántartásból érkezett. |
| X-Credits-Charged | Mennyibe került a kérés. |
| X-Credits-Remaining | Az egyenleged utána. |
Ha a dokumentum nem létezik a céghez, díjmentesen HTTP 404-et kapsz.
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}
Lekérés a háttérben
Ha a kliensed nem tud ennyit várni, állítsd be az async=true paramétert. Ha a dokumentum már elérhető, azonnal megjön. Különben az API HTTP 202-vel válaszol, és a Retry-After headerben megadja a várakozási időt másodpercben. A példában a SAP SE (Mannheim HRB 719915) Chronologischer Abdruck dokumentumát kérjük le.
curl -G "https://handelsregister.ai/api/v1/fetch-document" \ -H "x-api-key: AZ_API_KULCSOD" \ --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": "AZ_API_KULCSOD"}, 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": "AZ_API_KULCSOD" }, }); 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}
Ennyi idő után ismételd meg ugyanazt a kérést, és a fájl HTTP 200-zal érkezik. Csak a kiszállított fájl kerül kreditbe; a 202-es válasz ingyenes. Ha éppen nincs szabad kapacitás, HTTP 503-at kapsz, szintén Retry-After headerrel.
Minden ismétlés beleszámít a limitbe. Ezért várd ki a megadott időt, ahelyett hogy rövid időközönként újra kérdeznél.
Költségek és limitek
| Mi | Kredit |
|---|---|
| Egy kiszállított dokumentum | 15 |
Limit: percenként 5 kérés. A keresés, a dokumentumok és a Signals közös keretet használ: percenként 60 kérés.
Minden kiszállított dokumentum 15 kredit kerül, típustól függetlenül. Mivel minden dokumentum a nyilvántartásból jön, a fetch-document saját, alacsonyabb limittel rendelkezik: percenként 5 kérés.
Egy Idempotency-Key-jel egy dokumentumért csak egyszer fizetsz, akkor is, ha megszakadás után megismétled a kérést. Bővebben a Limitek alatt.
Retry-After headerrel. Az API semmit nem számol fel. Próbáld újra néhány perc múlva.
Gyakori buktatók
- Cégjegyzékszám entity_id helyett: a
company_idcsak a 32 karakteres entity_id-t fogadja el. AzAnsbach HRB 6089HTTP 400-at ad. - Tagjegyzék más jogi formáknál: csak GmbH-nál és UG-nál létezik. KG-nál vagy egyéni kereskedőnél HTTP 404-et kapsz.
- Dokumentumok képfájlként: ha egy dokumentum a nyilvántartásban csak TIFF-ként érhető el, az API HTTP 415-tel válaszol, és semmit nem számol fel.