Documenten downloaden
Registeruittreksels, aandeelhouderslijsten en statuten als bestand.
fetch-document haalt een document uit het Handelsregister (Duits handelsregister) en levert het als bestand: als PDF, of als XML voor de gestructureerde registerinhoud. Je hebt alleen de entity_id van het bedrijf nodig, zie Een bedrijfsprofiel ophalen.
Het documenttype kiezen
Er zijn vijf documenttypen. Het type geef je mee in document_type, precies geschreven zoals in de tabel, inclusief hoofd- en kleine letters.
| document_type | Document | Formaat | Voor |
|---|---|---|---|
| AD | Aktueller Abdruck (actueel uittreksel): alle inschrijvingen die vandaag gelden | elk ingeschreven bedrijf | |
| CD | Chronologischer Abdruck (chronologisch uittreksel): alle inschrijvingen in chronologische volgorde | elk ingeschreven bedrijf | |
| SI | Strukturierter Registerinhalt (gestructureerde registerinhoud) in het XJustiz-formaat, machineleesbaar | XML | elk ingeschreven bedrijf |
| shareholders_list | Gesellschafterliste (aandeelhouderslijst) | GmbH en UG | |
| articles_of_association | Satzung of Gesellschaftsvertrag (statuten) | Kapitaalvennootschappen en coöperaties |
Een document ophalen
Geef de entity_id mee als company_id en het type als document_type. Het antwoord is het bestand zelf, geen JSON. Onze voorbeeldaanvraag slaat de Aktueller Abdruck van Hetzner Online GmbH, Ansbach HRB 6089, op.
curl -G "https://handelsregister.ai/api/v1/fetch-document" \ -H "x-api-key: JOUW_API_SLEUTEL" \ --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": "JOUW_API_SLEUTEL"}, 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 berekend")
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": "JOUW_API_SLEUTEL" }, 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 berekend");
Omdat het antwoord geen JSON is, staan de gegevens erover in de headers:
| Veld | Betekenis |
|---|---|
| Content-Type |
application/pdf, voor de gestructureerde registerinhoud application/xml. |
| Content-Disposition | De bestandsnaam met entity_id, type en de dag waarop het document uit het register kwam. |
| X-Credits-Charged | Wat de aanvraag kostte. |
| X-Credits-Remaining | Je saldo daarna. |
Bestaat het document voor het bedrijf niet, dan krijg je HTTP 404 zonder 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}
Op de achtergrond ophalen
Kan je client niet zo lang wachten, zet dan async=true. Is het document al beschikbaar, dan komt het meteen. Anders antwoordt de API met HTTP 202 en geeft de wachttijd in seconden in Retry-After. In het voorbeeld halen we de Chronologischer Abdruck van SAP SE, Mannheim HRB 719915, op.
curl -G "https://handelsregister.ai/api/v1/fetch-document" \ -H "x-api-key: JOUW_API_SLEUTEL" \ --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": "JOUW_API_SLEUTEL"}, 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": "JOUW_API_SLEUTEL" }, }); 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}
Herhaal na deze tijd dezelfde aanvraag, dan komt het bestand met HTTP 200. Alleen het geleverde bestand kost credits; het 202-antwoord is gratis. Is er op dit moment geen capaciteit vrij, dan krijg je HTTP 503, ook met Retry-After.
Elke herhaling telt mee voor de limiet. Wacht dus de opgegeven tijd in plaats van met korte tussenpozen opnieuw te vragen.
Kosten en limieten
| Wat | Credits |
|---|---|
| Eén geleverd document | 15 |
Limiet: 5 aanvragen per minuut. Zoeken, documenten en Signals delen een quotum van 60 aanvragen per minuut.
Elk geleverd document kost 15 credits, ongeacht het type. Omdat elk document uit het register komt, heeft fetch-document een eigen, lagere limiet van 5 aanvragen per minuut.
Met een Idempotency-Key betaal je maar één keer voor een document, ook als je de aanvraag na een afgebroken verbinding herhaalt. Meer onder Limieten.
Retry-After. De API berekent niets. Probeer het na een paar minuten opnieuw.
Veelgemaakte fouten
- Registernummer in plaats van entity_id:
company_idaccepteert alleen de entity_id van 32 tekens.Ansbach HRB 6089levert HTTP 400. - Aandeelhouderslijst voor andere rechtsvormen: Die bestaat alleen voor GmbH en UG. Voor een KG of een eenmanszaak krijg je HTTP 404.
- Documenten als afbeeldingsbestand: Is een document in het register alleen als TIFF beschikbaar, dan antwoordt de API met HTTP 415 en berekent niets.