Αναφορά API

Πρόσβαση σε ολοκληρωμένα δεδομένα γερμανικών επιχειρήσεων μέσω του RESTful API μας. Πληροφορίες σε πραγματικό χρόνο από επίσημα εμπορικά μητρώα.

Βασικό URL
https://handelsregister.ai/api
Μορφή
JSON
Πιστοποίηση
Κλειδί API
Όρια Ρυθμού
60/λεπτό (5/λεπτό έγγραφα)

Schnellstart

In drei Schritten zum ersten Unternehmensprofil.

  1. 1

    API-Schlüssel holen

    Kostenlos registrieren und den API-Schlüssel aus dem Dashboard kopieren. Neue Konten enthalten Gratis-Credits zum Ausprobieren aller Features.

    Dashboard öffnen
  2. 2

    Erste Anfrage senden

    Ein Unternehmensprofil mit zwei kostenpflichtigen Features abrufen. Der Schlüssel wird im x-api-key Header übermittelt:

    curl 'https://handelsregister.ai/api/v1/fetch-organization?q=BMW%20AG&feature=financial_kpi&feature=related_persons' \
         -H 'x-api-key: YOUR_API_KEY'
  3. 3

    Antwort verstehen

    Die Kern-Unternehmensdaten sind immer enthalten; jedes angeforderte Feature erscheint als Top-Level-Schlüssel. meta zeigt exakt, was berechnet wurde — Features ohne Daten kosten nichts:

    {
      "entity_id": "cc78cf0b230aeae35c6df7ba31989bb9",
      "name": "Bayerische Motoren Werke Aktiengesellschaft",
      "status": "ACTIVE",
      "legal_form": "AG",
      "registration": {"court": "München", "register_type": "HRB", "register_number": "42243"},
      "financial_kpi": [{"year": 2021, "revenue": 111239000000, "net_income": 12382000000}, "..."],
      "related_persons": {"current": ["..."], "past": ["..."]},
      "meta": {"request_credit_cost": 8, "credits_remaining": 992}
    }

Πιστοποίηση

Το Handelsregister AI API υποστηρίζει δύο μεθόδους πιστοποίησης: Κλειδί API και Bearer Token. Και οι δύο μέθοδοι λειτουργούν σε όλα τα σημεία τέλους API.

Μέθοδοι Πιστοποίησης

1. Πιστοποίηση Κλειδιού API

Το κλειδί API σας μπορεί να παρασχεθεί με δύο τρόπους:

a)
Κεφαλίδα (Συνιστώμενο): x-api-key: YOUR_API_KEY
b)
Παράμετρος Ερωτήματος (Παλιό): ?api_key=YOUR_API_KEY

2. Πιστοποίηση Bearer Token

Για ενισχυμένη ασφάλεια και διαχείριση token, μπορείτε να δημιουργήσετε API tokens:

Κεφαλίδα Εξουσιοδότησης: Authorization: Bearer YOUR_TOKEN

Βέλτιστες Πρακτικές & Περιπτώσεις Χρήσης

Κλειδί API μέσω Κεφαλίδας: Συνιστώμενο για ενσωματώσεις διακομιστή-προς-διακομιστή και χρήση παραγωγής
Κλειδί API μέσω Παραμέτρου Ερωτήματος: Μόνο για γρήγορες δοκιμές και συμβατότητα προς τα πίσω
Bearer Token: Καλύτερο για εφαρμογές που απαιτούν λεπτομερή έλεγχο πρόσβασης, λήξη token και ενισχυμένη ασφάλεια

Παραδείγματα Πιστοποίησης Κλειδιού 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 Token

Δημιουργία API Token
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 token σας. Αποθηκεύστε το ασφαλώς!

Χρήση Bearer Token
curl -X GET "https://handelsregister.ai/api/v1/search-organizations?q=company" \
     -H "Authorization: Bearer YOUR_API_TOKEN"
Σημεία Τέλους Διαχείρισης Token
  • POST /api/v1/auth/tokens/create - Δημιουργία νέου token
  • GET /api/v1/auth/tokens - Λίστα όλων των tokens
  • DELETE /api/v1/auth/tokens/{id} - Ανάκληση συγκεκριμένου token
  • DELETE /api/v1/auth/tokens - Ανάκληση όλων των tokens

Σημεία Τέλους

Auf einen Blick
GET /v1/fetch-organization 5-21 πιστώσεις • 60/λεπτό
GET /v1/fetch-person 15-20 Credits • 60/min
GET /v1/search-organizations 1 πίστωση • 60/λεπτό
GET /v1/fetch-document 5 πιστώσεις • 5/λεπτό
GET

/v1/fetch-organization

5-21 πιστώσεις • 60/λεπτό

Ανάκτηση ολοκληρωμένων πληροφοριών για μια γερμανική εταιρεία συμπεριλαμβανομένου του νομικού καθεστώτος, οικονομικών δεδομένων, διοίκησης και άλλων.

Παράμετροι

Όνομα Τύπος Απαιτείται Περιγραφή
api_key string Υπό όρους* Το κλειδί API σας. Απαιτείται εάν δεν χρησιμοποιείτε την κεφαλίδα x-api-key ή Bearer token
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 5 πιστώσεις
annual_financial_statements 5 πιστώσεις
annual_financial_statements__html 5 Credits
shareholders Beta
5 μονάδες
ubos Beta
10 Credits
shareholdings Beta
5 Credits
mergers_and_acquisitions Beta
20 Credits
website_content AI
0 Credits
So funktioniert die Abrechnung
  • Jede Anfrage kostet 5 Credits Grundpreis. Jedes angeforderte Feature addiert seinen Preis aus der Tabelle unten.
  • Features werden nur berechnet, wenn sie tatsächlich Daten liefern. Ein angefragtes Feature ohne Ergebnis (z. B. ein Unternehmen ohne Insolvenzbekanntmachungen) kostet nichts — das Feld request_credit_cost im meta-Objekt zeigt immer, was wirklich berechnet wurde.
  • Der AI-Modus (ai_search=on-default) kostet zusätzlich 20 Credits. Der AI-Aufschlag fällt auch an, wenn die Anfrage selbst fehlschlägt, da die AI-Verarbeitung unabhängig davon läuft.
  • Der Echtzeitmodus (realtime_mode=handelsregister-default) kostet zusätzlich 10 Credits — berechnet nur, wenn der Live-Abruf aus dem Register erfolgreich war. Der Echtzeitmodus ist nicht mit den Features related_persons und publications kombinierbar.

Παράδειγμα Αιτήματος

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": 29,
    "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

Πλήρεις ετήσιες εκθέσεις σε μορφή markdown με μεταδεδομένα

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

mergers_and_acquisitions Beta

M&A-Transaktionen (Verschmelzungen, Spaltungen, Unternehmensverträge) mit Gegenparteien, Rollen, Registereinträgen sowie Kontrollverhältnissen und Zusammenfassung

website_content

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

Antwortbeispiele pro Feature

Gekürzte reale Ausschnitte, die die JSON-Struktur jedes Features zeigen (Arrays mit "..." gekürzt):

financial_kpi
"financial_kpi": [
  {
    "year": 2021,
    "revenue": 111239000000,
    "net_income": 12382000000,
    "active_total": 229527000000,
    "material_expenses": null,
    "personnel_expenses": null
  },
  "..."
]
balance_sheet_accounts
"balance_sheet_accounts": [
  {
    "year": 2024,
    "balance_sheet_accounts": [
      {
        "name": {"de": "Aktivseite", "en": "Assets", "in_report": "Aktiva"},
        "value": 267732000000,
        "children": [
          {
            "name": {"de": "Aktuelle Anlagen", "en": "Current Assets", "in_report": "..."},
            "value": 96387000000,
            "children": ["..."]
          },
          "..."
        ]
      },
      "..."
    ]
  },
  "..."
]
profit_and_loss_account
"profit_and_loss_account": [
  {
    "year": 2024,
    "profit_and_loss_accounts": [
      {
        "name": {"de": "Umsatzerlöse", "en": "Revenue", "in_report": "Umsatzerlöse"},
        "value": 142380000000,
        "children": []
      },
      "..."
    ]
  },
  "..."
]
related_persons
"related_persons": {
  "current": [
    {
      "entity_id": "80fd27f39a5c075f88d99f3e126442e0",
      "name": "Milan Dr. Nedeljkovic",
      "label": "BOARD_CHAIR",
      "role": {
        "en": {"long": "Board Chair", "short": "Board"},
        "de": {"long": "Vorsitzender des Vorstands", "short": "Vorstand"}
      },
      "start_date": "2026-05-15",
      "end_date": null,
      "birth_date": "1969-03-11",
      "name_parts": {"given": "Milan", "family": "Nedeljkovic", "canonical_name": "Dr. Nedeljkovic, Milan"},
      "titles": ["Dr."],
      "location": {"home": {"city": "Leipzig"}}
    },
    "..."
  ],
  "past": ["..."]
}
publications → response key "history"
"history": [
  {
    "entity_type": "EVENT",
    "name": {"en": "Change of legal form", "de": "Änderung der Rechtsform"},
    "description": {
      "short": {"en": "The company changed its legal form", "de": "Die Rechtsform wurde geändert"}
    },
    "start_date": "2018-09-28T00:00:00",
    "details": {
      "value": "Gesellschaft mit beschränkter Haftung",
      "linked_entities": {"organization": {"name": "OroraTech GmbH"}}
    }
  },
  "..."
]
insolvency_publications
"insolvency_publications": [
  {
    "publication_date": "2026-05-05T00:00:00+00:00",
    "insolvency_id": "10 IN 56/26",
    "court_city": "Wiesbaden",
    "entity_name": "Teltec AG",
    "seat": "Mainz-Kastel",
    "register": "Wiesbaden, HRB 27296",
    "publication_label": "Eröffnung",
    "event_notice": "Am 05.05.2026 wurde eine Insolvenzbekanntmachung (Eröffnung) ..."
  },
  "..."
]
news
"news": [
  {
    "id": "c204cffdcef222e543ae5c16",
    "title": "PTA-CMS: Bayerische Motoren Werke Aktiengesellschaft: ...",
    "source": "TradingView",
    "publication_date": "2026-07-20",
    "url": "https://de.tradingview.com/news/..."
  },
  "..."
]
annual_financial_statements
"annual_financial_statements": [
  {
    "document_type": "Jahresabschluss",
    "document_date": "2026-04-16",
    "document_title": "Jahresabschluss zum Geschäftsjahr vom 01.01.2025 bis zum 31.12.2025",
    "language": "Deutsch",
    "year": 2025,
    "document_md": "| Bayerische Motoren Werke Aktiengesellschaft ... (full report as Markdown)"
  },
  "..."
]
shareholders
"shareholders": {
  "total_capital": {"amount": 125193, "currency": "EUR"},
  "entries": [
    {
      "shareholder": {
        "entity_id": "960bf144c3eda5c99e3caab086644da1",
        "first_name": "Ingo",
        "last_name": "Baumann",
        "birth_date": "1971-02-27",
        "address": "Köln-Neustadt/Nord"
      },
      "contribution": {"amount": 566, "currency": "EUR"},
      "contribution_ratio": 0.00452,
      "role": {
        "label": "SHAREHOLDER",
        "en": {"long": "Shareholder", "short": "Shareholder"},
        "de": {"long": "Gesellschafter", "short": "Gesellschafter"}
      }
    },
    "..."
  ]
}
ubos
"ubos": {
  "beneficial_owners": [
    {
      "person": {
        "entity_id": "99e133f16ed20bbe874dfb08f87f2e54",
        "name": "Thomas Grübler",
        "birth_date": "1991-09-20",
        "name_parts": {"given": "Thomas", "family": "Grübler", "canonical_name": "Grübler, Thomas"},
        "location": {"home": {"city": "München", "state": "Bayern", "country": "DEU"}}
      },
      "ownership_percentage": 6.3,
      "paths": [
        {
          "percentage": 6.3,
          "via": [{"depth": 1, "name": "Gruebler Ventures UG (haftungsbeschränkt)", "entity_id": "...", "step_percentage": 6.3}]
        }
      ]
    },
    "..."
  ],
  "unresolved_beneficial_owners": [
    {
      "reason": "no_further_shareholder_data",
      "entity_id": "0aedd216ca3a22f0204667d552fe0c82",
      "name": "ConActivity KG",
      "legal_form": "KG",
      "ownership_percentage": 10.53,
      "registration": {"court": "Frankfurt am Main", "register_type": "HRA", "register_number": "30787"},
      "via": []
    },
    "..."
  ]
}
shareholdings
"shareholdings": {
  "holdings": {
    "current": [
      {
        "organization": {
          "entity_id": "c3b23cd03d57d302b938b74ce7fbc5e3",
          "name": "BMW M GmbH Gesellschaft für individuelle Automobile",
          "status": "ACTIVE",
          "legal_form": "GmbH",
          "address": {"city": "München", "state": "Bayern", "country": "DEU", "...": "..."},
          "registration": {"court": "München", "register_type": "HRB", "register_number": "44621"}
        },
        "ownership": {
          "percentage": 100,
          "contribution": {"amount": 50000, "currency": "DEM"}
        },
        "as_of": "2020-12-21"
      },
      "..."
    ]
  },
  "summary": {"total_current": 15}
}
mergers_and_acquisitions
"mergers_and_acquisitions": {
  "transactions": [
    {
      "id": "9254b90f65271482a0cd4babd80814b6",
      "headline": {
        "en": "Result transfer agreement with Avemio AG concluded",
        "de": "Ergebnisabführungsvertrag mit Avemio AG geschlossen"
      },
      "type": {
        "category": "ENTERPRISE_AGREEMENT",
        "event_type": "GROUP.ENTERPRISE_AGREEMENT",
        "name": {"en": "Enterprise agreement", "de": "Unternehmensvertrag"}
      },
      "kind": {
        "label": "RESULT_TRANSFER",
        "name": {"en": "Result transfer agreement", "de": "Ergebnisabführungsvertrag"}
      },
      "role": {
        "label": "CONTROLLED",
        "en": {"long": "Controlled company", "short": "Controlled"},
        "de": {"long": "Beherrschtes Unternehmen", "short": "Beherrscht"}
      },
      "phase": "REGISTERED",
      "date": "2023-10-11",
      "dates": {"registered_at": "2023-10-11", "agreement_date": null, "resolution_date": null},
      "counterparties": [
        {
          "entity_id": "176ad1d2790f8150ac03f6644e52f02c",
          "name": "Avemio AG",
          "seat": "Düsseldorf",
          "registration": {"court": "Amtsgericht Düsseldorf", "register_type": "HRB", "register_number": "82980"},
          "role": {"label": "CONTROLLING", "en": {"short": "Controlling"}, "de": {"short": "Herrschend"}}
        }
      ],
      "description": "Ergebnisabführungsvertrag mit der Avemio AG abgeschlossen.",
      "register_entries": [{"registered_at": "2023-10-11", "description": "..."}]
    },
    "..."
  ],
  "succession": null,
  "control": {
    "controlled_by": [
      {
        "counterparty": {"entity_id": "...", "name": "Avemio AG", "role": {"label": "CONTROLLING", "...": "..."}},
        "via": {"label": "RESULT_TRANSFER", "name": {"en": "Result transfer agreement", "de": "Ergebnisabführungsvertrag"}},
        "loss_absorption_obligation": true,
        "since": "2023-10-11",
        "transaction_ids": ["9254b90f65271482a0cd4babd80814b6"]
      }
    ],
    "controls": [],
    "former": []
  },
  "summary": {
    "total_transactions": 7,
    "by_category": {
      "ENTERPRISE_AGREEMENT": {"count": 5, "name": {"en": "Enterprise agreement", "de": "Unternehmensvertrag"}},
      "MERGER": {"count": 1, "name": {"en": "Merger", "de": "Verschmelzung"}}
    },
    "first_date": "2013-09-03",
    "last_date": "2024-08-14"
  }
}
website_content
"website_content": "# Company Name\n\nStructured Markdown extracted from the company website ..."
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.

Erfordert ein aktives Plus-, Pro- oder Max-Abonnement. Ohne Abonnement liefert der Endpunkt 403 mit error "subscription_required".

Parameter

Όνομα Τύπος Απαιτείται Περιγραφή
api_key string ΑΠΑΙΤΕΙΤΑΙ Το κλειδί API σας. Απαιτείται εάν δεν χρησιμοποιείτε την κεφαλίδα x-api-key ή Bearer token
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 token
q string ΑΠΑΙΤΕΙΤΑΙ Ερώτημα αναζήτησης (ελάχιστο: 2 χαρακτήρες)
skip integer προαιρετικό Αριθμός αποτελεσμάτων προς παράλειψη (προεπιλογή: 0)
limit integer προαιρετικό Αποτελέσματα ανά σελίδα (προεπιλογή: 10, μέγιστο: 30)
filters object προαιρετικό Φιλτράρισμα μόνο κατά postal_code. Μορφή:
ai_mode string προαιρετικό AI-gestützte Suche aktivieren (Wert: on-default). Erhöht die Kosten der Anfrage auf 5 Credits.

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 token
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 OK

Επιτυχές αίτημα

400 Λάθος Αίτημα

Μη έγκυρες παράμετροι

401 Μη Εξουσιοδοτημένο

Μη έγκυρο ή απουσιάζον κλειδί API

402 Απαιτείται Πληρωμή

Ανεπαρκείς πιστώσεις

403 Forbidden

Fehlendes Abonnement (fetch-person), unbestätigte E-Mail oder gesperrter Account

404 Not Found

Kein Unternehmen gefunden — es werden keine Credits berechnet

429 Πάρα Πολλά Αιτήματα

Υπέρβαση ορίου ρυθμού

500 Σφάλμα Διακομιστή

Εσωτερικό σφάλμα διακομιστή

Μορφή Απάντησης Σφάλματος

Fehler werden als JSON zurückgegeben. Abrechnungsbezogene Fehler nutzen ein meta-Objekt; das Feld request_credit_cost zeigt immer, was tatsächlich berechnet wurde (0 bei fehlgeschlagenen Anfragen, außer dem AI-Aufschlag):

402 — Unzureichende Credits

{
  "meta": {
    "message": "Insufficient credits to perform this operation.",
    "request_credit_cost": 25,
    "credits_remaining": 3
  }
}

404 — Unternehmen nicht gefunden

{
  "detail": [
    {
      "type": "not_found",
      "loc": ["path", "q"],
      "msg": "Organization that matches 'Example GmbH' does not exist",
      "input": {"q": "Example GmbH"}
    }
  ],
  "meta": {
    "request_credit_cost": 0,
    "credits_remaining": 1250
  }
}

403 — Abonnement erforderlich (fetch-person)

{
  "error": "subscription_required",
  "meta": {
    "message": "fetch-person requires an active Plus, Pro, or Max subscription.",
    "required_plans": ["plus", "pro", "max"],
    "request_credit_cost": 0,
    "credits_remaining": 1250
  }
}

401 — Nicht autorisiert

{
  "error": "Unauthorized: Missing or invalid authentication. Please provide a valid API key (via x-api-key header or api_key parameter) or Bearer token."
}

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

Zwei Authentifizierungsmethoden werden unterstützt:

API-Schlüssel (Header)

Übermitteln Sie Ihren handelsregister.ai API-Schlüssel als Header — ideal für skriptbasierte Clients und SDKs:

X-API-Key: YOUR_API_KEY

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

OAuth 2.1 (für MCP-Clients wie Claude und ChatGPT)

Clients, die sich interaktiv verbinden (z. B. Claude Custom Connectors, ChatGPT), authentifizieren sich über unseren OAuth-2.1-Autorisierungsserver — ohne manuelles API-Schlüssel-Handling. Der Client entdeckt den Server automatisch, registriert sich selbst (Dynamic Client Registration, RFC 7591) und holt Ihre Zustimmung im Browser ein. Anfragen werden anschließend über Ihr Konto abgerechnet.

Discovery-Endpunkt

https://handelsregister.ai/.well-known/oauth-authorization-server

Unterstützt: authorization_code-Grant mit PKCE, Refresh Tokens, Scopes mcp / api / offline_access. Access Tokens funktionieren auf der REST API wie reguläre Bearer Tokens.

Verfügbare Tools

Der MCP-Server stellt ein Tool pro Datenprodukt bereit. Die Tool-Parameter entsprechen den REST-API-Parametern; Credits werden exakt wie beim entsprechenden REST-Aufruf berechnet:

search_organizations
get_company_overview
get_financials
get_balance_sheet
get_profit_and_loss
get_annual_financial_statements
get_annual_financial_statements_html
get_related_persons
get_shareholders
get_ubos
get_shareholdings
get_mergers_and_acquisitions
get_publications
get_insolvency_publications
get_news
get_website_content
fetch_person
fetch_document

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.