Installation und Authentifizierung

pip install handelsregister

export HANDELSREGISTER_API_KEY=your_api_key_here
# Or: export HANDELSREGISTER_BEARER_TOKEN=your_token_here

Für deine Anwendung kannst du einen API-Key oder einen Bearer-Token verwenden. Ein Token eignet sich besonders für eingeschränkte Berechtigungen und Ablaufzeiten. Wenn beides gesetzt ist, verwendet das SDK den Bearer-Token. Zusätzliche Header für einen Proxy oder ein Gateway kannst du über extra_headers oder als JSON in HANDELSREGISTER_EXTRA_HEADERS übergeben; die Authentifizierungs- und User-Agent-Header des SDKs bleiben geschützt.

import os
from handelsregister import Handelsregister

client = Handelsregister(api_key=os.environ["HANDELSREGISTER_API_KEY"])
# client = Handelsregister(bearer_token=os.environ["HANDELSREGISTER_BEARER_TOKEN"])

Unternehmen und Personen abfragen

Mit fetch_organization() rufst du ein Unternehmen samt der gewünschten Feature-Flags ab. ai_search="on-default" aktiviert die KI-Suche. realtime_mode="handelsregister-default" führt eine Live-Abfrage aus (+10 Credits), lässt sich aber nicht mit related_persons oder publications kombinieren.

result = client.fetch_organization(
    q="KONUX GmbH München",
    features=["related_persons", "financial_kpi", "shareholders"],
    ai_search="on-default",
)
print(result["name"], result["registration"]["register_number"])

Die Schnittstelle Company bietet dir typisierten Zugriff auf Stammdaten, Personen, Beteiligungen, Vertretungsregelungen, M&A, Nachrichten und Finanzdaten. Dazu gehören Register- und Kontaktdaten, Finanzberichte, Gesellschafter, UBOs, Beteiligungen und die zugehörigen Vertretungsregeln.

from handelsregister import Company

company = Company(
    "OroraTech GmbH München",
    features=["related_persons", "financial_kpi", "shareholders", "ubos",
              "shareholdings", "mergers_and_acquisitions", "news"],
)
print(company.name, company.is_active, company.formatted_address)
for person in company.current_related_persons:
    print(person["name"], person["role"]["en"]["long"])
for entry in company.shareholders.entries:
    print(entry.display_name, entry.percentage)
for ubo in company.ubos.resolved:
    print(ubo.name, ubo.percentage)
for holding in company.shareholdings.current:
    print(holding.organization_name, holding.percentage)

/v1/fetch-person verbindet Handelsregistereinträge mit öffentlichen Webdaten. Die KI-Suche ist immer aktiv; sie ist im Grundpreis von 15 Credits bereits enthalten. Gib organization_q an, um häufige Namen eindeutig zuzuordnen. shareholdings kostet nur dann 5 Credits, wenn Daten zurückkommen.

from handelsregister import Person

person = Person(
    person_q="Max Mustermann",
    organization_q="Beispielwerk Analytics GmbH",
    features=["shareholdings"],
)
print(person.canonical_name, person.home_city)
for role in person.handelsregister_roles:
    print(role["name"], role["label"], role.get("start_date"))

Suche und Signals

Du kannst mit Suchbegriff, Filtern oder beidem suchen. Filter decken Registerdaten, Rechtsformen, WZ/NACE-Branchen, Aktivstatus, Standort und Radius, Unternehmensgröße, Beschäftigte, Bilanzwerte, Umsatz, Jahresüberschuss und EBIT ab. Verwende dafür RangeFilter oder ein Dictionary mit gte/lte.

from handelsregister import RangeFilter, SearchFilters

page = client.search_organizations(
    limit=10,
    filters=SearchFilters(
        city="München", legal_form_code=["GmbH", "AG"], active=True,
        pl_revenue=RangeFilter(gte=1_000_000, lte=5_000_000),
    ),
    ai_mode="on-default",
)
organizations = list(client.iter_search_organizations(
    q="tech", page_size=30, max_results=100,
))

Die API liefert höchstens 30 Unternehmen pro Anfrage. Ein höheres limit löst ValueError aus. Jede über den Iterator geladene Seite ist eine eigene abrechenbare Anfrage und wird erst abgerufen, wenn du sie wirklich erreichst.

Signals liefern Unternehmensveränderungen mit Cursor-Pagination. Der Katalog ist kostenlos; erfolgreiche Listen- und Detailanfragen kosten jeweils 20 Credits. Eine Seite enthält 20 Signals.

from handelsregister import SignalTopic

page = client.list_signals(
    topics=[SignalTopic.CAPITAL_CHANGES, SignalTopic.TRANSFORMATIONS],
    organization_ids=["0123456789abcdef0123456789abcdef"],
    from_date="2026-07-01", to_date="2026-07-30",
)
catalog = client.get_signal_catalog()
detail = client.get_signal(page["signals"][0]["event"]["id"])

for signal in client.iter_signals(
    topics=[SignalTopic.NEW_REGISTRATIONS], max_results=50,
):
    print(signal["organization"]["current_profile"]["name"])

list_signals() akzeptiert einen undurchsichtigen cursor, Topics, Unternehmens-IDs mit ODER-Semantik und inklusive Datumsgrenzen. Öffentliche Topics sind NEW_REGISTRATIONS, MASTER_DATA_CHANGES, CLOSURES, ROLE_HOLDER_CHANGES, CAPITAL_CHANGES, INSOLVENCIES (Pro) und TRANSFORMATIONS (Max). Ist ein Topic in deinem Plan nicht enthalten, löst das SDK SubscriptionRequiredError aus und es werden keine Credits berechnet. Listeneinträge enthalten Event, Organisation, Beteiligte, Registereintrag, Quelle, topicspezifische Details, Pagination, Filter, Warnungen und Metadaten.

Monitoring und Webhooks

Mit Monitoring erhältst du normalisierte Unternehmensveränderungen über signierte HTTPS-Webhooks. Lesezugriffe sind kostenlos. Für Änderungen brauchst du einen API-Key oder einen Bearer-Token mit account:read und monitoring:manage; für die Verwaltung von Endpunkten zusätzlich account:keys. Über das SDK kannst du Endpunkte, Zustellungen und Events auflisten, fehlgeschlagene Zustellungen erneut senden, Secrets rotieren sowie Endpunkte deaktivieren oder archivieren.

client = Handelsregister(bearer_token="YOUR_ADMIN_TOKEN")
created = client.create_webhook_endpoint(
    name="Production receiver",
    url="https://hooks.example.com/handelsregister",
)
endpoint_id = created["endpoint"]["id"]
signing_secret = created["signing_secret"]  # shown exactly once
client.verify_webhook_endpoint(endpoint_id)
client.test_webhook_endpoint(endpoint_id)

monitor = client.create_monitor(
    entity_id="cc78cf0b230aeae35c6df7ba31989bb9",
    poll_interval_days=7, endpoint_ids=[endpoint_id], label="BMW AG",
)["monitor"]
client.pause_monitor(monitor["id"])
client.resume_monitor(monitor["id"])
client.archive_monitor(monitor["id"])

Die asynchrone Baseline ist kostenlos und unterdrückt historische Beobachtungen. Bei der Aktivierung fallen mindestens 10 Credits für einen rollierenden Zeitraum von 30 Tagen und fünf vollständig erfolgreiche Prüfungen an. Jede weitere vollständige Prüfung kostet 2 Credits. Fehlgeschlagene, unvollständige, ersetzte oder nicht finanzierte Prüfungen bleiben kostenlos.

from handelsregister.webhooks import construct_event, verification_response_headers

event = construct_event(raw_body_bytes, request_headers, signing_secret)
if event["type"] == "endpoint.verification":
    return Response(status=204, headers=verification_response_headers(event))
if event["type"] == "organization.signal.detected":
    signal = event["data"]["signal"]

Webhook-Zustellungen erfolgen mindestens einmal und ohne feste Reihenfolge. Prüfe den unveränderten Request-Body mit HMAC-SHA256 und dedupliziere über die Nachrichten-ID. Nach einer Secret-Rotation bleibt das vorherige Secret sieben Tage lang gültig. Jeder 2xx-Status gilt als Erfolg, Fehler werden etwa drei Tage lang wiederholt. Jede Änderung verwendet einen Idempotency-Key; das SDK benutzt ihn bei internen Wiederholungen weiter, und idempotency_key= macht Wiederholungen nach einem Neustart sicher.

Konto und Nutzung

Kontoabfragen kosten keine Credits. Zum Erstellen oder Widerrufen von API-Keys brauchst du einen Bearer-Token mit account:keys; für die übrigen Abfragen reichen ein API-Key oder ein Bearer-Token mit account:read. Nutzungsabfragen können maximal 366 Tage umfassen. Bei einem to_date ohne Uhrzeit zählt der gesamte Tag; Transaktionen verwenden eine Cursor-Pagination.

client = Handelsregister()
profile = client.get_account()
credits = client.get_account_credits()
subscription = client.get_account_subscription()
keys = client.list_api_keys()
usage = client.get_account_usage(
    from_date="2026-07-01", to_date="2026-07-30", group_by="day",
)
for transaction in client.iter_account_usage_transactions(per_page=100):
    print(transaction["endpoint"], transaction["credits"])

Dokumente, Tokens, Anreicherung und CLI

Verfügbar sind shareholders_list, articles_of_association, AD, CD und SI. Für Bearer-Tokens gibt es Methoden zum Erstellen, Auflisten, einzelnen Widerrufen und zum bewussten Widerruf aller Tokens. ["*"] ist kein Platzhalter für alle Berechtigungen: Das SDK ersetzt ihn durch api:data und account:read.

entity_id = client.fetch_organization(q="KONUX GmbH München")["entity_id"]
client.fetch_document(company_id=entity_id, document_type="shareholders_list",
                      output_file="konux_shareholders.pdf")
pdf_bytes = client.fetch_document(company_id=entity_id, document_type="CD")
xml_bytes = client.fetch_document(company_id=entity_id, document_type="SI",
                                  output_file="konux_structured.xml")

client.enrich(
    file_path="companies.csv", input_type="csv",
    query_properties={"name": "company_name", "location": "city"},
    snapshot_dir="snapshots",
    params={"features": ["related_persons", "financial_kpi", "ubos"]},
    output_file="companies_enriched.csv", output_type="csv",
)

Die Anreicherung unterstützt CSV, JSON, XLSX und DataFrames. Mit Snapshots kannst du lange Jobs fortsetzen; die Ausgabe behält deine Eingabefelder und ergänzt _handelsregister_result sowie _in_file. Die CLI unterstützt außerdem Raw-JSON, reine Filtersuche, Dokumentdownloads, Monitoring-Aktionen, Webhook-Endpunkte, Zustellungen und Events.

handelsregister fetch "KONUX GmbH München"
handelsregister person --person "Max Mustermann" --organization "Beispielwerk Analytics GmbH"
handelsregister search "tech" --postal-code 80992 --limit 20
handelsregister document "KONUX GmbH München" --type SI --output konux_structured.xml
handelsregister monitors pricing --interval 7
handelsregister webhooks events

Feature-Flags, Fehler und Sicherheit

Verfügbare Unternehmens-Features: related_persons, financial_kpi, balance_sheet_accounts, profit_and_loss_account, annual_financial_statements, annual_financial_statements__html, publications, insolvency_publications, news, website_content, shareholders, ubos, shareholdings und mergers_and_acquisitions. Beteiligungs- und M&A-Features befinden sich in der Beta-Phase.

Alle API-Ausnahmen leiten sich von HandelsregisterError ab. Das SDK ordnet Validierungs-, Authentifizierungs-, Kredit-, Berechtigungs- und Abo-, Nichtgefunden-, Konflikt- und Idempotenz-, Rate-Limit-, Timeout-, Server- sowie Webhook-Signaturfehler passenden Ausnahmen zu. Diese enthalten status_code, JSON-payload und Abrechnungs-meta. Wiederholt werden nur Netzwerkfehler, HTTP 408/429 und Serverfehler. Lege Zugangsdaten nie im Quellcode ab und widerrufe einen offengelegten Key oder Token sofort.