Dados cadastrais – Documentação

Exemplo

Os exemplos desta página vêm de uma requisição de exemplo para a Hetzner Online GmbH, Ansbach HRB 6089. Se o registro dela mudar, sua própria requisição retornará valores diferentes.

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

import requests

response = requests.get(
    "https://handelsregister.ai/api/v1/fetch-organization",
    headers={"x-api-key": "SUA_CHAVE_DE_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": "SUA_CHAVE_DE_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 · Resposta de exemplo: os dados básicos da Hetzner Online GmbH, Ansbach HRB 6089

Nome e forma jurídica

Nome, forma jurídica e situação descrevem a empresa; o entity_id a identifica. Guarde o entity_id se quiser obter ou monitorar uma empresa de novo mais tarde, ou ligá-la aos seus próprios dados.

Campo
Campo	Significado	Exemplo	Disponibilidade
entity_idstring	O ID da empresa na handelsregister.ai. Guarde-o como chave nos seus dados. No parâmetro q, ele corresponde exatamente a esta empresa.Dados básicos	`"94eb910fef13f94585c48c263fa446d4"`	sempre
namestring	Nome da empresa como consta no registro, com o sufixo da forma jurídica.	`"Hetzner Online GmbH"`	como acima
legal_formstring	Forma jurídica, geralmente como a abreviação alemã usual. Compare sem diferenciar maiúsculas e minúsculas, porque a grafia pode variar um pouco, por exemplo oHG. Com o Modo IA, pode aparecer a forma por extenso. A lista mostra valores comuns; existem outros.Valores: `GmbH` Gesellschaft mit beschränkter Haftung (sociedade de responsabilidade limitada), `UG (haftungsbeschränkt)` Unternehmergesellschaft (mini-GmbH), `AG` Aktiengesellschaft (sociedade anônima), `SE` Societas Europaea (sociedade europeia), `KGaA` Kommanditgesellschaft auf Aktien (sociedade em comandita por ações), `GmbH & Co. KG` KG com uma GmbH como sócia de responsabilidade ilimitada, `KG` Kommanditgesellschaft (sociedade em comandita simples), `OHG` Offene Handelsgesellschaft (sociedade em nome coletivo), `e.K.` eingetragener Kaufmann (empresário individual registrado), `eG` eingetragene Genossenschaft (cooperativa registrada), `PartG` Partnerschaftsgesellschaft (sociedade de profissionais liberais), também com responsabilidade profissional limitada, `e.V.` eingetragener Verein (associação registrada), `eGbR` eingetragene Gesellschaft bürgerlichen Rechts (sociedade civil registrada)	`"GmbH"`	como acima
statusstring	Situação da empresa no registro. Outros valores são possíveis; trate valores desconhecidos como “não ativa”.Valores: `ACTIVE` ativa, `INSOLVENT` em processo de insolvência, `DISSOLVED` dissolvida, em liquidação, `TERMINATED` cancelada no registro	`"ACTIVE"`	como acima

Registro

Tribunal de registro, tipo de registro e número de registro identificam uma empresa. Nós os escrevemos juntos, no nosso exemplo como “Ansbach HRB 6089”. Você também pode passá-los nessa forma no parâmetro q.

Campo
Campo	Significado	Exemplo	Disponibilidade
registrationobject\|null	O registro da empresa.Vazio quando o Modo IA conhece uma empresa só por fontes da web; o entity_id dela começa então com AI_TMP_Dados básicos	–	sempre
registration.courtstring	Tribunal de registro como nome de lugar, sem “Amtsgericht” (tribunal local), por exemplo Ansbach ou Charlottenburg (Berlin).	`"Ansbach"`	como acima
registration.register_typestring	Tipo de registro, ou seja, o registro e, no caso do Handelsregister, a seção.Valores: `HRB` Handelsregister seção B: GmbH, UG, AG, SE, KGaA, `HRA` Handelsregister seção A: e.K., OHG, KG, GmbH & Co. KG, `GnR` Genossenschaftsregister (registro de cooperativas), `PR` Partnerschaftsregister (registro de sociedades de profissionais liberais), `VR` Vereinsregister (registro de associações), `GsR` Gesellschaftsregister (registro de sociedades) para a eGbR	`"HRB"`	como acima
registration.register_numberstring	Número de registro como texto. Único só junto com tribunal de registro e tipo de registro.	`"6089"`	como acima
registration_datestring\|null	Data de inscrição no registro, como timestamp ISO 8601.Vazio quando a data não está registrada	`"2013-03-18T00:00:00+00:00"`	geralmente: GmbH, UG, AG, SE, KGaA, KG, OHG, eG, PartG raramente: GmbH & Co. KG, e.K.

Um número de registro só é único junto com o seu tribunal de registro. Muitos tribunais podem ter o mesmo número.

Endereço e sede

address é o endereço comercial, seat a sede registrada (Sitz) no registro. Os dois podem diferir, por exemplo quando uma empresa está registrada em Munique e trabalha em Gauting.

Campo
Campo	Significado	Exemplo	Disponibilidade
addressobject	Endereço comercial da empresa.Dados básicos	–	sempre
address.streetstring\|null	Rua sem número.Vazio quando o endereço consiste só na cidade	`"Industriestraße"`	geralmente
address.house_numberstring\|null	Número como texto, também com complemento como “6 a”.Vazio quando o endereço não tem número	`"25"`	como acima
address.postal_codestring\|null	Código postal como texto, para preservar zeros à esquerda.Vazio quando o endereço consiste só na cidade	`"91710"`	como acima
address.citystring	Cidade do endereço comercial.	`"Gunzenhausen"`	sempre
address.countystring	Distrito (Landkreis) ou cidade independente de distrito. A chave falta em alguns endereços.	`"Weißenburg-Gunzenhausen"`	geralmente
address.statestring	Estado federal (Bundesland). A chave falta em alguns endereços.	`"Bayern"`	como acima
address.countrystring	País como código ISO 3166 de três letras, por exemplo DEU. A chave falta em alguns endereços.	`"DEU"`	como acima
address.coordinatesobject	Coordenadas geográficas do endereço comercial, para mapas e buscas por raio.	–	como acima
address.coordinates.latitudenumber\|null	Latitude em graus decimais.Vazio quando o endereço não pôde ser geocodificado	`49.12483`	como acima
address.coordinates.longitudenumber\|null	Longitude em graus decimais.Vazio quando o endereço não pôde ser geocodificado	`10.78052`	como acima
seatobject	A sede registrada da empresa (Sitz) no registro.	–	sempre
seat.citystring	Cidade da sede registrada. Pode diferir do endereço comercial.	`"Gunzenhausen"`	como acima

Objeto social e setor

O objeto social (Unternehmensgegenstand) consta no registro para GmbH, UG, AG, SE, KGaA, eG e PartG. GmbH & Co. KG, KG, OHG e empresários individuais (e.K.) não registram objeto social. Setor, palavras-chave e produtos e serviços existem para todas as formas jurídicas.

Campo
Campo	Significado	Exemplo	Disponibilidade
purposestring\|null	Objeto social como consta no registro, em alemão. Com o Modo IA, é um breve resumo da atividade, também para formas jurídicas sem objeto social registrado.Vazio quando a forma jurídica não registra objeto social, por exemplo KG, OHG e e.K.Dados básicos	`"Die Durchführung von Internet- und Netzwerkdienstleistun…"`	sempre: GmbH, UG, AG, SE, KGaA, eG, PartG nunca: GmbH & Co. KG, KG, OHG, e.K.
industry_classificationobject	Setor segundo a classificação alemã de atividades econômicas (WZ), em duas versões.	–	sempre
industry_classification.WZ2025array	Códigos de setor segundo a WZ 2025, a versão atual. O filtro de setor da busca também usa esses códigos.Vazio quando nenhum setor pôde ser atribuído	–	geralmente
industry_classification.WZ2025[].codestring	Código WZ de cinco dígitos, por exemplo 62.20.1.	`"62.20.1"`	como acima
industry_classification.WZ2025[].labelstring	Nome da atividade econômica, em alemão.	`"Erbringung von Beratungsleistungen auf dem Gebiet der In…"`	como acima
industry_classification.WZ2008array	Códigos de setor segundo a versão anterior WZ 2008, para sistemas que ainda a usam.Vazio quando não existe atribuição na WZ 2008	–	em parte
industry_classification.WZ2008[].codestring	Código WZ de cinco dígitos segundo a WZ 2008.	`"62.01.0"`	como acima
industry_classification.WZ2008[].labelstring	Nome da atividade econômica, em alemão.	`"Erbringung von Dienstleistungen der Informationstechnolo…"`	como acima
keywordsarray	Palavras-chave sobre a atividade da empresa, reunidas de fontes públicas da web. Ampliadas com o Modo IA.Vazio quando a empresa tem pouca presença na web	–	como acima
products_and_servicesarray	Os produtos e serviços da empresa como lista, reunidos de fontes públicas da web. Ampliados com o Modo IA.Vazio quando a empresa tem pouca presença na web	–	como acima

Com o Modo IA, purpose contém um breve resumo da atividade em vez do texto do registro. O Modo IA acrescenta palavras-chave e produtos e serviços da web.

Capital

Sociedades de capital registram seu capital social (Stammkapital ou Grundkapital), cada alteração com a data. current é o valor em vigor, history as alterações em ordem cronológica. Sociedades de pessoas e empresários individuais não têm capital fixo; nesse caso current é null e history fica vazio.

Campo
Campo	Significado	Exemplo	Disponibilidade
capitalobject	Capital registrado com seu histórico.Dados básicos	–	sempre
capital.currentobject\|null	O valor de capital em vigor.Vazio quando a forma jurídica não registra capital fixo, por exemplo KG, OHG, e.K. e PartG	–	sempre: GmbH, UG, AG, SE, KGaA raramente: eG nunca: GmbH & Co. KG, KG, OHG, e.K., PartG
capital.current.amountnumber	Valor como número, na moeda de currency.	`50000`	como acima
capital.current.currencystring	Moeda como código ISO 4217, quase sempre EUR.	`"EUR"`	como acima
capital.current.kindstring	Tipo de capital. Outros valores são possíveis.Valores: `STAMMKAPITAL` Stammkapital (capital social) de uma GmbH ou UG, `GRUNDKAPITAL` Grundkapital (capital social em ações) de uma AG, SE ou KGaA, `LIABILITY_SUM` Haftsumme (valor de responsabilidade), por exemplo de uma cooperativa, `CONDITIONAL` capital condicional de uma AG, em registros mais antigos	`"STAMMKAPITAL"`	como acima
capital.historyarray	Todos os valores registrados em ordem cronológica, incluindo o que está em vigor.	–	como acima
capital.history[].valueobject	O valor com amount, currency e kind, estruturado como current.	–	como acima
capital.history[].value.change_amountobject	Valor da alteração segundo o registro, com amount e currency. Se o capital foi aumentado ou reduzido, resulta da comparação com o valor anterior.	–	em parte: AG, SE, KGaA raramente: GmbH, UG, eG nunca: GmbH & Co. KG, KG, OHG, e.K., PartG
capital.history[].effective_fromstring\|null	Válido a partir deste dia, no formato YYYY-MM-DD.	`"2002-10-15"`	sempre: GmbH, UG, AG, SE, KGaA raramente: eG nunca: GmbH & Co. KG, KG, OHG, e.K., PartG
capital.history[].effective_tostring\|null	Válido até este dia.Vazio quando o valor ainda está em vigor	`"2005-02-28"`	como acima

Lemos o histórico do capital automaticamente dos registros. Usamos a tecnologia mais recente para isso e investimos muito em qualidade; ainda assim, erros pontuais são possíveis.

Regras de representação

As regras de representação (Vertretungsregelung) definem quem pode agir pela empresa. A resposta as traz palavra por palavra do registro, em alemão. Na nossa requisição de exemplo para a Hetzner Online GmbH, o histórico mencionava a diretoria executiva (Vorstand) até 28 de julho de 2015 e, depois, os diretores. O poder de pessoas específicas está em Poder de representação.

Campo
Campo	Significado	Exemplo	Disponibilidade
representation_schemeobject	Regras gerais de representação da empresa com seu histórico.Dados básicos	–	sempre: GmbH, UG, GmbH & Co. KG, KG, OHG, eG, PartG geralmente: AG, SE, KGaA, e.K.
representation_scheme.currentarray\|null	As regras em vigor como lista de parágrafos de texto, palavra por palavra do registro.Vazio quando nenhuma regra está registrada	–	como acima
representation_scheme.historyarray	Todas as versões registradas com sua validade, incluindo a que está em vigor.	–	como acima
representation_scheme.history[].valuearray	O texto desta versão como lista de parágrafos.	–	como acima
representation_scheme.history[].effective_fromstring\|null	Válido a partir deste dia, no formato YYYY-MM-DD.	`"2002-10-15"`	como acima
representation_scheme.history[].effective_tostring\|null	Válido até este dia.Vazio quando a versão ainda está em vigor	`"2015-07-28"`	como acima

Com Tempo real, history fica vazio. A versão em vigor está em current.

Contato e web

Dados de contato não constam no registro. Nós os reunimos a partir do site da empresa. Se existem, depende do que a empresa publica na web.

Campo
Campo	Significado	Exemplo	Disponibilidade
contact_dataobject	Dados de contato do site da empresa.Dados básicos	–	sempre
contact_data.websitestring\|null	Endereço do site.Vazio quando nenhum site foi encontrado	`"https://www.hetzner.com/"`	em parte
contact_data.phone_numberstring\|null	Número de telefone como a empresa o publica. O formato não é normalizado.Vazio quando nenhum número foi encontrado	`"09831 5050"`	como acima
contact_data.emailstring\|null	Endereço de e-mail geral da empresa.Vazio quando nenhum endereço foi encontrado	`"[email protected]"`	como acima
website_contentstring\|null	O texto do site como Markdown, por exemplo para sua própria análise ou um modelo de linguagem. Vem com o recurso website_content, só junto com o Modo IA e sem custo adicional.Vazio quando nenhum site foi encontrado`website_content`	`"Dedicated Servers, Cloud & Hosting from Germany \| Hetzne…"`	como acima

Tempo real

Com realtime_mode=handelsregister-default, a API também consulta o Handelsregister ao vivo. A resposta então contém as pessoas registradas no momento e _realtime_mode com o resultado da consulta. O Tempo real só é cobrado se a consulta for bem-sucedida, mas aí independentemente do que retornar.

Campo
Campo	Significado	Exemplo	Disponibilidade
_realtime_modeobject	Resultado da consulta em Tempo real. Só aparece na resposta se você solicitou realtime_mode.Dados básicos	–	sempre
_realtime_mode.modestring	O modo solicitado, handelsregister-default.	`"handelsregister-default"`	como acima
_realtime_mode.statusstring	Se a consulta ao vivo foi bem-sucedida. Com qualquer outro valor, a resposta contém os dados armazenados, e o Tempo real não é cobrado.Valores: `success` consulta ao vivo bem-sucedida, os dados vêm direto do Handelsregister	`"success"`	como acima

Uma consulta em Tempo real demora mais; por isso, configure o timeout do seu cliente para pelo menos 120 segundos. Se a consulta ao vivo falhar, a API retorna os dados armazenados. _realtime_mode.status então não é success, e o Tempo real não é cobrado. Se a requisição demorar demais, você recebe 408 sem custo; tente de novo mais tarde.

Próximos passos

fetch-organization O endpoint que retorna os dados cadastrais, com parâmetros e erros. Pessoas e representação Diretores, Prokura e sócios com seus poderes. Conceitos básicos Como ler current e history, null e listas vazias. Disponibilidade de dados O que o registro contém por forma jurídica e de onde vêm os dados.