Obter um perfil de empresa

fetch-organization encontra uma empresa pelo nome, tribunal de registro e número de registro, ou pelo entity_id. Normalmente você não precisa buscar antes.

Uma requisição basta para um perfil de empresa: fetch-organization encontra a empresa sozinho. Você a indica em q de uma de três formas. Normalmente você não precisa buscar antes.

Pelo nome

Escreva o nome da empresa com a forma jurídica em q, como consta no registro. Acrescentar a cidade ajuda quando várias empresas têm o mesmo nome. Maiúsculas e minúsculas não importam. Nossa requisição de exemplo busca a Hetzner Online GmbH, Ansbach HRB 6089, por nome e cidade.

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

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 Gunzenhausen",
    },
)
data = response.json()

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

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  "address": {12    "house_number": "25",13    "street": "Industriestraße",14    "postal_code": "91710",15    "city": "Gunzenhausen",16    "county": "Weißenburg-Gunzenhausen",17    "state": "Bayern",18    "country": "DEU",19    "coordinates": {20      "latitude": 49.12483,21      "longitude": 10.7805222    }23  },24  "meta": {25    "request_credit_cost": 5,26    "credits_remaining": 14527  }28}

200 · Resposta de exemplo para a Hetzner Online GmbH, encontrada por nome e cidade (trecho)

A resposta contém os dados básicos da empresa e custa 5 créditos. Para cada requisição seguinte, o principal de que você precisa é o entity_id.

Se várias empresas têm o mesmo nome, a API pode retornar outra diferente da que você queria ou responder com HTTP 404. Quando tem que ser exatamente esta empresa, pergunte com tribunal de registro e número de registro ou com o entity_id.

Se a API não encontra nenhuma empresa correspondente, responde com HTTP 404. Sem Modo IA, isso não custa nada. Parte do nome, como só “Hetzner”, muitas vezes não basta; use o nome completo, a cidade ou o número de registro.

Pelo tribunal de registro e número de registro

Tribunal de registro, tipo de registro e número de registro juntos identificam exatamente uma inscrição no Handelsregister (registro comercial). O tribunal de registro (Registergericht) é o tribunal local (Amtsgericht) que mantém o registro. Escreva as três partes em q, no exemplo Ansbach HRB 6089.

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

import requests

response = requests.get(
    "https://handelsregister.ai/api/v1/fetch-organization",
    headers={"x-api-key": "SUA_CHAVE_DE_API"},
    params={
        "q": "Ansbach HRB 6089",
    },
)
data = response.json()

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

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  "address": {12    "house_number": "25",13    "street": "Industriestraße",14    "postal_code": "91710",15    "city": "Gunzenhausen",16    "county": "Weißenburg-Gunzenhausen",17    "state": "Bayern",18    "country": "DEU",19    "coordinates": {20      "latitude": 49.12483,21      "longitude": 10.7805222    }23  },24  "meta": {25    "request_credit_cost": 5,26    "credits_remaining": 14527  }28}

200 · Resposta de exemplo: a mesma empresa, encontrada pelo número de registro (trecho)

A ordem fica a seu critério: HRB 6089 Ansbach funciona igualmente. Você não precisa acrescentar “Amtsgericht”. Sem o tribunal de registro, a API não encontra nenhuma empresa, porque muitos tribunais usam o mesmo número.

Pelo entity_id

Toda resposta contém o entity_id, um identificador de 32 caracteres da empresa. Guarde-o e use-o em cada requisição seguinte. Você precisa dele em q de fetch-organization, como company_id para documentos, em organization_ids para Signals e para um monitor.

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

import requests

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

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

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  "address": {12    "house_number": "25",13    "street": "Industriestraße",14    "postal_code": "91710",15    "city": "Gunzenhausen",16    "county": "Weißenburg-Gunzenhausen",17    "state": "Bayern",18    "country": "DEU",19    "coordinates": {20      "latitude": 49.12483,21      "longitude": 10.7805222    }23  },24  "meta": {25    "request_credit_cost": 5,26    "credits_remaining": 14527  }28}

200 · Resposta de exemplo: a mesma empresa, obtida pelo entity_id (trecho)

Com o entity_id não há confusão, e o seu sistema não precisa mais comparar nomes.

Adicionar recursos

Os dados básicos sempre vêm. Todo o resto você solicita como recurso na mesma requisição. Passe feature várias vezes ou escreva vários nomes, separados por vírgula, em features. O exemplo obtém a administração e os KPIs financeiros dos dois exercícios mais recentes.

curl -G "https://handelsregister.ai/api/v1/fetch-organization" \
  -H "x-api-key: SUA_CHAVE_DE_API" \
  --data-urlencode 'q=Ansbach HRB 6089' \
  --data-urlencode 'feature=related_persons' \
  --data-urlencode 'feature=financial_kpi' \
  --data-urlencode 'financial_years=2'

import requests

response = requests.get(
    "https://handelsregister.ai/api/v1/fetch-organization",
    headers={"x-api-key": "SUA_CHAVE_DE_API"},
    params={
        "q": "Ansbach HRB 6089",
        "feature": ["related_persons", "financial_kpi"],
        "financial_years": "2",
    },
)
data = response.json()

const url = new URL("https://handelsregister.ai/api/v1/fetch-organization");
url.searchParams.append("q", "Ansbach HRB 6089");
url.searchParams.append("feature", "related_persons");
url.searchParams.append("feature", "financial_kpi");
url.searchParams.append("financial_years", "2");

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  "related_persons": {5    "current": [6      {7        "entity_id": "ea3a1670232611a992727ed067216d07",8        "label": "MANAGING_DIRECTOR",9        "role": {10          "en": {11            "long": "Managing Director",12            "short": "MD"13          },14          "de": {15            "long": "Geschäftsführer",16            "short": "GF"17          }18        },19        "name": "Paul Musterwald",20        "start_date": "2019-01-04",21        "end_date": null,22        "birth_date": "1989-07-18",23        "name_parts": {24          "given": "Paul",25          "family": "Musterwald",26          "maiden": null,27          "canonical_name": "Musterwald, Paul",28          "previous_names": null29        },30        "location": {31          "home": {32            "city": "Exempelingen i. Bay."33          }34        },35        "organization_representation_scheme": {36          "current": [37            "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."38          ],39          "history": [40            {41              "value": [42                "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."43              ],44              "effective_from": "2002-10-15",45              "effective_to": "2015-07-28"46            },47            {48              "value": [49                "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."50              ],51              "effective_from": "2015-07-28",52              "effective_to": null53            }54          ]55        },56        "role_representation_scheme": {57          "current": [58            "einzelvertretungsberechtigt."59          ],60          "history": [61            {62              "value": [63                "einzelvertretungsberechtigt."64              ],65              "effective_from": "2019-01-04",66              "effective_to": null67            }68          ]69        }70      },71      {72        "entity_id": "dd7e94b41f78de4195cc70c6b0f732f3",73        "label": "MANAGING_DIRECTOR",74        "role": {75          "en": {76            "long": "Managing Director",77            "short": "MD"78          },79          "de": {80            "long": "Geschäftsführer",81            "short": "GF"82          }83        },84        "name": "Jan Musterhuber",85        "start_date": "2019-01-04",86        "end_date": null,87        "birth_date": "1955-11-06",88        "name_parts": {89          "given": "Jan",90          "family": "Musterhuber",91          "maiden": null,92          "canonical_name": "Musterhuber, Jan",93          "previous_names": null94        },95        "location": {96          "home": {97            "city": "Probeingen"98          }99        },100        "organization_representation_scheme": {101          "current": [102            "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."103          ],104          "history": [105            {106              "value": [107                "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."108              ],109              "effective_from": "2002-10-15",110              "effective_to": "2015-07-28"111            },112            {113              "value": [114                "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."115              ],116              "effective_from": "2015-07-28",117              "effective_to": null118            }119          ]120        },121        "role_representation_scheme": {122          "current": [123            "einzelvertretungsberechtigt."124          ],125          "history": [126            {127              "value": [128                "einzelvertretungsberechtigt."129              ],130              "effective_from": "2019-01-04",131              "effective_to": null132            }133          ]134        }135      },136      {137        "entity_id": "08ed5f967956831ca6588930fd2693ed",138        "label": "MANAGING_DIRECTOR",139        "role": {140          "en": {141            "long": "Managing Director",142            "short": "MD"143          },144          "de": {145            "long": "Geschäftsführer",146            "short": "GF"147          }148        },149        "name": "Max Felix Mustermann",150        "start_date": "2015-07-28",151        "end_date": null,152        "birth_date": "1976-01-15",153        "name_parts": {154          "given": "Max Felix",155          "family": "Mustermann",156          "maiden": null,157          "canonical_name": "Mustermann, Max Felix",158          "previous_names": null159        },160        "location": {161          "home": {162            "city": "Musterheim"163          }164        },165        "organization_representation_scheme": {166          "current": [167            "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."168          ],169          "history": [170            {171              "value": [172                "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."173              ],174              "effective_from": "2002-10-15",175              "effective_to": "2015-07-28"176            },177            {178              "value": [179                "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."180              ],181              "effective_from": "2015-07-28",182              "effective_to": null183            }184          ]185        },186        "role_representation_scheme": {187          "current": [188            "einzelvertretungsberechtigt; mit der Befugnis, im Namen der Gesellschaft mit sich im eigenen Namen oder als Vertreter eines Dritten Rechtsgeschäfte abzuschließen."189          ],190          "history": [191            {192              "value": [193                "einzelvertretungsberechtigt; mit der Befugnis, im Namen der Gesellschaft mit sich im eigenen Namen oder als Vertreter eines Dritten Rechtsgeschäfte abzuschließen."194              ],195              "effective_from": "2015-07-28",196              "effective_to": null197            }198          ]199        }200      }201    ],202    "past": [203      {204        "entity_id": "ea3a1670232611a992727ed067216d07",205        "label": "PROCURA",206        "role": {207          "en": {208            "long": "Procura",209            "short": "Procura"210          },211          "de": {212            "long": "Prokura",213            "short": "Prokura"214          }215        },216        "name": "Paul Musterwald",217        "start_date": "2015-07-28",218        "end_date": "2019-01-04",219        "birth_date": "1989-07-18",220        "name_parts": {221          "given": "Paul",222          "family": "Musterwald",223          "maiden": null,224          "canonical_name": "Musterwald, Paul",225          "previous_names": null226        },227        "location": {228          "home": {229            "city": "Exempelingen i. Bay."230          }231        },232        "organization_representation_scheme": {233          "latest": [234            "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."235          ],236          "history": [237            {238              "value": [239                "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."240              ],241              "effective_from": "2002-10-15",242              "effective_to": "2015-07-28"243            },244            {245              "value": [246                "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."247              ],248              "effective_from": "2015-07-28",249              "effective_to": null250            }251          ]252        },253        "role_representation_scheme": {254          "latest": [255            "Gesamtprokura gemeinsam mit einem anderen Prokuristen:"256          ],257          "history": [258            {259              "value": [260                "Gesamtprokura gemeinsam mit einem anderen Prokuristen:"261              ],262              "effective_from": "2015-07-28",263              "effective_to": "2019-01-04"264            }265          ]266        }267      },268      {269        "entity_id": "dd7e94b41f78de4195cc70c6b0f732f3",270        "label": "PROCURA",271        "role": {272          "en": {273            "long": "Procura",274            "short": "Procura"275          },276          "de": {277            "long": "Prokura",278            "short": "Prokura"279          }280        },281        "name": "Jan Musterhuber",282        "start_date": "2015-07-28",283        "end_date": "2019-01-04",284        "birth_date": "1955-11-06",285        "name_parts": {286          "given": "Jan",287          "family": "Musterhuber",288          "maiden": null,289          "canonical_name": "Musterhuber, Jan",290          "previous_names": null291        },292        "location": {293          "home": {294            "city": "Probeingen"295          }296        },297        "organization_representation_scheme": {298          "latest": [299            "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."300          ],301          "history": [302            {303              "value": [304                "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."305              ],306              "effective_from": "2002-10-15",307              "effective_to": "2015-07-28"308            },309            {310              "value": [311                "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."312              ],313              "effective_from": "2015-07-28",314              "effective_to": null315            }316          ]317        },318        "role_representation_scheme": {319          "latest": [320            "Gesamtprokura gemeinsam mit einem anderen Prokuristen:"321          ],322          "history": [323            {324              "value": [325                "Gesamtprokura gemeinsam mit einem anderen Prokuristen:"326              ],327              "effective_from": "2015-07-28",328              "effective_to": "2019-01-04"329            }330          ]331        }332      },333      {334        "entity_id": "08ed5f967956831ca6588930fd2693ed",335        "label": "BOARD",336        "role": {337          "en": {338            "long": "Board Member",339            "short": "Board"340          },341          "de": {342            "long": "Vorstandsmitglied",343            "short": "Vorstand"344          }345        },346        "name": "Max Felix Mustermann",347        "start_date": "2002-10-15",348        "end_date": "2015-07-28",349        "birth_date": "1976-01-15",350        "name_parts": {351          "given": "Max Felix",352          "family": "Mustermann",353          "maiden": null,354          "canonical_name": "Mustermann, Max Felix",355          "previous_names": null356        },357        "location": {358          "home": {359            "city": "Musterheim"360          }361        },362        "organization_representation_scheme": {363          "latest": [364            "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."365          ],366          "history": [367            {368              "value": [369                "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."370              ],371              "effective_from": "2002-10-15",372              "effective_to": "2015-07-28"373            },374            {375              "value": [376                "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."377              ],378              "effective_from": "2015-07-28",379              "effective_to": null380            }381          ]382        },383        "role_representation_scheme": {384          "latest": [385            "einzelvertretungsberechtigt; mit der Befugnis, im Namen der Gesellschaft mit sich im eigenen Namen oder als Vertreter eines Dritten Rechtsgeschäfte abzuschließen"386          ],387          "history": [388            {389              "value": [390                "einzelvertretungsberechtigt; mit der Befugnis, im Namen der Gesellschaft mit sich im eigenen Namen oder als Vertreter eines Dritten Rechtsgeschäfte abzuschließen"391              ],392              "effective_from": "2002-10-15",393              "effective_to": "2015-07-28"394            }395          ]396        }397      }398    ]399  },400  "financial_kpi": [401    {402      "year": 2023,403      "employees": 340,404      "company_size_by_employees": "large",405      "revenue_per_employee": 1582798.844,406      "net_income_per_employee": 485049.362,407      "assets_total": 397093655.67,408      "active_total": 397093655.67,409      "equity_total": 297695266.84,410      "liabilities_total": 28921831.79,411      "provisions_total": 55716527.94,412      "current_assets_total": 75902450.81,413      "inventory_total": 2605622.88,414      "receivables_total": 34451734.53,415      "securities_current_total": null,416      "cash_and_equivalents": 38845093.4,417      "ppe_total": 269497218.27,418      "intangible_assets": 18788946.41,419      "goodwill": null,420      "equity_ratio": 0.75,421      "debt_to_equity": 0.097,422      "debt_to_assets": 0.073,423      "cash_to_assets": 0.098,424      "cash_to_liabilities": 1.343,425      "receivables_to_assets": 0.087,426      "inventory_to_assets": 0.007,427      "ppe_to_assets": 0.679,428      "intangible_to_assets": 0.047,429      "goodwill_to_assets": null,430      "intangible_to_equity": 0.063,431      "tangible_equity": 278906320.43,432      "tangible_equity_ratio": 0.702,433      "operating_working_capital": 13370466.18,434      "net_working_capital_strict": 61276584.41,435      "net_working_capital_approx": 46980619.02,436      "interest_bearing_debt_strict": null,437      "interest_bearing_debt_broad": 14295965.39,438      "net_debt_narrow": null,439      "net_debt_broad": -24549128.01,440      "bank_debt": null,441      "bonds": null,442      "trade_payables": 14625866.4,443      "intragroup_receivables": 548819.99,444      "intragroup_payables": 2667666.2,445      "company_size_by_assets": "large",446      "revenue": 538151607.13,447      "material_expenses": 116509640.56,448      "material_expenses_goods": 1157010.5,449      "material_expenses_services": 115352630.06,450      "personnel_expenses": 37557386.2,451      "wages_salaries": 33140885.29,452      "social_expenses": 4416500.91,453      "pension_costs": null,454      "depreciation_amortization": 129958760.25,455      "other_operating_income": 1229615.57,456      "other_operating_expenses": 29380170.42,457      "selling_expenses": null,458      "admin_expenses": null,459      "gross_profit": null,460      "ebit": null,461      "ebt": null,462      "income_taxes": 67650181.5,463      "other_taxes": 94694.61,464      "net_income": 164916783.06,465      "ebitda": null,466      "gross_margin": null,467      "ebitda_margin": null,468      "ebit_margin": null,469      "net_margin": 0.306,470      "material_intensity": 0.216,471      "personnel_intensity": 0.07,472      "sga": null,473      "sga_ratio": null,474      "opex_core": 66937556.62,475      "opex_ratio": 0.124,476      "interest_coverage": null,477      "effective_tax_rate": null,478      "capitalized_own_work_ratio": 0.003,479      "inventory_change_ratio": null,480      "finance_income": 5025778.39,481      "finance_income_from_affiliates": null,482      "finance_to_ebt_ratio": null,483      "company_size_by_revenue": "large",484      "source_statement_date": "2023-12-31",485      "source_statement_type": "Jahresabschluss",486      "fixed_assets_total": 316193205.41,487      "land_and_buildings": 46944085.59,488      "long_term_financial_assets": 27907040.73,489      "trade_receivables": 25390709.7,490      "prepaid_expenses": 4997999.45,491      "capital_reserves": 536224.77,492      "revenue_reserves": 20005000,493      "profit_loss_carried_forward": 332187259.01,494      "pension_provisions": null,495      "other_provisions": 22278401.94,496      "liabilities_to_affiliated_companies": 2667666.2,497      "other_liabilities": 11628299.19,498      "deferred_income": 14760029.1,499      "interest_income": 5025778.39,500      "interest_expense": 42.37,501      "depreciation_amortization_operating": 129958760.25,502      "write_downs_financial_assets_and_securities": null,503      "income_after_taxes": 165011477.67,504      "_provenance": {505        "statement_type": "Jahresabschluss",506        "period_start": "2023-01-01",507        "period_end": "2023-12-31",508        "exempt_subsidiary": false,509        "parent_organization": null510      }511    },512    {513      "year": 2022,514      "employees": 320,515      "company_size_by_employees": "large",516      "revenue_per_employee": 1396309.758,517      "net_income_per_employee": 377666.02,518      "assets_total": 444880125.47,519      "active_total": 444880125.47,520      "equity_total": 352242259.01,521      "liabilities_total": 46463198.47,522      "provisions_total": 26782680.75,523      "current_assets_total": 131050312.58,524      "inventory_total": 1887629.1,525      "receivables_total": 27702079.33,526      "securities_current_total": null,527      "cash_and_equivalents": 101460604.15,528      "ppe_total": 269345763.76,529      "intangible_assets": 12231207.94,530      "goodwill": null,531      "equity_ratio": 0.792,532      "debt_to_equity": 0.132,533      "debt_to_assets": 0.104,534      "cash_to_assets": 0.228,535      "cash_to_liabilities": 2.184,536      "receivables_to_assets": 0.062,537      "inventory_to_assets": 0.004,538      "ppe_to_assets": 0.605,539      "intangible_to_assets": 0.027,540      "goodwill_to_assets": null,541      "intangible_to_equity": 0.035,542      "tangible_equity": 340011051.07,543      "tangible_equity_ratio": 0.764,544      "operating_working_capital": 6188582.52,545      "net_working_capital_strict": 115739202.37,546      "net_working_capital_approx": 84587114.11,547      "interest_bearing_debt_strict": null,548      "interest_bearing_debt_broad": 31152088.26,549      "net_debt_narrow": null,550      "net_debt_broad": -70308515.89,551      "bank_debt": null,552      "bonds": null,553      "trade_payables": 15311110.21,554      "intragroup_receivables": 425178.6,555      "intragroup_payables": 4135982.99,556      "company_size_by_assets": "large",557      "revenue": 446819122.41,558      "material_expenses": 86705005.69,559      "material_expenses_goods": 1716860.71,560      "material_expenses_services": 84988144.98,561      "personnel_expenses": 30660187,562      "wages_salaries": 26876081.71,563      "social_expenses": 3784105.29,564      "pension_costs": null,565      "depreciation_amortization": 132774782.91,566      "other_operating_income": 851946.7,567      "other_operating_expenses": 32577388.65,568      "selling_expenses": null,569      "admin_expenses": null,570      "gross_profit": null,571      "ebit": null,572      "ebt": null,573      "income_taxes": 48316338.38,574      "other_taxes": 106304.86,575      "net_income": 120853126.37,576      "ebitda": null,577      "gross_margin": null,578      "ebitda_margin": null,579      "ebit_margin": null,580      "net_margin": 0.27,581      "material_intensity": 0.194,582      "personnel_intensity": 0.069,583      "sga": null,584      "sga_ratio": null,585      "opex_core": 63237575.65,586      "opex_ratio": 0.142,587      "interest_coverage": null,588      "effective_tax_rate": null,589      "capitalized_own_work_ratio": 0.004,590      "inventory_change_ratio": 0.004,591      "finance_income": 2670145.94,592      "finance_income_from_affiliates": 2500000,593      "finance_to_ebt_ratio": null,594      "company_size_by_revenue": "large",595      "source_statement_date": "2022-12-31",596      "source_statement_type": "Jahresabschluss",597      "fixed_assets_total": 309484012.43,598      "land_and_buildings": 47348736.49,599      "long_term_financial_assets": 27907040.73,600      "trade_receivables": 19612063.63,601      "prepaid_expenses": 4345800.46,602      "capital_reserves": null,603      "revenue_reserves": 20005000,604      "profit_loss_carried_forward": 296334132.64,605      "pension_provisions": null,606      "other_provisions": 16843449.75,607      "liabilities_to_affiliated_companies": 4135982.99,608      "other_liabilities": 27016105.27,609      "deferred_income": 19391987.24,610      "interest_income": 170145.94,611      "interest_expense": 145745.2,612      "depreciation_amortization_operating": 132774782.91,613      "write_downs_financial_assets_and_securities": null,614      "income_after_taxes": 120959431.23,615      "_provenance": {616        "statement_type": "Jahresabschluss",617        "period_start": "2022-01-01",618        "period_end": "2022-12-31",619        "exempt_subsidiary": false,620        "parent_organization": null621      }622    }623  ],624  "meta": {625    "request_credit_cost": 8,626    "credits_remaining": 145627  }628}

200 · Resposta de exemplo: dados básicos com administração e KPIs financeiros (trecho)

Nossa requisição de exemplo custou 8 créditos: os dados básicos e os dois recursos, porque ambos retornaram dados. Cada recurso tem seu próprio preço e só custa quando retorna dados. Todos os recursos com seus preços estão em fetch-organization.

Busca & Exportação como alternativa

Para um único perfil de empresa, você não precisa de busca. A Busca & Exportação (search-organizations) vale a pena quando você quer mostrar ou analisar vários resultados:

Autocomplete num campo de entrada enquanto alguém digita.
Formulários de busca próprios em que usuários escolhem numa lista de resultados.
Listas por região, setor, forma jurídica ou indicadores, veja Montar listas de empresas.

Uma página de resultados custa 1 crédito. Cada resultado contém seu entity_id. Use-o para obter o perfil da empresa em seguida.

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

import requests

response = requests.get(
    "https://handelsregister.ai/api/v1/search-organizations",
    headers={"x-api-key": "SUA_CHAVE_DE_API"},
    params={
        "q": "Hetzner Online GmbH",
        "limit": "5",
    },
)
data = response.json()

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

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

1{2  "results": [3    {4      "entity_id": "94eb910fef13f94585c48c263fa446d4",5      "name": "Hetzner Online GmbH",6      "registration": {7        "court": "Ansbach",8        "register_type": "HRB",9        "register_number": "6089"10      },11      "address": {12        "house_number": "25",13        "street": "Industriestraße",14        "postal_code": "91710",15        "city": "Gunzenhausen",16        "county": "Weißenburg-Gunzenhausen",17        "state": "Bayern",18        "country": "DEU",19        "coordinates": {20          "latitude": 49.12483,21          "longitude": 10.7805222        }23      },24      "seat": {25        "city": "Gunzenhausen"26      },27      "registration_date": "2015-07-28T00:00:00",28      "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.",29      "_match_context": [],30      "status_normalized": null31    },32    {33      "entity_id": "63529c3a793e9f002196b4fd344e1241",34      "name": "Hetzner Cloud GmbH",35      "registration": {36        "court": "München",37        "register_type": "HRB",38        "register_number": "226782"39      },40      "address": {41        "house_number": "12A",42        "street": "Feringastraße",43        "postal_code": "85774",44        "city": "Unterföhring",45        "county": "München (Landkreis)",46        "state": "Bayern",47        "country": "DEU",48        "coordinates": {49          "latitude": 48.17815,50          "longitude": 11.6348751        }52      },53      "seat": {54        "city": "Unterföhring"55      },56      "registration_date": "2016-07-01T00:00:00",57      "purpose": "Entwicklung und Betrieb von Internetdiensten.",58      "_match_context": [],59      "status_normalized": null60    },61    {62      "entity_id": "f1747f74c17a47de25bcc130a7b4687f",63      "name": "HETZNER Verwaltungs GmbH",64      "registration": {65        "court": "Ulm",66        "register_type": "HRB",67        "register_number": "680752"68      },69      "address": {70        "house_number": "15",71        "street": "In den Torgärten",72        "postal_code": "97980",73        "city": "Bad Mergentheim",74        "county": "Main-Tauber-Kreis",75        "state": "Baden-Württemberg",76        "country": "DEU",77        "coordinates": {78          "latitude": 49.44874,79          "longitude": 9.78780        }81      },82      "seat": {83        "city": "Bad Mergentheim"84      },85      "registration_date": "2000-11-14T00:00:00",86      "purpose": "Die Beteiligung an Unternehmen und deren Verwaltung, insbesondere die Beteiligung und Geschäftsführung sowie die Übernahme der persönlichen Haftung an der Firma HETZNER GmbH & Co. KG.",87      "_match_context": [],88      "status_normalized": null89    },90    {91      "entity_id": "d8699b327083bea015fc66908d7bb370",92      "name": "Hetzner GmbH Steuerberatungsgesellschaft",93      "registration": {94        "court": "Stuttgart",95        "register_type": "HRB",96        "register_number": "747057"97      },98      "address": {99        "house_number": "7",100        "street": "Stuttgarter Straße",101        "postal_code": "74211",102        "city": "Leingarten",103        "county": "Heilbronn (Landkreis)",104        "state": "Baden-Württemberg",105        "country": "DEU",106        "coordinates": {107          "latitude": 49.14068,108          "longitude": 9.13568109        }110      },111      "seat": {112        "city": "Leingarten"113      },114      "registration_date": "2013-12-04T00:00:00",115      "purpose": "Die für Steuerberatungsgesellschaften gesetzlich und berufsrechtlich zulässigen Tätigkeiten gemäß § 33 in Verbindung mit § 57 Abs. 3 StBerG, insbesondere Steuerberatung. Handels- und Bankgeschäfte sind ausgeschlossen.",116      "_match_context": [],117      "status_normalized": null118    },119    {120      "entity_id": "7d0d69b853c37abcc75d3f7536b9f240",121      "name": "Hörber + Hetzner GmbH",122      "registration": {123        "court": "Nürnberg",124        "register_type": "HRB",125        "register_number": "10098"126      },127      "address": {128        "house_number": "47",129        "street": "Sulzbacher Straße",130        "postal_code": "90552",131        "city": "Röthenbach a.d.Pegnitz",132        "county": "Nürnberger Land",133        "state": "Bayern",134        "country": "DEU",135        "coordinates": {136          "latitude": 49.4914,137          "longitude": 11.251138        }139      },140      "seat": {141        "city": "Röthenbach a. d. Pegnitz"142      },143      "registration_date": "1991-02-04T00:00:00",144      "purpose": "Planung und Entwicklung, die Konstruktion, die Herstellung und der Vertrieb von Maschinen und Vorrichtungen aller Art sowie von Erzeugnissen ergänzender Art.",145      "_match_context": [],146      "status_normalized": null147    }148  ],149  "total": 2165,150  "total_exact": false,151  "total_relation": "upper_bound",152  "meta": {153    "request_credit_cost": 1,154    "credits_remaining": 145155  }156}

200 · Resposta de exemplo: os cinco primeiros resultados para “Hetzner Online GmbH”

Para enriquecer dados de clientes existentes, a busca geralmente é um desvio. Envie nome e cidade ou o número de registro direto para fetch-organization, veja Enriquecer dados de clientes.

Armadilhas comuns

Número de registro sem tribunal: só HRB 6089 retorna HTTP 404. Sempre acrescente o tribunal de registro.
Nomes comuns: quando empresas compartilham um nome, a API pode retornar outra empresa diferente da esperada ou nenhuma. Confira registration e address, ou pergunte diretamente com tribunal de registro e número de registro.
Entradas imprecisas: o Modo IA (ai_search=on-default) muitas vezes encontra nomes curtos e entradas imprecisas. Ele custa 20 créditos a mais, mesmo quando não encontra nenhuma empresa.
Nomes de recursos: a API ignora nomes desconhecidos ou escritos errado sem erro. Se faltar um bloco na resposta, confira a grafia.

Próximos passos

fetch-organization Todos os parâmetros, recursos e erros do endpoint. Encontrar diretores e sócios Administração, sócios e beneficiários finais. Analisar indicadores financeiros Indicadores, balanço e DRE ao longo de vários anos. Enriquecer dados de clientes Acrescentar dados de empresas a uma lista inteira de clientes.