Lataa asiakirjoja
Rekisteriotteet, osakasluettelot ja yhtiöjärjestykset tiedostoina.
fetch-document hakee asiakirjan Handelsregisteristä (kaupparekisteri) ja palauttaa sen tiedostona: PDF:nä tai jäsennellyn rekisterisisällön osalta XML:nä. Tarvitset vain yrityksen entity_id:n, katso Hae yritysprofiili.
Valitse asiakirjatyyppi
Asiakirjatyyppejä on viisi. Annat tyypin parametrissa document_type kirjoitettuna täsmälleen kuten taulukossa, isot ja pienet kirjaimet mukaan lukien.
| document_type | Asiakirja | Muoto | Kenelle |
|---|---|---|---|
| AD | Aktueller Abdruck (ajantasainen ote): kaikki tänään voimassa olevat merkinnät | jokainen rekisteröity yritys | |
| CD | Chronologischer Abdruck (kronologinen ote): kaikki merkinnät aikajärjestyksessä | jokainen rekisteröity yritys | |
| SI | Strukturierter Registerinhalt (jäsennelty rekisterisisältö) XJustiz-muodossa, koneluettava | XML | jokainen rekisteröity yritys |
| shareholders_list | Gesellschafterliste (osakasluettelo) | GmbH ja UG | |
| articles_of_association | Satzung tai Gesellschaftsvertrag (yhtiöjärjestys) | Pääomayhtiöt ja osuuskunnat |
Hae asiakirja
Anna entity_id parametrina company_id ja tyyppi parametrina document_type. Vastaus on itse tiedosto, ei JSON. Esimerkkipyyntömme tallentaa yrityksen Hetzner Online GmbH, Ansbach HRB 6089, Aktueller Abdruckin.
curl -G "https://handelsregister.ai/api/v1/fetch-document" \ -H "x-api-key: SINUN_API_AVAIMESI" \ --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": "SINUN_API_AVAIMESI"}, 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"], "krediittiä veloitettu")
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": "SINUN_API_AVAIMESI" }, 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"), "krediittiä veloitettu");
Koska vastaus ei ole JSONia, sitä koskevat tiedot ovat headereissa:
| Kenttä | Merkitys |
|---|---|
| Content-Type |
application/pdf, jäsennellylle rekisterisisällölle application/xml. |
| Content-Disposition | Tiedostonimi, jossa on entity_id, tyyppi ja päivä, jolloin asiakirja tuli rekisteristä. |
| X-Credits-Charged | Mitä pyyntö maksoi. |
| X-Credits-Remaining | Saldosi sen jälkeen. |
Jos asiakirjaa ei ole yritykselle, saat maksutta vastauksen 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}
Hae taustalla
Jos asiakasohjelmasi ei voi odottaa niin kauan, aseta async=true. Jos asiakirja on jo saatavilla, se tulee heti. Muuten API vastaa HTTP 202 ja kertoo odotusajan sekunteina headerissa Retry-After. Esimerkissä haemme yrityksen SAP SE, Mannheim HRB 719915, Chronologischer Abdruckin.
curl -G "https://handelsregister.ai/api/v1/fetch-document" \ -H "x-api-key: SINUN_API_AVAIMESI" \ --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": "SINUN_API_AVAIMESI"}, 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": "SINUN_API_AVAIMESI" }, }); 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}
Toista sama pyyntö tämän ajan jälkeen, niin tiedosto tulee tilalla HTTP 200. Vain toimitettu tiedosto maksaa krediittejä; 202-vastaus on maksuton. Jos kapasiteettia ei juuri nyt ole vapaana, saat vastauksen HTTP 503, myös headerin Retry-After kanssa.
Jokainen toisto lasketaan rajaan. Odota siis annettu aika sen sijaan, että kysyisit uudelleen lyhyin välein.
Kustannukset ja rajat
| Mitä | Krediitit |
|---|---|
| Yksi toimitettu asiakirja | 15 |
Raja: 5 pyyntöä minuutissa. Haulla, asiakirjoilla ja Signalsilla on yhteinen kiintiö, 60 pyyntöä minuutissa.
Jokainen toimitettu asiakirja maksaa 15 krediittiä tyypistä riippumatta. Koska jokainen asiakirja tulee rekisteristä, fetch-documentilla on oma, matalampi rajansa: 5 pyyntöä minuutissa.
Idempotency-Key:llä maksat asiakirjasta vain kerran, vaikka toistaisit pyynnön sen katkettua. Lisää kohdassa Rajat.
Retry-After. API ei veloita mitään. Yritä muutaman minuutin kuluttua uudelleen.
Yleiset sudenkuopat
- Rekisterinumero entity_id:n sijaan:
company_idottaa vain 32-merkkisen entity_id:n.Ansbach HRB 6089palauttaa HTTP 400. - Osakasluettelo muille yhtiömuodoille: Se on olemassa vain GmbH:lle ja UG:lle. KG:lle tai elinkeinonharjoittajalle saat vastauksen HTTP 404.
- Asiakirjat kuvatiedostoina: Jos asiakirja on rekisterissä saatavilla vain TIFF-muodossa, API vastaa HTTP 415 eikä veloita mitään.