Last ned dokumenter
Registerutskrifter, eierlister og vedtekter som filer.
fetch-document henter et dokument fra Handelsregister (handelsregisteret) og returnerer det som fil: som PDF, eller som XML for det strukturerte registerinnholdet. Alt du trenger, er firmaets entity_id, se Hent en firmaprofil.
Velg dokumenttype
Det finnes fem dokumenttyper. Typen sender du i document_type, skrevet nøyaktig som i tabellen, også med store og små bokstaver.
| document_type | Dokument | Format | For |
|---|---|---|---|
| AD | Aktueller Abdruck (aktuell utskrift): alle oppføringer som gjelder i dag | hvert registrert firma | |
| CD | Chronologischer Abdruck (kronologisk utskrift): alle oppføringer i kronologisk rekkefølge | hvert registrert firma | |
| SI | Strukturierter Registerinhalt (strukturert registerinnhold) i XJustiz-formatet, maskinlesbart | XML | hvert registrert firma |
| shareholders_list | Gesellschafterliste (eierliste) | GmbH og UG | |
| articles_of_association | Satzung eller Gesellschaftsvertrag (vedtekter) | Kapitalselskaper og samvirkeforetak |
Hent et dokument
Send entity_id som company_id og typen som document_type. Svaret er selve filen, ikke JSON. Eksempelforespørselen vår lagrer Aktueller Abdruck for Hetzner Online GmbH, Ansbach HRB 6089.
curl -G "https://handelsregister.ai/api/v1/fetch-document" \ -H "x-api-key: YOUR_API_KEY" \ --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": "YOUR_API_KEY"}, 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"], "kreditter belastet")
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": "YOUR_API_KEY" }, 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"), "kreditter belastet");
Fordi svaret ikke er JSON, står opplysningene om det i headerne:
| Felt | Betydning |
|---|---|
| Content-Type |
application/pdf, for det strukturerte registerinnholdet application/xml. |
| Content-Disposition | Filnavnet med entity_id, type og dagen dokumentet kom fra registeret. |
| X-Credits-Charged | Hva forespørselen kostet. |
| X-Credits-Remaining | Saldoen din etterpå. |
Finnes dokumentet ikke for firmaet, får du HTTP 404 uten kostnad.
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}
Hent i bakgrunnen
Kan klienten din ikke vente så lenge, setter du async=true. Er dokumentet allerede tilgjengelig, kommer det med en gang. Ellers svarer API-et med HTTP 202 og oppgir ventetiden i sekunder i Retry-After. I eksempelet henter vi Chronologischer Abdruck for SAP SE, Mannheim HRB 719915.
curl -G "https://handelsregister.ai/api/v1/fetch-document" \ -H "x-api-key: YOUR_API_KEY" \ --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": "YOUR_API_KEY"}, 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": "YOUR_API_KEY" }, }); 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}
Gjenta den samme forespørselen etter denne tiden, så kommer filen med HTTP 200. Bare den leverte filen koster kreditter; 202-svaret er gratis. Er ingen kapasitet ledig akkurat nå, får du HTTP 503, også med Retry-After.
Hver gjentakelse teller mot grensen. Vent derfor den oppgitte tiden i stedet for å spørre igjen med korte mellomrom.
Kostnader og grenser
| Hva | Kreditter |
|---|---|
| Ett levert dokument | 15 |
Grense: 5 forespørsler per minutt. Søk, dokumenter og Signals deler en kvote på 60 forespørsler per minutt.
Hvert levert dokument koster 15 kreditter, uansett type. Fordi hvert dokument kommer fra registeret, har fetch-document sin egen, lavere grense på 5 forespørsler per minutt.
Med en Idempotency-Key betaler du bare én gang for et dokument, også om du gjentar forespørselen etter at den ble brutt. Mer under Grenser.
Retry-After. API-et belaster ingenting. Prøv igjen etter noen minutter.
Vanlige fallgruver
- Registernummer i stedet for entity_id:
company_idtar bare imot den 32 tegn lange entity_id.Ansbach HRB 6089gir HTTP 400. - Eierliste for andre selskapsformer: Den finnes bare for GmbH og UG. For et KG eller et enkeltpersonforetak får du HTTP 404.
- Dokumenter som bildefiler: Finnes et dokument bare som TIFF i registeret, svarer API-et med HTTP 415 og belaster ingenting.