기본 개념 – 문서 | handelsregister.ai

회사를 명확하게 찾기

fetch-organization의 파라미터 q는 세 가지 입력을 받아요. 이 페이지의 예시는 Hetzner Online GmbH, Ansbach HRB 6089에 대한 요청이에요:

회사를 명확하게 찾기
입력	예시	적합한 경우
회사명	`Hetzner Online GmbH`	처음 시작할 때. 등기부에 적힌 그대로 최대한 완전하게 쓰세요.
등기 법원과 등기 번호	`Ansbach HRB 6089`	등기된 모든 회사에 대해 고유해요. 법원, 등기 유형, 번호는 한 묶음이에요.
entity_id	`94eb910fef13f94585c48c263fa446d4`	후속 요청용. 모든 응답에서 받아요.

등기 법원마다 번호를 따로 부여하므로 등기 번호만으로는 부족해요. 반면 순서는 자유로워요. 예시에서 HRB 6089 Ansbach도 같은 회사를 찾아요.

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

import requests

response = requests.get(
    "https://handelsregister.ai/api/v1/fetch-organization",
    headers={"x-api-key": "YOUR_API_KEY"},
    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": "YOUR_API_KEY" },
});
const data = await response.json();

여러 회사가 같은 이름이면 API가 그중 하나를 반환할 수 있는데, 원하는 회사가 아닐 수도 있고 404로 응답할 수도 있어요. 정확한 회사가 중요하다면 등기 법원과 등기 번호 또는 entity_id로 조회하세요.

API가 회사를 찾지 못하면 404로 응답하고 과금하지 않아요. 모호한 입력에는 AI 모드(ai_search=on-default)가 있어요. 이름의 일부만으로도 회사를 찾고 웹에서 조사해요. 회사를 찾지 못해도 20 크레딧이 추가로 들어요. 여러 후보를 한 번에 받으려면 검색 및 내보내기를 쓰세요.

기능

모든 회사 프로필에는 이름, 법적 형태, 상태, 등기, 주소, 목적, 업종, 자본금, 대표 규정 등 기본 데이터가 담겨 있어요. 나머지는 기능으로 요청해요. 예를 들어 대표이사는 related_persons, 재무 KPI는 financial_kpi예요.

여러 기능은 feature를 반복하거나 목록으로 넘겨요: features=related_persons,financial_kpi. 각 기능은 응답에서 자체 키 아래에 나타나요. publications만 그곳에서 history라고 불려요.

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

import requests

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

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

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

API는 알 수 없는 이름을 오류 메시지 없이 무시하므로 철자를 확인하세요. 플랜에 포함되지 않은 기능은 빠지고 과금되지 않아요.

모든 기능과 가격은 fetch-organization에, 모든 필드는 데이터 카탈로그에 있어요.

크레딧

데이터 요청에는 크레딧이 들어요. 회사 프로필에는 다음 규칙이 적용돼요:

API가 회사를 반환하면 기본 가격 5 크레딧이 적용돼요.
기능은 응답에 데이터를 반환할 때만 크레딧이 들어요. 항목이 없는 insolvency_publications를 포함해 빈 기능은 무료예요.
실시간 모드와 AI 모드는 기능이 아니라 고유한 규칙을 가진 추가 요금이에요:
- 실시간 모드는 실시간 조회가 성공하면 10 크레딧이 추가로 들어요. 새 내용이 없어도 마찬가지예요.
- AI 모드는 회사를 찾지 못해도 20 크레딧이 추가로 들어요. 요청이 너무 오래 걸려 API가 408로 중단한 경우에만 추가 요금이 면제돼요.
그 밖의 모든 오류는 비용이 들지 않아요.

개별 기능의 규칙은 과금에, 가격은 fetch-organization에 있어요.

예: related_persons와 financial_kpi를 포함한 기본 데이터는 두 기능이 모두 데이터를 반환하면 5 + 2 + 1 = 8 크레딧이에요.

각 요청 전에 API는 잔액이 가능한 최고 가격을 감당하는지 확인해요. 그렇지 않으면 402로 응답하고 과금하지 않아요. 실제로 차감된 금액은 meta.request_credit_cost에, 요청 후 잔액은 meta.credits_remaining에 있어요.

1{2  "meta": {3    "request_credit_cost": 5,4    "credits_remaining": 1455  }6}

200 · 기본 데이터만 요청한 예시의 meta

크레딧은 시작 크레딧으로, 크레딧 구독으로 매달, 또는 충전 크레딧으로 한 번 받아요. 크레딧 구독이 없으면 시작 크레딧과 충전 크레딧은 30일 동안 유효하고, 구독이 활성 상태면 만료되지 않아요. 나머지는 모두 과금에 있어요.

최신 데이터와 실시간 모드

기본적으로 회사 프로필은 저희 데이터베이스에서 나와요. 정보가 얼마나 최신인지는 출처에 따라 달라요.

Handelsregister

기본 데이터, 인물, 등기 공고는 등기부를 기준으로 데이터베이스에서 최신 상태로 유지해요. 빠르고 대부분의 용도에 충분해요.

실시간 모드(realtime_mode=handelsregister-default)를 쓰면 API가 요청 시점에 Handelsregister(상업 등기부)에서 Aktueller Abdruck(AD, 현재 등본)를 실시간으로 가져와 JSON으로 반환해요. 현재 등기된 인물도 기능 비용 없이 related_persons.current로 받아요.

실시간 조회의 성공 여부는 _realtime_mode.status에 표시돼요. 실시간 모드의 10 크레딧은 success일 때만 과금해요.

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

import requests

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

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

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

1{2  "name": "Hetzner Online GmbH",3  "_realtime_mode": {4    "mode": "handelsregister-default",5    "status": "success"6  },7  "related_persons": {8    "current": [9      {10        "entity_id": "78ad32e16ff779f589a9e88d23356f74",11        "label": "MANAGING_DIRECTOR",12        "role": {13          "en": {14            "long": "Managing Director",15            "short": "MD"16          },17          "de": {18            "long": "Geschäftsführer",19            "short": "GF"20          }21        },22        "name": "Max Mustermann",23        "name_parts": {24          "given": "Max",25          "family": "Mustermann",26          "maiden": null,27          "canonical_name": "Mustermann, Max",28          "aliases": [29            "Mustermann, Max"30          ],31          "previous_names": null32        },33        "start_date": null,34        "end_date": null,35        "birth_date": "1976-01-15",36        "location": {37          "home": {38            "city": "Musterheim"39          }40        },41        "organization_representation_scheme": {42          "current": [43            "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."44          ],45          "history": []46        },47        "role_representation_scheme": {48          "current": [49            "einzelvertretungsberechtigt",50            "mit der Befugnis, im Namen der Gesellschaft mit sich im eigenen Namen oder als Vertreter eines Dritten Rechtsgeschäfte abzuschließen"51          ],52          "history": []53        }54      },55      {56        "entity_id": "73549375ff7d709b9e7e2941ad1ffaa3",57        "label": "MANAGING_DIRECTOR",58        "role": {59          "en": {60            "long": "Managing Director",61            "short": "MD"62          },63          "de": {64            "long": "Geschäftsführer",65            "short": "GF"66          }67        },68        "name": "Paul Musterwald",69        "name_parts": {70          "given": "Paul",71          "family": "Musterwald",72          "maiden": null,73          "canonical_name": "Musterwald, Paul",74          "aliases": [75            "Musterwald, Paul"76          ],77          "previous_names": null78        },79        "start_date": null,80        "end_date": null,81        "birth_date": "1989-07-18",82        "location": {83          "home": {84            "city": "Probebrück"85          }86        },87        "organization_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        "role_representation_scheme": {94          "current": [95            "einzelvertretungsberechtigt"96          ],97          "history": []98        }99      },100      {101        "entity_id": "cfecded2c1d17946c8ab0379aa786eed",102        "label": "MANAGING_DIRECTOR",103        "role": {104          "en": {105            "long": "Managing Director",106            "short": "MD"107          },108          "de": {109            "long": "Geschäftsführer",110            "short": "GF"111          }112        },113        "name": "Jan Musterhuber",114        "name_parts": {115          "given": "Jan",116          "family": "Musterhuber",117          "maiden": null,118          "canonical_name": "Musterhuber, Jan",119          "aliases": [120            "Musterhuber, Jan"121          ],122          "previous_names": null123        },124        "start_date": null,125        "end_date": null,126        "birth_date": "1955-11-06",127        "location": {128          "home": {129            "city": "Probeingen"130          }131        },132        "organization_representation_scheme": {133          "current": [134            "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."135          ],136          "history": []137        },138        "role_representation_scheme": {139          "current": [140            "einzelvertretungsberechtigt"141          ],142          "history": []143        }144      }145    ]146  },147  "meta": {148    "request_credit_cost": 15,149    "credits_remaining": 145150  }151}

200 · 실시간 모드를 쓴 Hetzner Online GmbH 예시 응답 발췌

실시간 조회가 실패하면 API는 데이터베이스에 저장된 데이터를 반환해요. 이때 _realtime_mode.status가 success가 아니므로 알 수 있어요. 그러면 실시간 모드는 과금되지 않으며, meta.request_credit_cost에서도 확인할 수 있어요.

실시간 모드는 오늘의 상태가 중요할 때 가치가 있어요. 예를 들어 계약 전에 새 거래처를 확인하거나, 지금 누가 회사를 대표할 수 있는지 볼 때예요.

실시간 조회는 일반 조회보다 오래 걸려요. 클라이언트 타임아웃을 최소 120초로 설정하세요. 요청이 너무 오래 걸리면 API가 408로 응답하고 과금하지 않아요. 그때는 나중에 다시 시도하세요.

연간 재무제표

새로 공개된 연간 재무제표를 매일 찾아요. 하지만 회사는 회계연도 종료 후 최대 12개월 안에 공개하면 되고(§ 325 HGB), 많은 회사가 그 기한을 모두 써요. 일부 회사는 법정 기한을 일부러 넘겨 더 늦게 공개해요.

그래서 최신 재무제표가 재작년 것인 경우가 많아요. 자세한 내용은 최신성에 있어요.

파산 공고

파산 법원은 보통 결정 당일이나 직후에 공고를 게시해요. insolvency_publications 기능으로 받으며, 각각 법원, 사건 번호, 날짜가 포함돼요.

뉴스

news 기능은 웹에서 회사에 관한 뉴스를 제목, 출처, 날짜, 링크와 함께 반환해요. 최신성은 그 회사에 대한 마지막 보도 시점에 달려 있어요. 소규모 회사는 맞는 보도가 몇 건뿐인 경우가 많아요.

이력과 유효 기간

많은 정보가 시간이 지나며 바뀌어요. 그래서 API는 현재 상태와 이력을 나란히 반환해요:

current는 오늘 기준 상태예요.
history는 등기된 모든 상태를 effective_from과 effective_to와 함께 나열해요. effective_to가 null이면 그 상태가 지금도 유효해요.
인물은 related_persons.current와 related_persons.past에 있으며, 각각 start_date와 end_date가 있어요.

이력이 있는 모든 정보는 등기부와 공고에서 와요. 예를 들어 Handelsregister의 Chronologischer Abdruck(CD, 연대순 등본)나 공개된 모든 연간 재무제표예요.

예시에서 Hetzner Online GmbH의 대표 규정은 다음과 같아요. 예시 응답에서 2015년 7월 28일까지는 이사회를, 그 이후로는 대표이사를 기재해요:

1{2  "representation_scheme": {3    "current": [4      "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."5    ],6    "history": [7      {8        "value": [9          "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."10        ],11        "effective_from": "2002-10-15",12        "effective_to": "2015-07-28"13      },14      {15        "value": [16          "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."17        ],18        "effective_from": "2015-07-28",19        "effective_to": null20      }21    ]22  }23}

예시 응답: Hetzner Online GmbH의 representation_scheme

대부분의 날짜는 YYYY-MM-DD 형식이에요. 이력이 거슬러 올라가는 범위는 연혁과 이력에서 설명해요.

빈 값

모든 회사가 모든 필드에 값을 갖지는 않아요. API는 이를 두 가지 방식으로 표시해요:

null: 이 필드에 값이 없어요.
[]: 목록에 항목이 없어요. 예: 파산 공고 없음.

데이터가 없는 요청 기능은 null 또는 []로 오며 비용이 들지 않아요.

1{2  "name": "dm-drogerie markt GmbH + Co. KG",3  "legal_form": "GmbH & Co. KG",4  "contact_data": {5    "website": "https://www.dm.de",6    "phone_number": "+49 721 55920",7    "email": null8  },9  "capital": {10    "current": null,11    "history": []12  },13  "mergers_and_acquisitions": null,14  "insolvency_publications": []15}

빈 값이 있는 dm-drogerie markt GmbH + Co. KG 예시 응답 발췌

일부 빈 객체가 []로 오므로, 코드에서는 키 없음, null, []를 똑같이 다루세요. 키의 순서는 고정되어 있지 않으므로 필드는 이름으로 읽으세요.

값이 없다면 대개 회사가 그 값을 공개할 의무가 아예 없는 경우예요. 법적 형태와 규모에 따라 법이 요구하는 내용은 데이터 제공 범위에서 설명해요. 일부 정보는 의도적으로 보류하며, 그런 정보에는 redacted: true가 붙어요.

안정성과 버전

API는 추가 방식으로 확장돼요. 새 데이터와 기능은 새 필드로 추가돼요. 기존 필드를 제거하거나 이름을 바꾸지 않으며, 타입이나 의미도 바꾸지 않아요. 그래서 모든 버전이 하위 호환돼요.

기존 코드를 깨뜨릴 변경은 새 API 버전에서만 나와요. 예: /v2. 현재 버전은 /v1에서 동작해요.

그러니 클라이언트가 알 수 없는 필드는 무시하고, 알 수 없는 값은 일반적인 경우로 처리하게 하세요. 새 필드와 기능은 변경 이력에 있어요.

플랜

회사 프로필, 문서, 검색 및 내보내기, Signals는 크레딧 구독 없이도 모든 계정에서 쓸 수 있어요. 크레딧 구독은 매달 새 크레딧을 주고 더 많은 데이터를 열어 줘요:

플랜
추가로 제공되는 것	Plus	Pro	Max
인물 프로필: 인물의 직책과 지분	포함	포함	포함
검색 및 내보내기: 소유, 경영진, 도산 필터	미포함	포함	포함
회사 프로필: 90개 이상의 확장 재무 지표	미포함	포함	포함
회사 프로필: 에너지 공급업체의 활동별 재무제표 (§ 6b EnWG)	미포함	미포함	포함
회사 프로필: 심층 주주 정보 (`shareholders_deep`)	미포함	미포함	포함
기업 네트워크 (`network`)	미포함	포함	포함
Signals: 파산	미포함	포함	포함
Signals: 조직 변경 & M&A	미포함	미포함	포함

API는 플랜에 없는 기능을 오류 없이 빼고 과금하지 않아요. 플랜에 없는 인물 프로필과 검색 필터는 403으로 거부하며, 역시 비용이 들지 않아요. Signals에서는 명시적으로 요청한 주제에 이것이 적용되고, 주제를 지정하지 않으면 플랜의 모든 주제를 받아요.

플랜의 가격과 크레딧은 가격 페이지에 있어요.