Pobieraj dokumenty
Odpisy z rejestru, listy wspólników i umowy spółki jako pliki.
fetch-document pobiera dokument z Handelsregister (rejestr handlowy) i zwraca go jako plik: jako PDF albo jako XML dla ustrukturyzowanej treści rejestru. Potrzebujesz tylko entity_id firmy, zobacz Pobierz profil firmy.
Wybierz typ dokumentu
Jest pięć typów dokumentów. Typ przekazujesz w document_type, zapisany dokładnie jak w tabeli, z wielkością liter.
| document_type | Dokument | Format | Dla |
|---|---|---|---|
| AD | Aktueller Abdruck (odpis aktualny): wszystkie wpisy obowiązujące dziś | każdej zarejestrowanej firmy | |
| CD | Chronologischer Abdruck (odpis chronologiczny): wszystkie wpisy w kolejności chronologicznej | każdej zarejestrowanej firmy | |
| SI | Strukturierter Registerinhalt (ustrukturyzowana treść rejestru) w formacie XJustiz, czytelna dla maszyn | XML | każdej zarejestrowanej firmy |
| shareholders_list | Gesellschafterliste (lista wspólników) | GmbH i UG | |
| articles_of_association | Satzung lub Gesellschaftsvertrag (umowa spółki / statut) | spółek kapitałowych i spółdzielni |
Pobierz dokument
Przekaż entity_id jako company_id i typ jako document_type. Odpowiedzią jest sam plik, nie JSON. Nasze przykładowe zapytanie zapisuje Aktueller Abdruck Hetzner Online GmbH, Ansbach HRB 6089.
curl -G "https://handelsregister.ai/api/v1/fetch-document" \ -H "x-api-key: TWOJ_KLUCZ_API" \ --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": "TWOJ_KLUCZ_API"}, 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"], "pobrano kredytów")
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": "TWOJ_KLUCZ_API" }, 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"), "pobrano kredytów");
Ponieważ odpowiedź nie jest JSON-em, informacje o niej są w nagłówkach:
| Pole | Znaczenie |
|---|---|
| Content-Type |
application/pdf, dla ustrukturyzowanej treści rejestru application/xml. |
| Content-Disposition | Nazwa pliku z entity_id, typem i dniem, z którego dokument pochodzi z rejestru. |
| X-Credits-Charged | Ile kosztowało zapytanie. |
| X-Credits-Remaining | Twoje saldo po zapytaniu. |
Jeśli dla firmy nie ma takiego dokumentu, dostajesz bezpłatnie HTTP 404.
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}
Pobieranie w tle
Jeśli twój klient nie może czekać tak długo, ustaw async=true. Jeśli dokument jest już dostępny, przychodzi od razu. W przeciwnym razie API odpowiada HTTP 202 i podaje czas oczekiwania w sekundach w Retry-After. W przykładzie pobieramy Chronologischer Abdruck SAP SE, Mannheim HRB 719915.
curl -G "https://handelsregister.ai/api/v1/fetch-document" \ -H "x-api-key: TWOJ_KLUCZ_API" \ --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": "TWOJ_KLUCZ_API"}, 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": "TWOJ_KLUCZ_API" }, }); 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}
Powtórz to samo zapytanie po tym czasie, a plik przyjdzie z HTTP 200. Kredyty kosztuje tylko dostarczony plik; odpowiedź 202 jest bezpłatna. Jeśli w tej chwili nie ma wolnej przepustowości, dostajesz HTTP 503, także z Retry-After.
Każde powtórzenie wlicza się do limitu. Odczekaj więc podany czas, zamiast pytać ponownie w krótkich odstępach.
Koszty i limity
| Co | Kredyty |
|---|---|
| Jeden dostarczony dokument | 15 |
Limit: 5 zapytań na minutę. Wyszukiwanie, dokumenty i Signals dzielą wspólną pulę 60 zapytań na minutę.
Każdy dostarczony dokument kosztuje 15 kredytów, niezależnie od typu. Ponieważ każdy dokument pochodzi z rejestru, fetch-document ma własny, niższy limit 5 zapytań na minutę.
Z Idempotency-Key płacisz za dokument tylko raz, nawet jeśli powtórzysz zapytanie po jego przerwaniu. Więcej w Limitach.
Retry-After. API nic nie nalicza. Spróbuj ponownie za kilka minut.
Częste pułapki
- Numer rejestru zamiast entity_id:
company_idprzyjmuje tylko 32-znakowe entity_id.Ansbach HRB 6089zwraca HTTP 400. - Lista wspólników dla innych form prawnych: istnieje tylko dla GmbH i UG. Dla KG lub jednoosobowego przedsiębiorcy dostajesz HTTP 404.
- Dokumenty jako pliki graficzne: jeśli dokument jest w rejestrze dostępny tylko jako TIFF, API odpowiada HTTP 415 i nic nie nalicza.