Scaricare documenti
Estratti del registro, elenchi soci e statuti come file.
fetch-document recupera un documento dall’Handelsregister (registro delle imprese) e lo restituisce come file: in PDF, oppure in XML per il contenuto strutturato del registro. Ti serve solo l’entity_id dell’azienda, vedi Recuperare un profilo aziendale.
Scegliere il tipo di documento
Ci sono cinque tipi di documento. Passi il tipo in document_type, scritto esattamente come nella tabella, maiuscole e minuscole comprese.
| document_type | Documento | Formato | Per |
|---|---|---|---|
| AD | Aktueller Abdruck (estratto attuale): tutte le iscrizioni valide oggi | ogni azienda iscritta | |
| CD | Chronologischer Abdruck (estratto cronologico): tutte le iscrizioni in ordine cronologico | ogni azienda iscritta | |
| SI | Strukturierter Registerinhalt (contenuto strutturato del registro) nel formato XJustiz, leggibile dalle macchine | XML | ogni azienda iscritta |
| shareholders_list | Gesellschafterliste (elenco soci) | GmbH e UG | |
| articles_of_association | Satzung o Gesellschaftsvertrag (statuto o atto costitutivo) | Società di capitali e cooperative |
Recuperare un documento
Passa l’entity_id come company_id e il tipo come document_type. La risposta è il file stesso, non JSON. La nostra richiesta di esempio salva l’Aktueller Abdruck di Hetzner Online GmbH, Ansbach HRB 6089.
curl -G "https://handelsregister.ai/api/v1/fetch-document" \ -H "x-api-key: LA_TUA_CHIAVE_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": "LA_TUA_CHIAVE_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"], "crediti addebitati")
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": "LA_TUA_CHIAVE_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"), "crediti addebitati");
Poiché la risposta non è JSON, i dettagli su di essa sono negli header:
| Campo | Significato |
|---|---|
| Content-Type |
application/pdf, per il contenuto strutturato del registro application/xml. |
| Content-Disposition | Il nome del file con entity_id, tipo e il giorno in cui il documento è arrivato dal registro. |
| X-Credits-Charged | Quanto è costata la richiesta. |
| X-Credits-Remaining | Il tuo saldo dopo. |
Se il documento non esiste per l’azienda, ricevi HTTP 404 senza costi.
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}
Recuperare in background
Se il tuo client non può aspettare così a lungo, imposta async=true. Se il documento è già disponibile, arriva subito. Altrimenti l’API risponde con HTTP 202 e indica il tempo di attesa in secondi in Retry-After. Nell’esempio recuperiamo il Chronologischer Abdruck di SAP SE, Mannheim HRB 719915.
curl -G "https://handelsregister.ai/api/v1/fetch-document" \ -H "x-api-key: LA_TUA_CHIAVE_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": "LA_TUA_CHIAVE_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": "LA_TUA_CHIAVE_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}
Ripeti la stessa richiesta dopo questo tempo e il file arriva con HTTP 200. Solo il file consegnato costa crediti; la risposta 202 è gratuita. Se al momento non c’è capacità libera, ricevi HTTP 503, anch’esso con Retry-After.
Ogni ripetizione conta per il limite. Quindi aspetta il tempo indicato invece di chiedere di nuovo a brevi intervalli.
Costi e limiti
| Cosa | Crediti |
|---|---|
| Un documento consegnato | 15 |
Limite: 5 richieste al minuto. Ricerca, documenti e Signals condividono una quota di 60 richieste al minuto.
Ogni documento consegnato costa 15 crediti, qualunque sia il tipo. Poiché ogni documento arriva dal registro, fetch-document ha un suo limite più basso di 5 richieste al minuto.
Con un Idempotency-Key paghi un documento una sola volta, anche se ripeti la richiesta dopo che si è interrotta. Maggiori dettagli in Limiti.
Retry-After. L’API non addebita nulla. Riprova dopo qualche minuto.
Errori frequenti
- Numero di registro invece di entity_id:
company_idaccetta solo l’entity_id di 32 caratteri.Ansbach HRB 6089restituisce HTTP 400. - Elenco soci per altre forme giuridiche: Esiste solo per GmbH e UG. Per una KG o un imprenditore individuale ricevi HTTP 404.
- Documenti come file immagine: Se un documento nel registro è disponibile solo come TIFF, l’API risponde con HTTP 415 e non addebita nulla.