Αναφορά API
Πρόσβαση σε ολοκληρωμένα δεδομένα γερμανικών επιχειρήσεων μέσω του RESTful API μας. Πληροφορίες σε πραγματικό χρόνο από επίσημα εμπορικά μητρώα.
https://handelsregister.ai/api
JSON
Κλειδί API
60/λεπτό (5/λεπτό έγγραφα)
Schnellstart
In drei Schritten zum ersten Unternehmensprofil.
-
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
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
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 σας μπορεί να παρασχεθεί με δύο τρόπους:
x-api-key: YOUR_API_KEY
?api_key=YOUR_API_KEY
2. Πιστοποίηση Bearer Token
Για ενισχυμένη ασφάλεια και διαχείριση token, μπορείτε να δημιουργήσετε API tokens:
Authorization: Bearer YOUR_TOKEN
Βέλτιστες Πρακτικές & Περιπτώσεις Χρήσης
Παραδείγματα Πιστοποίησης Κλειδιού API
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- Δημιουργία νέου tokenGET /api/v1/auth/tokens- Λίστα όλων των tokensDELETE /api/v1/auth/tokens/{id}- Ανάκληση συγκεκριμένου tokenDELETE /api/v1/auth/tokens- Ανάκληση όλων των tokens
Σημεία Τέλους
| 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/λεπτό |
/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
ubos
Beta
shareholdings
Beta
mergers_and_acquisitions
Beta
website_content
AI
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 ..."/v1/fetch-person
15-20 Credits • 60/minPersonenprofile 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 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
/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.
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_fromdate - Frühestes Registrierungsdatum (ISO 8601, YYYY-MM-DD).
-
registration_date_todate - Spätestes Registrierungsdatum (ISO 8601, YYYY-MM-DD).
-
legal_form_codestring / array - Deutscher Rechtsformcode, z. B. GmbH, AG, e.V., UG. Einzelner String oder Array.
-
industry_codestring / array - NACE/WZ-Branchencode. Einzelner String oder Array.
-
industry_schemestring - Klassifikationsschema zu industry_code. Standard: WZ2025.
-
activeboolean - true = nur aktive Unternehmen, false = nur inaktive. Weglassen für beide.
Standort
5-
postal_codestring - Deutsche 5-stellige Postleitzahl (PLZ).
-
citystring - Stadtname.
-
statestring - Deutsches Bundesland (z. B. Bayern, Hessen).
-
location_coordinatescoordinates - WGS84-Dezimalkoordinaten als Mittelpunkt für die Geo-Suche.
-
location_max_distance_kmnumber - Radius in km (1–100). Erfordert location_coordinates.
Gericht & Register
3-
registration_typestring / array - Registertyp: HRA, HRB, GnR, PR oder VR. Einzelner String oder Array.
-
registration_authority_namestring - Name des Gerichts/Registergerichts (z. B. München).
-
registration_numberstring - Registernummer (z. B. HRB 12345).
Größe & Mitarbeiter
2-
company_size_categoryenum - Größenklasse: micro, small, medium oder large.
-
emp_countrange - Mitarbeiterzahl-Bereich.
Bilanz
7-
bs_assets_totalEUR range - Bilanzsumme, in EUR.
-
bs_equity_totalEUR range - Eigenkapital, in EUR.
-
bs_liabilities_totalEUR range - Gesamtverbindlichkeiten, in EUR.
-
bs_cash_and_equivalentsEUR range - Kassenbestand & Zahlungsmitteläquivalente, in EUR.
-
bs_cash_to_liabilitiesdecimal range - Liquiditätsgrad (Kassenbestand ÷ Verbindlichkeiten), Dezimalwert.
-
bs_equity_ratioratio (0–1) - Eigenkapitalquote (Eigenkapital ÷ Bilanzsumme), Dezimalwert 0–1.
-
bs_debt_to_assetsratio (0–1) - Fremdkapitalquote (Schulden ÷ Bilanzsumme), Dezimalwert 0–1.
Gewinn- und Verlustrechnung
3-
pl_revenueEUR range - Jahresumsatz, in EUR.
-
pl_net_incomeEUR range - Jahresüberschuss, in EUR.
-
pl_ebitEUR 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"
}
}
/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.
Διαχείριση Σφαλμάτων
Επιτυχές αίτημα
Μη έγκυρες παράμετροι
Μη έγκυρο ή απουσιάζον κλειδί API
Ανεπαρκείς πιστώσεις
Fehlendes Abonnement (fetch-person), unbestätigte E-Mail oder gesperrter Account
Kein Unternehmen gefunden — es werden keine Credits berechnet
Υπέρβαση ορίου ρυθμού
Εσωτερικό σφάλμα διακομιστή
Μορφή Απάντησης Σφάλματος
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
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 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.
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:
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:
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.