v1.0.0 Stabilny
Panel kontrolny

Dokumentacja API

Dostęp do kompleksowych danych niemieckich firm poprzez nasze RESTful API. Informacje w czasie rzeczywistym z oficjalnych rejestrów handlowych.

Bazowy URL
https://handelsregister.ai/api
Format
JSON
Uwierzytelnianie
Klucz API
Limity prędkości
60/min (5/min dokumenty)

Uwierzytelnianie

API Handelsregister AI obsługuje dwie metody uwierzytelniania: Klucz API i Token Bearer. Obie metody działają na wszystkich endpointach API.

Metody Uwierzytelniania

1. Uwierzytelnianie Kluczem API

Twój klucz API może być dostarczony na dwa sposoby:

a)
Nagłówek (Zalecane): x-api-key: YOUR_API_KEY
b)
Parametr Zapytania (Legacy): ?api_key=YOUR_API_KEY

2. Uwierzytelnianie Tokenem Bearer

Dla zwiększonego bezpieczeństwa i zarządzania tokenami, możesz tworzyć tokeny API:

Nagłówek Autoryzacji: Authorization: Bearer YOUR_TOKEN

Najlepsze Praktyki i Przypadki Użycia

Klucz API przez Nagłówek: Zalecane dla integracji serwer-do-serwera i użycia produkcyjnego
Klucz API przez Parametr Zapytania: Tylko do szybkich testów i kompatybilności wstecznej
Token Bearer: Najlepszy dla aplikacji wymagających dokładnej kontroli dostępu, wygaśnięcia tokenów i zwiększonego bezpieczeństwa

Przykłady Uwierzytelniania Kluczem API

Używanie Nagłówka x-api-key (Zalecane) 
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"

Zarządzanie Tokenami Bearer

Tworzenie Tokenu 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"
     }'

Odpowiedź będzie zawierać Twój token Bearer. Przechowuj go bezpiecznie!

Używanie Tokenu Bearer
curl -X GET "https://handelsregister.ai/api/v1/search-organizations?q=company" \
     -H "Authorization: Bearer YOUR_API_TOKEN"
Endpointy Zarządzania Tokenami
  • POST /api/v1/auth/tokens/create - Utwórz nowy token
  • GET /api/v1/auth/tokens - Wyświetl wszystkie tokeny
  • DELETE /api/v1/auth/tokens/{id} - Unieważnij określony token
  • DELETE /api/v1/auth/tokens - Unieważnij wszystkie tokeny

Endpoints

GET

/v1/fetch-organization

5-21 kredytów • 60/min

Pobierz kompleksowe informacje o niemieckiej firmie, w tym status prawny, dane finansowe, zarząd i więcej.

Parametry

Nazwa Typ Wymagane Opis
api_key string Warunkowe* Twój klucz API. Wymagany, jeśli nie używasz nagłówka x-api-key lub tokenu Bearer
q string WYMAGANE Nazwa firmy, numer rejestracyjny lub zapytanie wyszukiwania
feature string opcjonalne Dodatkowa funkcja danych do dołączenia. Może być określona wielokrotnie (zobacz tabelę funkcji poniżej)
ai_search string opcjonalne Włącz wyszukiwanie AI. Wartości: on-default lub zostaw parametr całkowicie pusty
realtime_mode string opcjonalne Echtzeitmodus für Live-Daten aus dem Handelsregister aktivieren. Werte: handelsregister-default oder Parameter komplett weglassen

Dostępne funkcje

financial_kpi 1 kredyt
balance_sheet_accounts 3 kredyty
profit_and_loss_account 3 kredyty
related_persons 2 kredyty
publications 1 kredyt
news 10 kredytów
insolvency_publications 1 kredyt
annual_financial_statements 5 kredytów
annual_financial_statements__html 5 Credits
shareholders Beta
5 kredytów
ubos Beta
10 Credits
shareholdings Beta
5 Credits
website_content AI
0 Credits

Przykładowe żądanie

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'

Przykładowa odpowiedź

{
  "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"
  }
}

Szczegóły struktury odpowiedzi

Podstawowe dane firmy

Zawsze dołączone: entity_id, name, status, legal_form, address, registration, contact_data, purpose, keywords, products_and_services

financial_kpi

Tablica rocznych wskaźników finansowych (przychody, dochód netto, pracownicy, itp.) z wielu lat

balance_sheet_accounts

Hierarchiczne dane bilansu z podziałem aktywów i pasywów na rok

profit_and_loss_account

Szczegółowe rachunki zysków i strat z podziałem przychodów, kosztów i zysków na rok

related_persons

Obecni i byli dyrektorzy/funkcjonariusze z rolami, nazwami i okresami kadencji

publications

Oficjalne publikacje i ogłoszenia rejestru handlowego

news

Tablica artykułów prasowych z tytułem, źródłem, datą publikacji i URL

insolvency_publications

Publikacje sądu upadłościowego z datami, ID spraw i szczegółami zdarzeń

annual_financial_statements

Pełne raporty roczne w formacie markdown z metadanymi

annual_financial_statements__html

Vollständige Jahresberichte im HTML-Format mit Metadaten

shareholders Beta

Lista udziałowców firmy z procentami własności i rolami

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

Nazwa Typ Wymagane Opis
api_key string WYMAGANE Twój klucz API. Wymagany, jeśli nie używasz nagłówka x-api-key lub tokenu Bearer
person_q string WYMAGANE Name der Person (min. 2 Zeichen, erforderlich)
organization_q string WYMAGANE Unternehmenskontext zur Disambiguierung gleichnamiger Personen (min. 2 Zeichen, erforderlich)
feature string[] opcjonalne 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 kredyt • 60/min

Wyszukaj niemieckie firmy z zaawansowanym filtrowaniem i obsługą paginacji.

Parametry

Nazwa Typ Wymagane Opis
api_key string Warunkowe* Twój klucz API. Wymagany, jeśli nie używasz nagłówka x-api-key lub tokenu Bearer
q string WYMAGANE Zapytanie wyszukiwania (min: 2 znaki)
skip integer opcjonalne Liczba wyników do pominięcia (domyślnie: 0)
limit integer opcjonalne Wyników na stronę (domyślnie: 10, max: 30)
filters object opcjonalne Filtruj tylko według postal_code. Format:

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.

Przykładowe żądanie

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'

Przykładowa odpowiedź

{
  "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 kredytów • 5/min

Pobierz oficjalne dokumenty PDF z niemieckiego rejestru handlowego.

Parametry

Nazwa Typ Wymagane Opis
api_key string Warunkowe* Twój klucz API. Wymagany, jeśli nie używasz nagłówka x-api-key lub tokenu Bearer
company_id string WYMAGANE Unikalny ID jednostki firmy z wyników wyszukiwania
document_type string WYMAGANE Typ dokumentu. Wartości: shareholders_list, articles_of_association, AD, CD, SI

Przykładowe żądanie

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

Odpowiedź

Sukces (200): Zwraca plik PDF bezpośrednio

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

Błąd: Zwraca JSON ze szczegółami błędu

Typy dokumentów

shareholders_list

Dokument rejestru udziałowców

articles_of_association

Gesellschaftervertrag / Satzung / Statut Dokument

AD

Aktualne wypisy (Aktuelle Daten)

CD

Wypisy historyczne (Chronologische Daten)

SI

Strukturierte Inhalte – als XML-Datei zurückgegeben.

Obsługa błędów

200 OK

Żądanie zakończyło się sukcesem

400 Nieprawidłowe żądanie

Nieprawidłowe parametry

401 Nieautoryzowany

Nieprawidłowy lub brakujący klucz API

402 Wymagana płatność

Niewystarczające kredyty

429 Zbyt wiele żądań

Przekroczono limit prędkości

500 Błąd serwera

Wewnętrzny błąd serwera

Format odpowiedzi błędu

{
  "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+ • Licencja MIT
Instalacja 
pip install handelsregister

Podstawowe użycie

from handelsregister import Handelsregister

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

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

Interfejs obiektowy

from handelsregister import Company

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

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

Wzbogacanie danych

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.