Dokumente herunterladen
Registerauszüge, Gesellschafterlisten und Satzungen als Datei.
fetch-document holt ein Dokument aus dem Handelsregister und liefert es als Datei, als PDF oder beim strukturierten Registerinhalt als XML. Du brauchst dafür nur die entity_id der Firma, siehe Firmenprofil abrufen.
Dokumenttyp wählen
Es gibt fünf Dokumenttypen. Den Typ gibst du in document_type an, genau so geschrieben wie in der Tabelle, auch in Groß- und Kleinschreibung.
| document_type | Dokument | Format | Für |
|---|---|---|---|
| AD | Aktueller Abdruck: alle Eintragungen, die heute gelten | jede eingetragene Firma | |
| CD | Chronologischer Abdruck: alle Eintragungen in zeitlicher Folge | jede eingetragene Firma | |
| SI | Strukturierter Registerinhalt im Format XJustiz, maschinenlesbar | XML | jede eingetragene Firma |
| shareholders_list | Gesellschafterliste | GmbH und UG | |
| articles_of_association | Satzung bzw. Gesellschaftsvertrag | Kapitalgesellschaften und Genossenschaften |
Dokument abrufen
Gib die entity_id als company_id an und den Typ als document_type. Die Antwort ist die Datei selbst, kein JSON. Unsere Beispielanfrage speichert den aktuellen Abdruck der Hetzner Online GmbH, Ansbach HRB 6089.
curl -G "https://handelsregister.ai/api/v1/fetch-document" \ -H "x-api-key: DEIN_API_SCHLUESSEL" \ --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": "DEIN_API_SCHLUESSEL"}, 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"], "Credits berechnet")
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": "DEIN_API_SCHLUESSEL" }, 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"), "Credits berechnet");
Weil die Antwort kein JSON ist, stehen die Angaben dazu in den Headern:
| Feld | Bedeutung |
|---|---|
| Content-Type |
application/pdf, beim strukturierten Registerinhalt application/xml. |
| Content-Disposition | Der Dateiname mit entity_id, Typ und dem Tag, an dem das Dokument aus dem Register kam. |
| X-Credits-Charged | Was die Anfrage gekostet hat. |
| X-Credits-Remaining | Dein Guthaben danach. |
Gibt es das Dokument für die Firma nicht, kommt HTTP 404 ohne Kosten.
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}
Im Hintergrund abrufen
Wenn dein Client nicht so lange warten kann, setz async=true. Liegt das Dokument schon bereit, kommt es sofort. Sonst antwortet die API mit HTTP 202 und nennt in Retry-After die Wartezeit in Sekunden. Im Beispiel holen wir den chronologischen Abdruck der SAP SE, Mannheim HRB 719915.
curl -G "https://handelsregister.ai/api/v1/fetch-document" \ -H "x-api-key: DEIN_API_SCHLUESSEL" \ --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": "DEIN_API_SCHLUESSEL"}, 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": "DEIN_API_SCHLUESSEL" }, }); 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}
Wiederhol dieselbe Anfrage nach dieser Zeit, dann kommt die Datei mit HTTP 200. Erst die gelieferte Datei kostet Credits, die Antwort 202 ist kostenlos. Ist gerade keine Kapazität frei, kommt HTTP 503, ebenfalls mit Retry-After.
Jede Wiederholung zählt zum Limit. Warte deshalb die angegebene Zeit ab, statt in kurzen Abständen nachzufragen.
Kosten und Limits
| Was | Credits |
|---|---|
| Ein geliefertes Dokument | 15 |
Limit: 5 Anfragen pro Minute. Suche, Dokumente und Signals teilen sich ein Kontingent von 60 Anfragen pro Minute.
Jedes gelieferte Dokument kostet 15 Credits, egal welcher Typ. Weil jedes Dokument aus dem Register kommt, hat fetch-document ein eigenes, kleineres Limit von 5 Anfragen pro Minute.
Mit einem Idempotency-Key bezahlst du ein Dokument nur einmal, auch wenn du die Anfrage nach einem Abbruch wiederholst. Mehr dazu unter Limits.
Retry-After. Die API berechnet nichts. Versuch es nach ein paar Minuten erneut.
Typische Stolpersteine
- Registernummer statt entity_id:
company_idnimmt nur die entity_id aus 32 Zeichen.Ansbach HRB 6089ergibt HTTP 400. - Gesellschafterliste bei anderen Rechtsformen: Sie gibt es nur für GmbH und UG. Für eine KG oder einen Einzelkaufmann kommt HTTP 404.
- Dokumente als Bilddatei: Liegt ein Dokument im Register nur als TIFF vor, antwortet die API mit HTTP 415 und berechnet nichts.