Descarcă documente
Extrase din registru, liste ale asociaților și acte constitutive ca fișiere.
fetch-document preia un document din Handelsregister (registrul comerțului) și îl returnează ca fișier: ca PDF sau ca XML pentru conținutul structurat al registrului. Ai nevoie doar de entity_id-ul companiei, vezi Preia un profil de companie.
Alege tipul de document
Există cinci tipuri de documente. Transmiți tipul în document_type, scris exact ca în tabel, inclusiv literele mari și mici.
| document_type | Document | Format | Pentru |
|---|---|---|---|
| AD | Aktueller Abdruck (extrasul curent): toate înscrierile valabile azi | orice companie înregistrată | |
| CD | Chronologischer Abdruck (extrasul cronologic): toate înscrierile în ordine cronologică | orice companie înregistrată | |
| SI | Strukturierter Registerinhalt (conținutul structurat al registrului) în formatul XJustiz, lizibil de mașină | XML | orice companie înregistrată |
| shareholders_list | Gesellschafterliste (lista asociaților) | GmbH și UG | |
| articles_of_association | Satzung sau Gesellschaftsvertrag (actul constitutiv) | Societăți de capital și cooperative |
Preia un document
Transmite entity_id-ul ca company_id și tipul ca document_type. Răspunsul este fișierul însuși, nu JSON. Cererea noastră exemplu salvează Aktueller Abdruck al Hetzner Online GmbH, Ansbach HRB 6089.
curl -G "https://handelsregister.ai/api/v1/fetch-document" \ -H "x-api-key: CHEIA_TA_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": "CHEIA_TA_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"], "credite taxate")
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": "CHEIA_TA_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"), "credite taxate");
Pentru că răspunsul nu este JSON, informațiile despre el se află în headere:
| Câmp | Semnificație |
|---|---|
| Content-Type |
application/pdf, pentru conținutul structurat al registrului application/xml. |
| Content-Disposition | Numele fișierului cu entity_id, tipul și ziua în care documentul a venit din registru. |
| X-Credits-Charged | Cât a costat cererea. |
| X-Credits-Remaining | Soldul tău după aceea. |
Dacă documentul nu există pentru companie, primești HTTP 404 fără cost.
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}
Preluare în fundal
Dacă clientul tău nu poate aștepta atât, setează async=true. Dacă documentul e deja disponibil, vine imediat. Altfel API-ul răspunde cu HTTP 202 și indică timpul de așteptare în secunde în Retry-After. În exemplu preluăm Chronologischer Abdruck al SAP SE, Mannheim HRB 719915.
curl -G "https://handelsregister.ai/api/v1/fetch-document" \ -H "x-api-key: CHEIA_TA_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": "CHEIA_TA_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": "CHEIA_TA_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}
Repetă aceeași cerere după acest timp, iar fișierul vine cu HTTP 200. Doar fișierul livrat costă credite; răspunsul 202 e gratuit. Dacă momentan nu e capacitate liberă, primești HTTP 503, tot cu Retry-After.
Fiecare repetare se socotește la limită. Așteaptă deci timpul indicat în loc să întrebi din nou la intervale scurte.
Costuri și limite
| Ce | Credite |
|---|---|
| Un document livrat | 15 |
Limită: 5 cereri pe minut. Căutarea, documentele și Signals împart o cotă de 60 cereri pe minut.
Fiecare document livrat costă 15 credite, indiferent de tip. Pentru că fiecare document vine din registru, fetch-document are propria limită, mai mică, de 5 cereri pe minut.
Cu un Idempotency-Key plătești un document o singură dată, chiar dacă repeți cererea după ce a fost întreruptă. Mai multe la Limite.
Retry-After. API-ul nu taxează nimic. Încearcă din nou după câteva minute.
Capcane frecvente
- Număr de registru în loc de entity_id:
company_idacceptă doar entity_id-ul de 32 de caractere.Ansbach HRB 6089returnează HTTP 400. - Lista asociaților pentru alte forme juridice: Există doar pentru GmbH și UG. Pentru un KG sau un comerciant individual primești HTTP 404.
- Documente ca fișiere imagine: Dacă un document e disponibil în registru doar ca TIFF, API-ul răspunde cu HTTP 415 și nu taxează nimic.