v1.0.0 안정
대시보드

API 참조

RESTful API를 통해 독일 기업의 포괄적인 데이터에 액세스하세요. 공식 상업 등기부에서 실시간 정보를 제공합니다.

기본 URL
https://handelsregister.ai/api
형식
JSON
인증
API 키
속도 제한
60회/분 (문서 5회/분)

인증

Handelsregister AI API는 두 가지 인증 방법을 지원합니다: API 키와 Bearer 토큰. 두 방법 모두 모든 API 엔드포인트에서 작동합니다.

인증 방법

1. API 키 인증

API 키는 두 가지 방법으로 제공할 수 있습니다:

a)
헤더 (권장): x-api-key: YOUR_API_KEY
b)
쿼리 매개변수 (레거시): ?api_key=YOUR_API_KEY

2. Bearer 토큰 인증

향상된 보안 및 토큰 관리를 위해 API 토큰을 생성할 수 있습니다:

인증 헤더: Authorization: Bearer YOUR_TOKEN

모범 사례 및 사용 사례

헤더를 통한 API 키: 서버 간 통합 및 프로덕션 사용에 권장
쿼리 매개변수를 통한 API 키: 빠른 테스트 및 하위 호환성을 위해서만 사용
Bearer 토큰: 세밀한 액세스 제어, 토큰 만료 및 향상된 보안이 필요한 애플리케이션에 가장 적합

API 키 인증 예시

x-api-key 헤더 사용 (권장) 
curl -X GET "https://handelsregister.ai/api/v1/search-organizations?q=company" \
     -H "x-api-key: YOUR_API_KEY"
# Using query parameter (legacy)
curl "https://handelsregister.ai/api/v1/fetch-organization?api_key=YOUR_API_KEY&q=company"

# Using x-api-key header (recommended)
curl -X GET "https://handelsregister.ai/api/v1/fetch-organization?q=company" \
     -H "x-api-key: YOUR_API_KEY"

Bearer 토큰 관리

API 토큰 생성
curl -X POST "https://handelsregister.ai/api/v1/auth/tokens/create" \
     -H "x-api-key: YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "token_name": "My Application",
       "abilities": ["*"],
       "expires_at": "2026-01-01 00:00:00"
     }'

응답에는 Bearer 토큰이 포함됩니다. 안전하게 보관하세요!

Bearer 토큰 사용
curl -X GET "https://handelsregister.ai/api/v1/search-organizations?q=company" \
     -H "Authorization: Bearer YOUR_API_TOKEN"
토큰 관리 엔드포인트
  • POST /api/v1/auth/tokens/create - 새 토큰 생성
  • GET /api/v1/auth/tokens - 모든 토큰 나열
  • DELETE /api/v1/auth/tokens/{id} - 특정 토큰 취소
  • DELETE /api/v1/auth/tokens - 모든 토큰 취소

엔드포인트

GET

/v1/fetch-organization

5-21 크레딧 • 60회/분

법적 지위, 재무 데이터, 경영진 등을 포함한 독일 기업의 포괄적인 정보를 검색합니다.

매개변수

이름 유형 필수 설명
api_key string 조건부* 귀하의 API 키. x-api-key 헤더 또는 Bearer 토큰을 사용하지 않는 경우 필수
q string 필수 회사명, 등록번호 또는 검색 쿼리
feature string 선택사항 포함할 추가 데이터 기능. 여러 번 지정 가능 (아래 기능 표 참조)
ai_search string 선택사항 AI 검색 활성화. 값: on-default 또는 매개변수를 완전히 비워둠
realtime_mode string 선택사항 Echtzeitmodus für Live-Daten aus dem Handelsregister aktivieren. Werte: handelsregister-default oder Parameter komplett weglassen

사용 가능한 기능

financial_kpi 1 크레딧
balance_sheet_accounts 3 크레딧
profit_and_loss_account 3 크레딧
related_persons 2 크레딧
publications 1 크레딧
news 10 크레딧
insolvency_publications 1 크레딧
annual_financial_statements 5 크레딧
annual_financial_statements__html 5 Credits
shareholders Beta
5 크래딧
ubos Beta
10 Credits
shareholdings Beta
5 Credits
website_content AI
0 Credits

요청 예시

curl -X GET 'https://handelsregister.ai/api/v1/fetch-organization?q=BMW%20AG&feature=financial_kpi&feature=related_persons&feature=publications&feature=website_content&ai_search=on-default' \
     -H 'x-api-key: YOUR_API_KEY'

응답 예시

{
  "entity_id": "add84642a957b08a3f252c69c9d063de",
  "name": "Polyden-Folienfabrik GmbH",
  "status": "INACTIVE",
  "legal_form": "GmbH",
  "purpose": "Herstellung von Folien...",
  "registration_date": "1978-02-23T00:00:00",
  "address": {
    "house_number": "38",
    "street": "Ansbacher Straße",
    "postal_code": "91560",
    "city": "Heilsbronn",
    "coordinates": {
      "latitude": 49.33438,
      "longitude": 10.78262
    }
  },
  "registration": {
    "court": "Ansbach",
    "register_type": "HRB",
    "register_number": "405"
  },
  "contact_data": {
    "website": "https://www.polyden.de",
    "phone_number": "+49 9872 808 0"
  },
  "financial_kpi": [
    {
      "year": 2022,
      "revenue": 41855558.25,
      "net_income": -19668989.99,
      "employees": 208
    }
  ],
  "related_persons": {
    "current": [
      {
        "name": "Knut Neumann",
        "role": {
          "en": {"long": "Managing Director"},
          "de": {"long": "Geschäftsführer"}
        },
        "start_date": "2019-06-03"
      }
    ]
  },
  "publications": [...],
  "news": [
    {
      "title": "Company News Title",
      "source": "News Source",
      "publication_date": "2023-08-08"
    }
  ],
  "meta": {
    "request_credit_cost": 55,
    "credits_remaining": "73841334"
  }
}

응답 구조 세부사항

핵심 회사 데이터

항상 포함됨: entity_id, name, status, legal_form, address, registration, contact_data, purpose, keywords, products_and_services

financial_kpi

여러 년도에 걸친 연간 재무 지표 배열 (매출, 순수익, 직원 수 등)

balance_sheet_accounts

연도별 자산 및 부채 분석을 포함한 계층적 대차대조표 데이터

profit_and_loss_account

연도별 매출, 비용, 이익 분석을 포함한 상세 손익계산서

related_persons

역할, 이름, 재임 기간을 포함한 현재 및 과거 이사/임원

publications

공식 상업 등기부 발행물 및 공고

news

제목, 출처, 발행일, URL을 포함한 뉴스 기사 배열

insolvency_publications

날짜, 사건 ID, 이벤트 세부사항을 포함한 파산 법원 발행물

annual_financial_statements

메타데이터가 포함된 마크다운 형식의 완전한 연간 보고서

annual_financial_statements__html

Vollständige Jahresberichte im HTML-Format mit Metadaten

shareholders Beta

소유 비율 및 역할이 포함된 회사 주주 목록

ubos Beta

Wirtschaftlich Berechtigte (UBOs) mit Beteiligungsquoten, inklusive aufgelöster und nicht aufgelöster Eigentümer sowie Abdeckungsgrad

shareholdings Beta

Aktuelle Beteiligungen dieses Unternehmens an anderen Gesellschaften mit Anteilshöhe, Einlage und Stichtag

website_content

Unternehmens-Website als strukturiertes Markdown, optimiert für LLM-Verarbeitung (nur AI Mode, 0 Credits)

GET

/v1/fetch-person

15-20 Credits • 60/min

Personenprofile aus dem deutschen Handelsregister und dem öffentlichen Web zusammenführen. ai_search ist immer aktiv; die Grundkosten von 15 Credits enthalten die AI-Anreicherung bereits.

Parameter

이름 유형 필수 설명
api_key string 필수 귀하의 API 키. x-api-key 헤더 또는 Bearer 토큰을 사용하지 않는 경우 필수
person_q string 필수 Name der Person (min. 2 Zeichen, erforderlich)
organization_q string 필수 Unternehmenskontext zur Disambiguierung gleichnamiger Personen (min. 2 Zeichen, erforderlich)
feature string[] 선택사항 Zusätzliches Datenfeature. Zurzeit unterstützt: shareholdings.

Verfügbare Features

shareholdings +5 credits

Beteiligungen der Person an Unternehmen (Name, Anteil, Rolle, Stichtag). +5 Credits, nur wenn Daten geliefert werden.

Beispiel-Anfrage

curl -X GET 'https://handelsregister.ai/api/v1/fetch-person?person_q=Max%20Mustermann&organization_q=Beispielwerk%20Analytics%20GmbH&features=shareholdings' \
     -H 'x-api-key: YOUR_API_KEY'

Beispiel-Antwort

{
  "entity_id": "f1e2d3c4b5a69788a7b6c5d4e3f2a1b0",
  "name": "Max Mustermann",
  "birth_date": "1985-07-14",
  "name_parts": {
    "given": "Max",
    "family": "Mustermann",
    "maiden": null,
    "canonical_name": "Mustermann, Max",
    "previous_names": null
  },
  "location": {
    "home": {
      "city": "München"
    }
  },
  "bio": "Max Mustermann ist Mitgründer und Geschäftsführer der Beispielwerk Analytics GmbH...",
  "expertise": [
    "Produktentwicklung",
    "Softwareentwicklung",
    "Datenanalyse",
    "KI"
  ],
  "contact": {
    "emails": [
      {
        "address": "[email protected]",
        "type": "organization",
        "label": "Allgemeine Kontakt-E-Mail"
      }
    ],
    "phones": []
  },
  "profiles": {
    "linkedin": "https://linkedin.com/in/max-mustermann",
    "github": "https://github.com/max-mustermann",
    "other": []
  },
  "affiliations": [
    {
      "organization": "Beispielwerk Analytics GmbH",
      "relation": "Geschäftsführer"
    }
  ],
  "handelsregister_roles": [
    {
      "entity_id": "b4a3c2d1e5f697887a6b5c4d3e2f1a0b",
      "name": "Beispielwerk Analytics GmbH",
      "label": "MANAGING_DIRECTOR",
      "role": {
        "en": "Managing Director",
        "de": "Geschäftsführer"
      },
      "start_date": "2019-06-03",
      "end_date": null
    }
  ],
  "shareholdings": {
    "holdings": {
      "current": [
        {
          "organization": {
            "entity_id": "b4a3c2d1e5f697887a6b5c4d3e2f1a0b",
            "name": "Beispielwerk Analytics GmbH",
            "status": "ACTIVE",
            "legal_form": "GmbH",
            "address": {
              "house_number": "12",
              "street": "Beispielstraße",
              "postal_code": "80331",
              "city": "München",
              "county": "München (Stadt)",
              "state": "Bayern",
              "country": "DEU",
              "coordinates": {
                "latitude": 48.13743,
                "longitude": 11.57549
              }
            },
            "registration": {
              "court": "München",
              "register_type": "HRB",
              "register_number": "254891"
            }
          },
          "ownership": {
            "percentage": 25.0,
            "contribution": {
              "amount": 12500,
              "currency": "EUR"
            }
          },
          "as_of": "2025-03-15"
        }
      ]
    },
    "summary": {
      "total_current": 1
    }
  },
  "meta": {
    "request_credit_cost": 20,
    "credits_remaining": 9996743
  }
}

Grundlegende Personendaten

Immer enthalten: entity_id, name, birth_date, name_parts, location, bio, expertise, contact, profiles, handelsregister_roles, affiliations

GET

/v1/search-organizations

1 크레딧 • 60회/분

고급 필터링 및 페이지네이션 지원을 통한 독일 기업 검색.

매개변수

이름 유형 필수 설명
api_key string 조건부* 귀하의 API 키. x-api-key 헤더 또는 Bearer 토큰을 사용하지 않는 경우 필수
q string 필수 검색 쿼리 (최소: 2자)
skip integer 선택사항 건너뛸 결과 수 (기본값: 0)
limit integer 선택사항 페이지당 결과 수 (기본값: 10, 최대: 30)
filters object 선택사항 postal_code로만 필터링. 형식:

Filter

Alle Filter-Schlüssel sind optional. Bereichsfilter akzeptieren {"gte": min, "lte": max} – jede Grenze kann weggelassen werden.

Beispiel-URL 
GET /v1/search-organizations?q=GmbH&limit=10&filters={"postal_code":"80331","legal_form_code":"GmbH","pl_revenue":{"gte":1000000,"lte":5000000}}

Zur besseren Lesbarkeit nicht URL-kodiert – in echten Requests muss der filters-Wert URL-kodiert werden.

Identität & Registrierung
6
registration_date_from date
Frühestes Registrierungsdatum (ISO 8601, YYYY-MM-DD).
registration_date_to date
Spätestes Registrierungsdatum (ISO 8601, YYYY-MM-DD).
legal_form_code string / array
Deutscher Rechtsformcode, z. B. GmbH, AG, e.V., UG. Einzelner String oder Array.
industry_code string / array
NACE/WZ-Branchencode. Einzelner String oder Array.
industry_scheme string
Klassifikationsschema zu industry_code. Standard: WZ2025.
active boolean
true = nur aktive Unternehmen, false = nur inaktive. Weglassen für beide.
Standort
5
postal_code string
Deutsche 5-stellige Postleitzahl (PLZ).
city string
Stadtname.
state string
Deutsches Bundesland (z. B. Bayern, Hessen).
location_coordinates coordinates
WGS84-Dezimalkoordinaten als Mittelpunkt für die Geo-Suche.
location_max_distance_km number
Radius in km (1–100). Erfordert location_coordinates.
Gericht & Register
3
registration_type string / array
Registertyp: HRA, HRB, GnR, PR oder VR. Einzelner String oder Array.
registration_authority_name string
Name des Gerichts/Registergerichts (z. B. München).
registration_number string
Registernummer (z. B. HRB 12345).
Größe & Mitarbeiter
2
company_size_category enum
Größenklasse: micro, small, medium oder large.
emp_count range
Mitarbeiterzahl-Bereich.
Bilanz
7
bs_assets_total EUR range
Bilanzsumme, in EUR.
bs_equity_total EUR range
Eigenkapital, in EUR.
bs_liabilities_total EUR range
Gesamtverbindlichkeiten, in EUR.
bs_cash_and_equivalents EUR range
Kassenbestand & Zahlungsmitteläquivalente, in EUR.
bs_cash_to_liabilities decimal range
Liquiditätsgrad (Kassenbestand ÷ Verbindlichkeiten), Dezimalwert.
bs_equity_ratio ratio (0–1)
Eigenkapitalquote (Eigenkapital ÷ Bilanzsumme), Dezimalwert 0–1.
bs_debt_to_assets ratio (0–1)
Fremdkapitalquote (Schulden ÷ Bilanzsumme), Dezimalwert 0–1.
Gewinn- und Verlustrechnung
3
pl_revenue EUR range
Jahresumsatz, in EUR.
pl_net_income EUR range
Jahresüberschuss, in EUR.
pl_ebit EUR range
EBIT / Betriebsergebnis, in EUR.

요청 예시

curl 'https://handelsregister.ai/api/v1/search-organizations?api_key=your_api_key_here&q=tech&limit=10&filters=%7B%22postal_code%22%3A%2280992%22%7D'

응답 예시

{
  "results": [
    {
      "entity_id": "65063129c1bf565e4244b943a188bbda",
      "name": "m50 GmbH",
      "registration": {
        "court": "München",
        "register_type": "HRB",
        "register_number": "189767"
      },
      "address": {
        "house_number": "20",
        "street": "Gubestraße",
        "postal_code": "80992",
        "city": "München",
        "county": "München (Stadt)",
        "state": "Bayern",
        "country": "DEU",
        "coordinates": {
          "latitude": 48.18005,
          "longitude": 11.51116
        }
      },
      "registration_date": "2011-01-04T00:00:00",
      "purpose": "Film- und Fernsehproduktion..."
    }
  ],
  "total": 988,
  "meta": {
    "request_credit_cost": 1,
    "credits_remaining": "73841333"
  }
}
GET

/v1/fetch-document

5 크레딧 • 5회/분

독일 상업 등기부에서 공식 PDF 문서를 다운로드합니다.

매개변수

이름 유형 필수 설명
api_key string 조건부* 귀하의 API 키. x-api-key 헤더 또는 Bearer 토큰을 사용하지 않는 경우 필수
company_id string 필수 검색 결과의 고유한 회사 엔티티 ID
document_type string 필수 문서 유형. 값: shareholders_list, articles_of_association, AD, CD, SI

요청 예시

curl 'https://handelsregister.ai/api/v1/fetch-document?api_key=your_api_key_here&company_id=20a1510e88cd2e9b166db4d0bc5d563d&document_type=shareholders_list' \
  -o document.pdf

응답

성공 (200): PDF 파일을 직접 반환

Content-Type: application/pdf · application/xml (application/pdf für AD, CD, shareholders_list, articles_of_association — application/xml für SI.)

오류: 오류 세부사항이 포함된 JSON 반환

문서 유형

shareholders_list

주주 등록부 문서

articles_of_association

Gesellschaftervertrag / Satzung / Statut Dokument

AD

현재 발췌문 (Aktuelle Daten)

CD

이력 발췌문 (Chronologische Daten)

SI

Strukturierte Inhalte – als XML-Datei zurückgegeben.

오류 처리

200 확인

요청 성공

400 잘못된 요청

유효하지 않은 매개변수

401 인증되지 않음

유효하지 않거나 누락된 API 키

402 결제 필요

크레딧 부족

429 요청이 너무 많음

속도 제한 초과

500 서버 오류

내부 서버 오류

오류 응답 형식

{
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "Your account has insufficient credits",
    "details": {
      "required": 10,
      "available": 5
    }
  }
}

Python SDK

PyPI GitHub v1.0.0 • Python 3.8+ • MIT License
설치 
pip install handelsregister

기본 사용법

from handelsregister import Handelsregister

client = Handelsregister(api_key="your_key")
company = client.fetch_organization(q="BMW AG")

print(company['name'])
print(company['registration'])

객체 인터페이스

from handelsregister import Company

company = Company("BMW AG", features=[
    "financial_kpi",
    "related_persons"
])

print(company.revenue)
print(company.current_ceo)

데이터 강화

client.enrich(
    file_path="companies.csv",
    query_properties={"name": "company_name", "location": "city"},
    features=["financial_kpi", "related_persons"],
    output_format="json"
)

npm SDK

npm GitHub v0.1.0 • Node.js 14+ • MIT Lizenz
Installation 
npm install handelsregister

Grundlegende Nutzung

const { Handelsregister, Company } = require('handelsregister');

const client = new Handelsregister('your-api-key');
const companyData = await client.fetchOrganization('OroraTech GmbH');

console.log(companyData.name);
console.log(companyData.registration);

TypeScript Unterstützung

import { Handelsregister, Company, CompanyData } from 'handelsregister';

const client = new Handelsregister(process.env.API_KEY);

const company: CompanyData = await client.fetchOrganization({
    q: 'Konux GmbH',
    features: ['financial_kpi', 'related_persons']
});

Async/Await Interface

// Using async/await
async function getCompanyInfo() {
    try {
        const company = await client.fetchOrganization('OroraTech GmbH');
        return company;
    } catch (error) {
        console.error('Error fetching company:', error.message);
    }
}

// Multiple companies
const companies = ['OroraTech GmbH', 'Konux GmbH', 'Celonis SE'];
const results = await Promise.all(
    companies.map(name => client.fetchOrganization(name))
);

Datenanreicherung

await client.enrich({
    filePath: 'companies.csv',
    queryProperties: { name: 'company_name', location: 'city' },
    features: ['financial_kpi', 'related_persons'],
    outputFormat: 'json'
});

MCP Server Beta

Universeller MCP (Model Context Protocol) Server für nahtlose Integration mit KI-Agenten und Workflow-Automatisierung.

Server URL
https://mcp.handelsregister.ai/mcp

Kompatibilität & Integration

Unser MCP Server ist mit jedem MCP-kompatiblen Client verwendbar und ermöglicht die einfache Integration von Handelsregister-Daten in Ihre KI-gestützten Workflows.

Hauptfunktionen

  • Universelle Kompatibilität mit allen MCP Clients
  • Echtzeit-Zugriff auf deutsche Unternehmensdaten
  • Perfekt für agentenbasierte Workflows
  • Native Integration mit OpenAI SDK

Verwendung mit OpenAI Python SDK

Der MCP Server kann direkt mit dem OpenAI Python SDK verwendet werden, um Handelsregister-Daten in Ihre KI-Anwendungen zu integrieren:

Python 
import os
from openai import OpenAI

client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])

resp = client.responses.create(
    model="gpt-5",
    input="Gib mir die aktuellsten Finanzdaten der Konux GmbH aus München und gebe diese als Markdown-Tabelle aus.",
    tools=[
        {
            "type": "mcp",
            "server_label": "handelsregister",
            "server_url": "https://mcp.handelsregister.ai/mcp",
            "require_approval": "never",
            "headers": {
                "X-API-Key": os.environ["HANDELSREGISTER_API_KEY"]
            },
        }
    ],
)

print(resp.output_text)

Authentifizierung

Die Authentifizierung erfolgt über Ihren handelsregister.ai API-Schlüssel, der als Header übermittelt wird:

X-API-Key: YOUR_API_KEY

Verwenden Sie denselben API-Schlüssel wie für die REST API.

Agentenbasierte Workflows

Der MCP Server ermöglicht die nahtlose Integration von Handelsregister-Daten in komplexe agentenbasierte Workflows:

  • • Automatische Datenextraktion und -analyse
  • • Multi-Agenten-Systeme mit Zugriff auf Unternehmensdaten
  • • Workflow-Automatisierung mit Echtzeit-Datenabruf
  • • Integration in bestehende KI-Pipelines

Credits & Preise

MCP-Anfragen verbrauchen dieselben Credits wie direkte API-Aufrufe, basierend auf den angeforderten Features. Die Preise entsprechen exakt den Preisen der Standard-REST-API.

Anforderungen

  • Gültiger handelsregister.ai API-Schlüssel
  • MCP-kompatibler Client (z.B. OpenAI SDK)
  • Python 3.8+ (für OpenAI SDK)

Wichtige Hinweise

  • • Diese Funktion befindet sich derzeit in der Beta-Phase. Funktionalität und API können sich ändern.
  • • Die Credit-Preise entsprechen exakt den Preisen der Standard-REST-API.
  • • Es gelten dieselben Rate Limits wie für die REST API.
  • • Bei Fragen oder Problemen wenden Sie sich bitte an unseren Support.