Dati anagrafici – Documentazione

Esempio

Gli esempi in questa pagina vengono da una richiesta di esempio per Hetzner Online GmbH, Ansbach HRB 6089. Se la sua iscrizione cambia, la tua richiesta restituisce valori diversi.

curl -G "https://handelsregister.ai/api/v1/fetch-organization" \
  -H "x-api-key: LA_TUA_CHIAVE_API" \
  --data-urlencode 'q=Hetzner Online GmbH'

import requests

response = requests.get(
    "https://handelsregister.ai/api/v1/fetch-organization",
    headers={"x-api-key": "LA_TUA_CHIAVE_API"},
    params={
        "q": "Hetzner Online GmbH",
    },
)
data = response.json()

const url = new URL("https://handelsregister.ai/api/v1/fetch-organization");
url.searchParams.append("q", "Hetzner Online GmbH");

const response = await fetch(url, {
  headers: { "x-api-key": "LA_TUA_CHIAVE_API" },
});
const data = await response.json();

1{2  "entity_id": "94eb910fef13f94585c48c263fa446d4",3  "name": "Hetzner Online GmbH",4  "status": "ACTIVE",5  "legal_form": "GmbH",6  "registration": {7    "court": "Ansbach",8    "register_type": "HRB",9    "register_number": "6089"10  },11  "keywords": [12    "Dedicated Server",13    "Cloud Hosting",14    "Webhosting",15    "Colocation",16    "Object Storage",17    "Domainregistrierung",18    "SSL-Zertifikate",19    "Web-Hosting-Unternehmen"20  ],21  "products_and_services": [22    "Dedizierte Root-Server (Dedicated Servers)",23    "Cloud-Server und virtuelle Server",24    "Managed Server",25    "Webhosting (Shared Hosting)",26    "Colocation Rack / Rechenzentrumsflächen",27    "Storage Box / Object Storage / Storage Share",28    "Domain-Registrierung",29    "SSL-Zertifikate",30    "Load Balancer",31    "DNS Console",32    "Registration Robot",33    "Custom Solutions"34  ],35  "industry_classification": {36    "WZ2008": [37      {38        "code": "62.01.0",39        "label": "Erbringung von Dienstleistungen der Informationstechnologie"40      },41      {42        "code": "63.11.0",43        "label": "Datenverarbeitung, Hosting und damit verbundene Tätigkeiten"44      },45      {46        "code": "61.90.0",47        "label": "Telekommunikation, sonstige"48      }49    ],50    "WZ2025": [51      {52        "code": "62.20.1",53        "label": "Erbringung von Beratungsleistungen auf dem Gebiet der Informationstechnologie"54      },55      {56        "code": "46.50.1",57        "label": "Großhandel mit Datenverarbeitungsgeräten, peripheren Geräten und Software"58      },59      {60        "code": "62.90.0",61        "label": "Erbringung von sonstigen Dienstleistungen der Informationstechnologie"62      }63    ]64  },65  "contact_data": {66    "website": "https://www.hetzner.com/",67    "phone_number": "09831 5050",68    "email": "[email protected]"69  },70  "address": {71    "house_number": "25",72    "street": "Industriestraße",73    "postal_code": "91710",74    "city": "Gunzenhausen",75    "county": "Weißenburg-Gunzenhausen",76    "state": "Bayern",77    "country": "DEU",78    "coordinates": {79      "latitude": 49.12483,80      "longitude": 10.7805281    }82  },83  "seat": {84    "city": "Gunzenhausen"85  },86  "registration_date": null,87  "representation_scheme": {88    "current": [89      "Ist nur ein Geschäftsführer bestellt, so vertritt er die Gesellschaft allein. Sind mehrere Geschäftsführer bestellt, so wird die Gesellschaft durch zwei Geschäftsführer oder durch einen Geschäftsführer gemeinsam mit einem Prokuristen vertreten."90    ],91    "history": [92      {93        "value": [94          "Ist nur ein Vorstandsmitglied bestellt, so vertritt es die Gesellschaft allein. Sind mehrere Vorstandsmitglieder bestellt, so wird die Gesellschaft durch zwei Vorstandsmitglieder oder durch ein Vorstandsmitglied gemeinsam mit einem Prokuristen vertreten."95        ],96        "effective_from": "2002-10-15",97        "effective_to": "2015-07-28"98      },99      {100        "value": [101          "Ist nur ein Geschäftsführer bestellt, so vertritt er die Gesellschaft allein. Sind mehrere Geschäftsführer bestellt, so wird die Gesellschaft durch zwei Geschäftsführer oder durch einen Geschäftsführer gemeinsam mit einem Prokuristen vertreten."102        ],103        "effective_from": "2015-07-28",104        "effective_to": null105      }106    ]107  },108  "capital": {109    "current": {110      "amount": 50000,111      "currency": "EUR",112      "kind": "STAMMKAPITAL"113    },114    "history": [115      {116        "value": {117          "amount": 50000,118          "currency": "EUR",119          "kind": "GRUNDKAPITAL"120        },121        "effective_from": "2002-10-15",122        "effective_to": null123      }124    ]125  },126  "purpose": "Die Durchführung von Internet- und Netzwerkdienstleistungen, das Erstellen und Vertreiben von Software, der Handel mit Hard- und Software, der Betrieb einer Werbeagentur,darüber hinaus der Im- und Export von Waren aller Art, soweit sie keiner Einfuhr- oder Ausfuhrbeschränkung unterliegen und soweit keine Genehmigungen erforderlich sind.",127  "meta": {128    "request_credit_cost": 5,129    "credits_remaining": 145130  }131}

200 · Risposta di esempio: i dati di base di Hetzner Online GmbH, Ansbach HRB 6089

Nome e forma giuridica

Nome, forma giuridica e stato descrivono l’azienda, l’entity_id la identifica. Salva l’entity_id se vuoi recuperare o monitorare di nuovo un’azienda in seguito, o collegarla ai tuoi dati.

Campo
Campo	Significato	Esempio	Disponibilità
entity_idstring	L’ID dell’azienda su handelsregister.ai. Salvalo come chiave nei tuoi dati. Nel parametro q corrisponde esattamente a questa azienda.Dati di base	`"94eb910fef13f94585c48c263fa446d4"`	sempre
namestring	Nome dell’azienda come compare nel registro, con il suffisso della forma giuridica.	`"Hetzner Online GmbH"`	come sopra
legal_formstring	Forma giuridica, di solito come la comune abbreviazione tedesca. Confronta senza distinguere maiuscole e minuscole, perché la grafia può variare leggermente, ad esempio oHG. Con la Modalità AI può comparire la forma completa. La lista mostra i valori comuni; ce ne sono altri.Valori: `GmbH` Gesellschaft mit beschränkter Haftung (società a responsabilità limitata), `UG (haftungsbeschränkt)` Unternehmergesellschaft (mini GmbH), `AG` Aktiengesellschaft (società per azioni), `SE` Societas Europaea (società europea), `KGaA` Kommanditgesellschaft auf Aktien (società in accomandita per azioni), `GmbH & Co. KG` KG con una GmbH come socia accomandataria, `KG` Kommanditgesellschaft (società in accomandita semplice), `OHG` Offene Handelsgesellschaft (società in nome collettivo), `e.K.` eingetragener Kaufmann (imprenditore individuale iscritto), `eG` eingetragene Genossenschaft (cooperativa iscritta), `PartG` Partnerschaftsgesellschaft (società tra professionisti), anche a responsabilità professionale limitata, `e.V.` eingetragener Verein (associazione iscritta), `eGbR` eingetragene Gesellschaft bürgerlichen Rechts (società di diritto civile iscritta)	`"GmbH"`	come sopra
statusstring	Stato dell’azienda nel registro. Sono possibili altri valori; tratta i valori sconosciuti come “non attiva”.Valori: `ACTIVE` attiva, `INSOLVENT` in procedura di insolvenza, `DISSOLVED` sciolta, in liquidazione, `TERMINATED` cancellata dal registro	`"ACTIVE"`	come sopra

Iscrizione nel registro

Tribunale del registro, tipo di registro e numero di registro identificano un’azienda. Li scriviamo insieme, nel nostro esempio come “Ansbach HRB 6089”. Puoi passarli in questa forma anche nel parametro q.

Campo
Campo	Significato	Esempio	Disponibilità
registrationobject\|null	L’iscrizione nel registro dell’azienda.Vuoto se la Modalità AI conosce un’azienda solo da fonti web; il suo entity_id inizia allora con AI_TMP_Dati di base	–	sempre
registration.courtstring	Tribunale del registro come nome di luogo, senza “Amtsgericht” (tribunale locale), ad esempio Ansbach o Charlottenburg (Berlin).	`"Ansbach"`	come sopra
registration.register_typestring	Tipo di registro, cioè il registro e, per l’Handelsregister, la sua sezione.Valori: `HRB` Handelsregister sezione B: GmbH, UG, AG, SE, KGaA, `HRA` Handelsregister sezione A: e.K., OHG, KG, GmbH & Co. KG, `GnR` Genossenschaftsregister (registro delle cooperative), `PR` Partnerschaftsregister (registro delle società tra professionisti), `VR` Vereinsregister (registro delle associazioni), `GsR` Gesellschaftsregister (registro delle società) per la eGbR	`"HRB"`	come sopra
registration.register_numberstring	Numero di registro come testo. Univoco solo insieme a tribunale del registro e tipo di registro.	`"6089"`	come sopra
registration_datestring\|null	Data di iscrizione nel registro, come timestamp ISO 8601.Vuoto se la data non è registrata	`"2013-03-18T00:00:00+00:00"`	quasi sempre: GmbH, UG, AG, SE, KGaA, KG, OHG, eG, PartG raramente: GmbH & Co. KG, e.K.

Un numero di registro è univoco solo insieme al suo tribunale del registro. Molti tribunali possono avere lo stesso numero.

Indirizzo e sede legale

address è l’indirizzo aziendale, seat la sede legale (Sitz) nel registro. I due possono differire, ad esempio quando un’azienda è iscritta a Monaco e lavora a Gauting.

Campo
Campo	Significato	Esempio	Disponibilità
addressobject	Indirizzo aziendale dell’azienda.Dati di base	–	sempre
address.streetstring\|null	Via senza numero civico.Vuoto se l’indirizzo consiste solo della città	`"Industriestraße"`	quasi sempre
address.house_numberstring\|null	Numero civico come testo, anche con un suffisso come “6 a”.Vuoto se l’indirizzo non ha numero civico	`"25"`	come sopra
address.postal_codestring\|null	Codice postale come testo, così gli zeri iniziali restano.Vuoto se l’indirizzo consiste solo della città	`"91710"`	come sopra
address.citystring	Città dell’indirizzo aziendale.	`"Gunzenhausen"`	sempre
address.countystring	Circondario (Landkreis) o città extracircondariale. Manca come chiave in alcuni indirizzi.	`"Weißenburg-Gunzenhausen"`	quasi sempre
address.statestring	Land federale (Bundesland). Manca come chiave in alcuni indirizzi.	`"Bayern"`	come sopra
address.countrystring	Paese come codice ISO 3166 a tre lettere, ad esempio DEU. Manca come chiave in alcuni indirizzi.	`"DEU"`	come sopra
address.coordinatesobject	Coordinate geografiche dell’indirizzo aziendale, per mappe e ricerche per raggio.	–	come sopra
address.coordinates.latitudenumber\|null	Latitudine in gradi decimali.Vuoto se l’indirizzo non è stato geocodificato	`49.12483`	come sopra
address.coordinates.longitudenumber\|null	Longitudine in gradi decimali.Vuoto se l’indirizzo non è stato geocodificato	`10.78052`	come sopra
seatobject	La sede legale (Sitz) dell’azienda nel registro.	–	sempre
seat.citystring	Città della sede legale. Può differire dall’indirizzo aziendale.	`"Gunzenhausen"`	come sopra

Oggetto sociale e settore

L’oggetto sociale (Unternehmensgegenstand) è nel registro per GmbH, UG, AG, SE, KGaA, eG e PartG. GmbH & Co. KG, KG, OHG e imprenditori individuali (e.K.) non iscrivono un oggetto sociale. Settore, parole chiave e prodotti e servizi esistono per ogni forma giuridica.

Campo
Campo	Significato	Esempio	Disponibilità
purposestring\|null	Oggetto sociale come compare nel registro, in tedesco. Con la Modalità AI è un breve riassunto dell’attività, anche per forme giuridiche senza oggetto sociale iscritto.Vuoto se la forma giuridica non iscrive un oggetto sociale, ad esempio KG, OHG ed e.K.Dati di base	`"Die Durchführung von Internet- und Netzwerkdienstleistun…"`	sempre: GmbH, UG, AG, SE, KGaA, eG, PartG mai: GmbH & Co. KG, KG, OHG, e.K.
industry_classificationobject	Settore secondo la classificazione tedesca delle attività economiche (WZ), in due versioni.	–	sempre
industry_classification.WZ2025array	Codici di settore secondo WZ 2025, la versione attuale. Anche il filtro di settore della ricerca usa questi codici.Vuoto se non è stato possibile assegnare un settore	–	quasi sempre
industry_classification.WZ2025[].codestring	Codice WZ a cinque cifre, ad esempio 62.20.1.	`"62.20.1"`	come sopra
industry_classification.WZ2025[].labelstring	Nome dell’attività economica, in tedesco.	`"Erbringung von Beratungsleistungen auf dem Gebiet der In…"`	come sopra
industry_classification.WZ2008array	Codici di settore secondo la versione precedente WZ 2008, per i sistemi che la usano ancora.Vuoto se non esiste un’assegnazione WZ 2008	–	in parte
industry_classification.WZ2008[].codestring	Codice WZ a cinque cifre secondo WZ 2008.	`"62.01.0"`	come sopra
industry_classification.WZ2008[].labelstring	Nome dell’attività economica, in tedesco.	`"Erbringung von Dienstleistungen der Informationstechnolo…"`	come sopra
keywordsarray	Parole chiave sull’attività dell’azienda, raccolte da fonti web pubbliche. Ampliate con la Modalità AI.Vuoto se l’azienda è poco presente sul web	–	come sopra
products_and_servicesarray	Prodotti e servizi dell’azienda come lista, raccolti da fonti web pubbliche. Ampliati con la Modalità AI.Vuoto se l’azienda è poco presente sul web	–	come sopra

Con la Modalità AI, purpose contiene un breve riassunto dell’attività invece del testo del registro. La Modalità AI aggiunge dal web parole chiave e prodotti e servizi.

Capitale

Le società di capitali iscrivono il loro capitale (Stammkapital o Grundkapital), ogni modifica con la sua data. current è l’importo in vigore, history le modifiche in ordine cronologico. Società di persone e imprenditori individuali non hanno un capitale fisso; lì current è null e history è vuoto.

Campo
Campo	Significato	Esempio	Disponibilità
capitalobject	Capitale iscritto con il suo storico.Dati di base	–	sempre
capital.currentobject\|null	L’importo del capitale in vigore.Vuoto se la forma giuridica non iscrive un capitale fisso, ad esempio KG, OHG, e.K. e PartG	–	sempre: GmbH, UG, AG, SE, KGaA raramente: eG mai: GmbH & Co. KG, KG, OHG, e.K., PartG
capital.current.amountnumber	Importo come numero, nella valuta di currency.	`50000`	come sopra
capital.current.currencystring	Valuta come codice ISO 4217, quasi sempre EUR.	`"EUR"`	come sopra
capital.current.kindstring	Tipo di capitale. Sono possibili altri valori.Valori: `STAMMKAPITAL` Stammkapital (capitale sociale) di una GmbH o UG, `GRUNDKAPITAL` Grundkapital (capitale azionario) di una AG, SE o KGaA, `LIABILITY_SUM` Haftsumme (importo di responsabilità), ad esempio di una cooperativa, `CONDITIONAL` capitale condizionato di una AG, in iscrizioni precedenti	`"STAMMKAPITAL"`	come sopra
capital.historyarray	Tutti gli importi iscritti in ordine cronologico, compreso quello in vigore.	–	come sopra
capital.history[].valueobject	L’importo con amount, currency e kind, strutturato come current.	–	come sopra
capital.history[].value.change_amountobject	Importo della modifica secondo l’iscrizione nel registro, con amount e currency. Se il capitale è stato aumentato o ridotto risulta dal confronto con l’importo precedente.	–	in parte: AG, SE, KGaA raramente: GmbH, UG, eG mai: GmbH & Co. KG, KG, OHG, e.K., PartG
capital.history[].effective_fromstring\|null	Valido da questo giorno, nel formato YYYY-MM-DD.	`"2002-10-15"`	sempre: GmbH, UG, AG, SE, KGaA raramente: eG mai: GmbH & Co. KG, KG, OHG, e.K., PartG
capital.history[].effective_tostring\|null	Valido fino a questo giorno.Vuoto se l’importo è ancora in vigore	`"2005-02-28"`	come sopra

Leggiamo automaticamente lo storico del capitale dalle iscrizioni nel registro. Usiamo la tecnologia più recente e investiamo molto nella qualità; singoli errori restano comunque possibili.

Regole di rappresentanza

Le regole di rappresentanza (Vertretungsregelung) stabiliscono chi può agire per l’azienda. La risposta le contiene parola per parola dal registro, in tedesco. Nella nostra richiesta di esempio per Hetzner Online GmbH, lo storico nominava il consiglio di gestione (Vorstand) fino al 28 luglio 2015, poi gli amministratori. Il potere delle singole persone è in Potere di rappresentanza.

Campo
Campo	Significato	Esempio	Disponibilità
representation_schemeobject	Regole generali di rappresentanza dell’azienda con il loro storico.Dati di base	–	sempre: GmbH, UG, GmbH & Co. KG, KG, OHG, eG, PartG quasi sempre: AG, SE, KGaA, e.K.
representation_scheme.currentarray\|null	Le regole in vigore come lista di paragrafi di testo, parola per parola dal registro.Vuoto se non sono iscritte regole	–	come sopra
representation_scheme.historyarray	Tutte le versioni iscritte con la loro validità, compresa quella in vigore.	–	come sopra
representation_scheme.history[].valuearray	Il testo di questa versione come lista di paragrafi.	–	come sopra
representation_scheme.history[].effective_fromstring\|null	Valido da questo giorno, nel formato YYYY-MM-DD.	`"2002-10-15"`	come sopra
representation_scheme.history[].effective_tostring\|null	Valido fino a questo giorno.Vuoto se la versione è ancora in vigore	`"2015-07-28"`	come sopra

Con Tempo reale history è vuoto. La versione in vigore è in current.

Contatti e web

I contatti non sono nel registro. Li raccogliamo dal sito web dell’azienda. Se esistono dipende quindi da ciò che l’azienda pubblica sul web.

Campo
Campo	Significato	Esempio	Disponibilità
contact_dataobject	Contatti dal sito web dell’azienda.Dati di base	–	sempre
contact_data.websitestring\|null	Indirizzo del sito web.Vuoto se non è stato trovato alcun sito web	`"https://www.hetzner.com/"`	in parte
contact_data.phone_numberstring\|null	Numero di telefono come lo pubblica l’azienda. Il formato non è normalizzato.Vuoto se non è stato trovato alcun numero	`"09831 5050"`	come sopra
contact_data.emailstring\|null	Indirizzo email generale dell’azienda.Vuoto se non è stato trovato alcun indirizzo	`"[email protected]"`	come sopra
website_contentstring\|null	Il testo del sito web come Markdown, ad esempio per analisi proprie o per un modello linguistico. Arriva con la feature website_content, solo insieme alla Modalità AI e senza costi aggiuntivi.Vuoto se non è stato trovato alcun sito web`website_content`	`"Dedicated Servers, Cloud & Hosting from Germany \| Hetzne…"`	come sopra

Tempo reale

Con realtime_mode=handelsregister-default l’API interroga anche l’Handelsregister in diretta. La risposta contiene allora le persone attualmente iscritte e _realtime_mode con l’esito della query. Tempo reale viene addebitato solo se la query riesce, ma allora indipendentemente da ciò che restituisce.

Campo
Campo	Significato	Esempio	Disponibilità
_realtime_modeobject	Esito della query in Tempo reale. Nella risposta solo se hai richiesto realtime_mode.Dati di base	–	sempre
_realtime_mode.modestring	La modalità richiesta, handelsregister-default.	`"handelsregister-default"`	come sopra
_realtime_mode.statusstring	Se la query in diretta è riuscita. Con qualsiasi altro valore la risposta contiene i dati salvati e Tempo reale non viene addebitato.Valori: `success` query in diretta riuscita, i dati arrivano direttamente dall’Handelsregister	`"success"`	come sopra

Una query in Tempo reale dura di più, quindi imposta il timeout del tuo client ad almeno 120 secondi. Se la query in diretta fallisce, l’API restituisce i dati salvati. _realtime_mode.status allora non è success e Tempo reale non viene addebitato. Se la richiesta dura troppo, ricevi 408 senza costi; riprova più tardi.

Avanti

fetch-organization L’endpoint che restituisce i dati anagrafici, con parametri ed errori. Persone e rappresentanza Amministratori, Prokura e soci con i loro poteri. Concetti di base Come leggere current e history, null e liste vuote. Disponibilità dei dati Cosa contiene il registro per forma giuridica e da dove vengono i dati.