Αναφορά API
Πρόσβαση σε ολοκληρωμένα δεδομένα γερμανικών επιχειρήσεων μέσω του RESTful API μας. Πληροφορίες σε πραγματικό χρόνο από επίσημα εμπορικά μητρώα.
https://handelsregister.ai/api
JSON
Κλειδί API
60/λεπτό (5/λεπτό έγγραφα)
Πιστοποίηση
Το 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
Σημεία Τέλους
/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
1 πίστωση
annual_financial_statements
5 πιστώσεις
annual_financial_statements__html
5 Credits
shareholders
Beta
ubos
Beta
shareholdings
Beta
website_content
AI
Παράδειγμα Αιτήματος
curl -X GET 'https://handelsregister.ai/api/v1/fetch-organization?q=BMW%20AG&feature=financial_kpi&feature=related_persons&feature=publications&feature=website_content&ai_search=on-default' \
-H 'x-api-key: YOUR_API_KEY'
Παράδειγμα Απάντησης
{
"entity_id": "add84642a957b08a3f252c69c9d063de",
"name": "Polyden-Folienfabrik GmbH",
"status": "INACTIVE",
"legal_form": "GmbH",
"purpose": "Herstellung von Folien...",
"registration_date": "1978-02-23T00:00:00",
"address": {
"house_number": "38",
"street": "Ansbacher Straße",
"postal_code": "91560",
"city": "Heilsbronn",
"coordinates": {
"latitude": 49.33438,
"longitude": 10.78262
}
},
"registration": {
"court": "Ansbach",
"register_type": "HRB",
"register_number": "405"
},
"contact_data": {
"website": "https://www.polyden.de",
"phone_number": "+49 9872 808 0"
},
"financial_kpi": [
{
"year": 2022,
"revenue": 41855558.25,
"net_income": -19668989.99,
"employees": 208
}
],
"related_persons": {
"current": [
{
"name": "Knut Neumann",
"role": {
"en": {"long": "Managing Director"},
"de": {"long": "Geschäftsführer"}
},
"start_date": "2019-06-03"
}
]
},
"publications": [...],
"news": [
{
"title": "Company News Title",
"source": "News Source",
"publication_date": "2023-08-08"
}
],
"meta": {
"request_credit_cost": 55,
"credits_remaining": "73841334"
}
}
Λεπτομέρειες Δομής Απάντησης
Κύρια Δεδομένα Εταιρείας
Πάντα συμπεριλαμβάνονται: entity_id, name, status, legal_form, address, registration, contact_data, purpose, keywords, products_and_services
financial_kpi
Πίνακας ετήσιων οικονομικών δεικτών (έσοδα, καθαρό εισόδημα, υπάλληλοι, κλπ.) που καλύπτει πολλά έτη
balance_sheet_accounts
Ιεραρχικά δεδομένα ισολογισμού με ανάλυση περιουσιακών στοιχείων και υποχρεώσεων ανά έτος
profit_and_loss_account
Λεπτομερείς καταστάσεις κερδών και ζημιών με ανάλυση εσόδων, εξόδων και κερδών ανά έτος
related_persons
Τρέχοντες και παλαιότεροι διευθυντές/στελέχη με ρόλους, ονόματα και περιόδους θητείας
publications
Επίσημες δημοσιεύσεις και ανακοινώσεις εμπορικού μητρώου
news
Πίνακας ειδησεογραφικών άρθρων με τίτλο, πηγή, ημερομηνία δημοσίευσης και URL
insolvency_publications
Δημοσιεύσεις δικαστηρίου αφερεγγυότητας με ημερομηνίες, ID υποθέσεων και λεπτομέρειες γεγονότων
annual_financial_statements
Πλήρεις ετήσιες εκθέσεις σε μορφή 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
website_content
Unternehmens-Website als strukturiertes Markdown, optimiert für LLM-Verarbeitung (nur AI Mode, 0 Credits)
/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. Μορφή: |
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
Ανεπαρκείς πιστώσεις
Υπέρβαση ορίου ρυθμού
Εσωτερικό σφάλμα διακομιστή
Μορφή Απάντησης Σφάλματος
{
"error": {
"code": "INSUFFICIENT_CREDITS",
"message": "Your account has insufficient credits",
"details": {
"required": 10,
"available": 5
}
}
}
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
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.