기본 데이터

예시

이 페이지의 예시는 Hetzner Online GmbH, Ansbach HRB 6089에 대한 예시 요청에서 가져왔어요. 등기 내용이 바뀌면 직접 요청했을 때 다른 값이 나와요.

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

import requests

response = requests.get(
    "https://handelsregister.ai/api/v1/fetch-organization",
    headers={"x-api-key": "YOUR_API_KEY"},
    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": "YOUR_API_KEY" },
});
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 · 예시 응답: Hetzner Online GmbH, Ansbach HRB 6089의 기본 데이터

이름과 법적 형태

이름, 법적 형태, 상태는 회사를 설명하고, entity_id는 회사를 식별해요. 나중에 회사를 다시 가져오거나 모니터링하거나 내 데이터와 연결하려면 entity_id를 저장하세요.

필드
필드	의미	예시	제공 빈도
entity_idstring	handelsregister.ai에서의 회사 ID. 내 데이터의 키로 저장하세요. 파라미터 q에 넣으면 정확히 이 회사와 일치해요.기본 데이터	`"94eb910fef13f94585c48c263fa446d4"`	항상
namestring	등기부에 적힌 회사명, 법적 형태 접미사 포함.	`"Hetzner Online GmbH"`	위와 같음
legal_formstring	법적 형태, 대개 독일에서 흔히 쓰는 약어. 철자가 조금씩 다를 수 있으니(예: oHG) 대소문자를 구분하지 말고 비교하세요. AI 모드에서는 전체 명칭이 나올 수 있어요. 목록은 흔한 값만 보여 주며, 더 있어요.값: `GmbH` Gesellschaft mit beschränkter Haftung(유한책임회사), `UG (haftungsbeschränkt)` Unternehmergesellschaft(소규모 GmbH), `AG` Aktiengesellschaft(주식회사), `SE` Societas Europaea(유럽 회사), `KGaA` Kommanditgesellschaft auf Aktien(주식합자회사), `GmbH & Co. KG` GmbH가 무한책임사원인 KG, `KG` Kommanditgesellschaft(합자회사), `OHG` Offene Handelsgesellschaft(합명회사), `e.K.` eingetragener Kaufmann(등기된 개인 상인), `eG` eingetragene Genossenschaft(등기된 협동조합), `PartG` Partnerschaftsgesellschaft(전문직 파트너십), 직업상 책임이 제한된 형태 포함, `e.V.` eingetragener Verein(등기된 사단), `eGbR` eingetragene Gesellschaft bürgerlichen Rechts(등기된 민법상 조합)	`"GmbH"`	위와 같음
statusstring	회사의 등기 상태. 다른 값도 있을 수 있으니, 알 수 없는 값은 “비활성”으로 다루세요.값: `ACTIVE` 활성, `INSOLVENT` 파산 절차 중, `DISSOLVED` 해산, 청산 중, `TERMINATED` 등기부에서 말소	`"ACTIVE"`	위와 같음

등기

등기 법원, 등기 유형, 등기 번호가 회사를 식별해요. 저희는 이를 한데 묶어 써요. 예시에서는 “Ansbach HRB 6089”예요. 이 형태 그대로 파라미터 q에 넘길 수도 있어요.

필드
필드	의미	예시	제공 빈도
registrationobject\|null	회사의 등기.비어 있는 경우: AI 모드가 웹 출처로만 아는 회사; 이때 entity_id는 AI_TMP_로 시작기본 데이터	–	항상
registration.courtstring	“Amtsgericht”(지방 법원)를 뺀 지명으로 된 등기 법원, 예: Ansbach 또는 Charlottenburg (Berlin).	`"Ansbach"`	위와 같음
registration.register_typestring	등기 유형, 즉 등기부와 Handelsregister의 경우 그 부문.값: `HRB` Handelsregister B부: GmbH, UG, AG, SE, KGaA, `HRA` Handelsregister A부: e.K., OHG, KG, GmbH & Co. KG, `GnR` Genossenschaftsregister(협동조합 등기부), `PR` Partnerschaftsregister(파트너십 등기부), `VR` Vereinsregister(사단 등기부), `GsR` eGbR용 Gesellschaftsregister(조합 등기부)	`"HRB"`	위와 같음
registration.register_numberstring	텍스트로 된 등기 번호. 등기 법원, 등기 유형과 함께일 때만 고유해요.	`"6089"`	위와 같음
registration_datestring\|null	ISO 8601 타임스탬프로 된 등기부 등기일.비어 있는 경우: 날짜가 기록되어 있지 않음	`"2013-03-18T00:00:00+00:00"`	대부분: GmbH, UG, AG, SE, KGaA, KG, OHG, eG, PartG 드묾: GmbH & Co. KG, e.K.

등기 번호는 등기 법원과 함께일 때만 고유해요. 여러 법원이 같은 번호를 가질 수 있어요.

주소와 본점 소재지

address는 사업장 주소이고, seat는 등기부상의 본점 소재지(Sitz)예요. 예를 들어 회사가 뮌헨에 등기되어 있고 Gauting에서 일하면 둘이 달라요.

필드
필드	의미	예시	제공 빈도
addressobject	회사의 사업장 주소.기본 데이터	–	항상
address.streetstring\|null	번지를 뺀 거리.비어 있는 경우: 주소가 도시로만 되어 있음	`"Industriestraße"`	대부분
address.house_numberstring\|null	텍스트로 된 번지, “6 a” 같은 접미사 포함.비어 있는 경우: 주소에 번지가 없음	`"25"`	위와 같음
address.postal_codestring\|null	텍스트로 된 우편번호, 그래서 앞자리 0이 유지돼요.비어 있는 경우: 주소가 도시로만 되어 있음	`"91710"`	위와 같음
address.citystring	사업장 주소의 도시.	`"Gunzenhausen"`	항상
address.countystring	군(Landkreis) 또는 독립시. 일부 주소에는 키 자체가 없어요.	`"Weißenburg-Gunzenhausen"`	대부분
address.statestring	연방주(Bundesland). 일부 주소에는 키 자체가 없어요.	`"Bayern"`	위와 같음
address.countrystring	ISO 3166 세 글자 코드로 된 국가, 예: DEU. 일부 주소에는 키 자체가 없어요.	`"DEU"`	위와 같음
address.coordinatesobject	지도와 반경 검색을 위한 사업장 주소의 지리 좌표.	–	위와 같음
address.coordinates.latitudenumber\|null	십진 도 단위의 위도.비어 있는 경우: 주소를 지오코딩할 수 없었음	`49.12483`	위와 같음
address.coordinates.longitudenumber\|null	십진 도 단위의 경도.비어 있는 경우: 주소를 지오코딩할 수 없었음	`10.78052`	위와 같음
seatobject	등기부상 회사의 본점 소재지(Sitz).	–	항상
seat.citystring	본점 소재지의 도시. 사업장 주소와 다를 수 있어요.	`"Gunzenhausen"`	위와 같음

사업 목적과 업종

사업 목적(Unternehmensgegenstand)은 GmbH, UG, AG, SE, KGaA, eG, PartG의 경우 등기부에 있어요. GmbH & Co. KG, KG, OHG, 개인 상인(e.K.)은 목적을 등기하지 않아요. 업종, 키워드, 제품 및 서비스는 모든 법적 형태에 있어요.

필드
필드	의미	예시	제공 빈도
purposestring\|null	등기부에 적힌 독일어 사업 목적. AI 모드에서는 사업에 대한 짧은 요약이며, 등기된 목적이 없는 법적 형태에도 있어요.비어 있는 경우: 법적 형태상 목적을 등기하지 않음, 예: KG, OHG, e.K.기본 데이터	`"Die Durchführung von Internet- und Netzwerkdienstleistun…"`	항상: GmbH, UG, AG, SE, KGaA, eG, PartG 없음: GmbH & Co. KG, KG, OHG, e.K.
industry_classificationobject	독일 경제활동 분류(WZ)에 따른 업종, 두 가지 버전.	–	항상
industry_classification.WZ2025array	현행 버전인 WZ 2025에 따른 업종 코드. 검색의 업종 필터도 이 코드를 써요.비어 있는 경우: 업종을 배정할 수 없었음	–	대부분
industry_classification.WZ2025[].codestring	다섯 자리 WZ 코드, 예: 62.20.1.	`"62.20.1"`	위와 같음
industry_classification.WZ2025[].labelstring	독일어로 된 경제활동 이름.	`"Erbringung von Beratungsleistungen auf dem Gebiet der In…"`	위와 같음
industry_classification.WZ2008array	아직 이전 버전을 쓰는 시스템을 위한 WZ 2008 기준 업종 코드.비어 있는 경우: WZ 2008 배정이 없음	–	일부
industry_classification.WZ2008[].codestring	WZ 2008 기준 다섯 자리 WZ 코드.	`"62.01.0"`	위와 같음
industry_classification.WZ2008[].labelstring	독일어로 된 경제활동 이름.	`"Erbringung von Dienstleistungen der Informationstechnolo…"`	위와 같음
keywordsarray	공개 웹 출처에서 모은 회사 사업에 관한 키워드. AI 모드로 확장돼요.비어 있는 경우: 회사의 웹 노출이 적음	–	위와 같음
products_and_servicesarray	공개 웹 출처에서 모은 회사의 제품과 서비스 목록. AI 모드로 확장돼요.비어 있는 경우: 회사의 웹 노출이 적음	–	위와 같음

AI 모드에서 purpose에는 등기부 텍스트 대신 사업에 대한 짧은 요약이 담겨요. AI 모드는 웹에서 키워드와 제품 및 서비스를 더해요.

자본금

자본회사는 자본금(Stammkapital 또는 Grundkapital)을 등기하며, 모든 변경이 날짜와 함께 기록돼요. current는 유효한 금액, history는 시간순 변경 내역이에요. 인적 회사와 개인 상인은 고정 자본금이 없어서 current가 null이고 history는 비어 있어요.

필드
필드	의미	예시	제공 빈도
capitalobject	이력이 포함된 등기 자본금.기본 데이터	–	항상
capital.currentobject\|null	유효한 자본금 금액.비어 있는 경우: 법적 형태상 고정 자본금을 등기하지 않음, 예: KG, OHG, e.K., PartG	–	항상: GmbH, UG, AG, SE, KGaA 드묾: eG 없음: GmbH & Co. KG, KG, OHG, e.K., PartG
capital.current.amountnumber	currency의 통화로 된 숫자 금액.	`50000`	위와 같음
capital.current.currencystring	ISO 4217 코드로 된 통화, 거의 항상 EUR.	`"EUR"`	위와 같음
capital.current.kindstring	자본금 종류. 다른 값도 있을 수 있어요.값: `STAMMKAPITAL` GmbH 또는 UG의 Stammkapital(출자 자본금), `GRUNDKAPITAL` AG, SE 또는 KGaA의 Grundkapital(주식 자본금), `LIABILITY_SUM` Haftsumme(책임액), 예: 협동조합, `CONDITIONAL` AG의 조건부 자본금, 이전 등기에서	`"STAMMKAPITAL"`	위와 같음
capital.historyarray	유효한 것을 포함해 등기된 모든 금액, 시간순.	–	위와 같음
capital.history[].valueobject	amount, currency, kind가 담긴 금액, current와 같은 구조.	–	위와 같음
capital.history[].value.change_amountobject	등기 내용에 따른 변경 금액, amount와 currency 포함. 자본금이 늘었는지 줄었는지는 이전 금액과 비교하면 알 수 있어요.	–	일부: AG, SE, KGaA 드묾: GmbH, UG, eG 없음: GmbH & Co. KG, KG, OHG, e.K., PartG
capital.history[].effective_fromstring\|null	이 날부터 유효, YYYY-MM-DD 형식.	`"2002-10-15"`	항상: GmbH, UG, AG, SE, KGaA 드묾: eG 없음: GmbH & Co. KG, KG, OHG, e.K., PartG
capital.history[].effective_tostring\|null	이 날까지 유효.비어 있는 경우: 금액이 아직 유효함	`"2005-02-28"`	위와 같음

자본금 이력은 등기 내용에서 자동으로 읽어 내요. 이를 위해 최신 기술을 쓰고 품질에 많은 투자를 하지만, 개별 오류가 있을 수 있어요.

대표 규정

대표 규정(Vertretungsregelung)은 누가 회사를 위해 행위할 수 있는지 정해요. 응답에는 등기부의 문구가 독일어 그대로 담겨요. Hetzner Online GmbH 예시 요청에서 이력은 2015년 7월 28일까지 이사회(Vorstand)를, 그 이후로는 대표이사를 기재했어요. 개별 인물의 권한은 대표권에 있어요.

필드
필드	의미	예시	제공 빈도
representation_schemeobject	이력이 포함된 회사의 일반 대표 규정.기본 데이터	–	항상: GmbH, UG, GmbH & Co. KG, KG, OHG, eG, PartG 대부분: AG, SE, KGaA, e.K.
representation_scheme.currentarray\|null	유효한 규정, 등기부 문구 그대로의 텍스트 단락 목록.비어 있는 경우: 등기된 규정이 없음	–	위와 같음
representation_scheme.historyarray	유효한 것을 포함해 등기된 모든 버전과 그 유효 기간.	–	위와 같음
representation_scheme.history[].valuearray	이 버전의 텍스트, 단락 목록.	–	위와 같음
representation_scheme.history[].effective_fromstring\|null	이 날부터 유효, YYYY-MM-DD 형식.	`"2002-10-15"`	위와 같음
representation_scheme.history[].effective_tostring\|null	이 날까지 유효.비어 있는 경우: 버전이 아직 유효함	`"2015-07-28"`	위와 같음

실시간 모드에서는 history가 비어 있어요. 유효한 버전은 current에 있어요.

연락처와 웹

연락처는 등기부에 없어요. 회사 웹사이트에서 모아요. 그래서 있는지 여부는 회사가 웹에 무엇을 공개하는지에 달려 있어요.

필드
필드	의미	예시	제공 빈도
contact_dataobject	회사 웹사이트에서 가져온 연락처.기본 데이터	–	항상
contact_data.websitestring\|null	웹사이트 주소.비어 있는 경우: 웹사이트를 찾지 못함	`"https://www.hetzner.com/"`	일부
contact_data.phone_numberstring\|null	회사가 공개한 그대로의 전화번호. 형식은 정규화하지 않아요.비어 있는 경우: 번호를 찾지 못함	`"09831 5050"`	위와 같음
contact_data.emailstring\|null	회사의 일반 이메일 주소.비어 있는 경우: 주소를 찾지 못함	`"[email protected]"`	위와 같음
website_contentstring\|null	Markdown으로 된 웹사이트 텍스트, 예: 자체 분석이나 언어 모델용. website_content 기능으로 오며, AI 모드와 함께일 때만 추가 비용 없이 와요.비어 있는 경우: 웹사이트를 찾지 못함`website_content`	`"Dedicated Servers, Cloud & Hosting from Germany \| Hetzne…"`	위와 같음

실시간 모드

realtime_mode=handelsregister-default를 쓰면 API가 Handelsregister도 실시간으로 조회해요. 그러면 응답에 현재 등기된 인물과 조회 결과가 담긴 _realtime_mode가 들어 있어요. 실시간 모드는 조회가 성공할 때만 과금되지만, 그때는 무엇을 반환하든 과금돼요.

필드
필드	의미	예시	제공 빈도
_realtime_modeobject	실시간 조회 결과. realtime_mode를 요청했을 때만 응답에 있어요.기본 데이터	–	항상
_realtime_mode.modestring	요청한 모드, handelsregister-default.	`"handelsregister-default"`	위와 같음
_realtime_mode.statusstring	실시간 조회의 성공 여부. 다른 값이면 응답에는 저장된 데이터가 담기고 실시간 모드는 과금되지 않아요.값: `success` 실시간 조회 성공, 데이터가 Handelsregister에서 바로 옴	`"success"`	위와 같음

실시간 조회는 더 오래 걸리니 클라이언트 타임아웃을 최소 120초로 설정하세요. 실시간 조회가 실패하면 API는 저장된 데이터를 반환해요. 이때 _realtime_mode.status는 success가 아니고 실시간 모드는 과금되지 않아요. 요청이 너무 오래 걸리면 비용 없이 408을 받아요. 나중에 다시 시도하세요.

fetch-organization 기본 데이터를 반환하는 엔드포인트, 파라미터와 오류 포함. 인물과 대표권 대표이사, Prokura, 사원과 그 권한. 기본 개념 current와 history, null과 빈 목록 읽는 법. 데이터 제공 범위 법적 형태별로 등기부에 담긴 내용과 데이터의 출처.

예시