v1.0.0 Stabil
Irányítópult

API referencia

Hozzáférés átfogó német vállalati adatokhoz RESTful API-nkon keresztül. Valós idejű információk hivatalos kereskedelmi nyilvántartásokból.

Alap URL
https://handelsregister.ai/api
Formátum
JSON
Hitelesítés
API kulcs
Sebességi korlátok
60/perc (5/perc dokumentumok)

Hitelesítés

A Handelsregister AI API két hitelesítési módszert támogat: API kulcs és Bearer Token. Mindkét módszer működik az összes API végponton.

Hitelesítési módszerek

1. API kulcs hitelesítés

Az API kulcsod két módon adható meg:

a)
Fejléc (Ajánlott): x-api-key: YOUR_API_KEY
b)
Lekérdezési paraméter (Örökölt): ?api_key=YOUR_API_KEY

2. Bearer Token hitelesítés

A fokozott biztonság és token kezelés érdekében API tokeneket hozhat létre:

Engedélyezési fejléc: Authorization: Bearer YOUR_TOKEN

Legjobb gyakorlatok és használati esetek

API kulcs fejlécen keresztül: Ajánlott szerverről-szerverre integrációkhoz és éles környezetben
API kulcs lekérdezési paraméteren keresztül: Csak gyors teszteléshez és visszafelé kompatibilitáshoz
Bearer Token: Legjobb olyan alkalmazásokhoz, amelyek finom hozzáférés-szabályozást, token lejáratot és fokozott biztonságot igényelnek

API kulcs hitelesítési példák

x-api-key fejléc használata (Ajánlott) 
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 kezelés

API token létrehozása
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"
     }'

A válasz tartalmazni fogja a Bearer tokenedet. Tárold biztonságosan!

Bearer Token használata
curl -X GET "https://handelsregister.ai/api/v1/search-organizations?q=company" \
     -H "Authorization: Bearer YOUR_API_TOKEN"
Token kezelési végpontok
  • POST /api/v1/auth/tokens/create - Új token létrehozása
  • GET /api/v1/auth/tokens - Összes token listázása
  • DELETE /api/v1/auth/tokens/{id} - Adott token visszavonása
  • DELETE /api/v1/auth/tokens - Összes token visszavonása

Endpoints

GET

/v1/fetch-organization

5-21 kredit • 60/perc

Szerezzen be átfogó információkat német vállalatról, beleértve a jogi státuszt, pénzügyi adatokat, vezetőséget és egyebeket.

Paraméterek

Név Típus Kötelező Leírás
api_key string Feltételes* Az API kulcsod. Kötelező, ha nem használsz x-api-key fejlécet vagy Bearer tokent
q string KÖTELEZŐ Vállalat neve, regisztrációs szám vagy keresési lekérdezés
feature string opcionális További adat funkció a tartalmazáshoz. Többször is megadható (lásd funkciók táblázatát alább)
ai_search string opcionális AI keresés engedélyezése. Értékek: on-default vagy hagyja a paramétert teljesen üresen
realtime_mode string opcionális Echtzeitmodus für Live-Daten aus dem Handelsregister aktivieren. Werte: handelsregister-default oder Parameter komplett weglassen

Elérhető funkciók

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

Példa kérés

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'

Példa válasz

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

Válasz struktúra részletei

Alapvető vállalati adatok

Mindig tartalmazza: entity_id, name, status, legal_form, address, registration, contact_data, purpose, keywords, products_and_services

financial_kpi

Éves pénzügyi mutatók tömbje (árbevétel, nettó jövedelem, alkalmazottak, stb.) több évből

balance_sheet_accounts

Hierarchikus mérlegadatok eszközök és kötelezettségek bontásával évente

profit_and_loss_account

Részletes eredménykimutatások árbevétel, költségek és nyereség bontásával évente

related_persons

Jelenlegi és korábbi igazgatók/tisztviselők szerepekkel, nevekkel és hivatali időszakokkal

publications

Hivatalos kereskedelmi nyilvántartási publikációk és közlemények

news

Hírcikkek tömbje címmel, forrással, publikálási dátummal és URL-lel

insolvency_publications

Fizetésképtelenségi bírósági publikációk dátumokkal, ügyszámokkal és esemény részletekkel

annual_financial_statements

Teljes éves jelentések markdown formátumban metaadatokkal

annual_financial_statements__html

Vollständige Jahresberichte im HTML-Format mit Metadaten

shareholders Beta

A vállalat részvényeseinek listája tulajdoni százalékokkal és szerepekkel

ubos Beta

Wirtschaftlich Berechtigte (UBOs) mit Beteiligungsquoten, inklusive aufgelöster und nicht aufgelöster Eigentümer sowie Abdeckungsgrad

shareholdings Beta

Aktuelle Beteiligungen dieses Unternehmens an anderen Gesellschaften mit Anteilshöhe, Einlage und Stichtag

website_content

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

GET

/v1/fetch-person

15-20 Credits • 60/min

Personenprofile aus dem deutschen Handelsregister und dem öffentlichen Web zusammenführen. ai_search ist immer aktiv; die Grundkosten von 15 Credits enthalten die AI-Anreicherung bereits.

Parameter

Név Típus Kötelező Leírás
api_key string KÖTELEZŐ Az API kulcsod. Kötelező, ha nem használsz x-api-key fejlécet vagy Bearer tokent
person_q string KÖTELEZŐ Name der Person (min. 2 Zeichen, erforderlich)
organization_q string KÖTELEZŐ Unternehmenskontext zur Disambiguierung gleichnamiger Personen (min. 2 Zeichen, erforderlich)
feature string[] opcionális 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 kredit • 60/perc

Keressen német vállalatokat fejlett szűréssel és lapozási támogatással.

Paraméterek

Név Típus Kötelező Leírás
api_key string Feltételes* Az API kulcsod. Kötelező, ha nem használsz x-api-key fejlécet vagy Bearer tokent
q string KÖTELEZŐ Keresési lekérdezés (min: 2 karakter)
skip integer opcionális Kihagyandó eredmények száma (alapértelmezett: 0)
limit integer opcionális Eredmények oldalanként (alapértelmezett: 10, max: 30)
filters object opcionális Szűrés csak postal_code szerint. Formátum:

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.

Példa kérés

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'

Példa válasz

{
  "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 kredit • 5/perc

Töltsön le hivatalos PDF dokumentumokat a német kereskedelmi nyilvántartásból.

Paraméterek

Név Típus Kötelező Leírás
api_key string Feltételes* Az API kulcsod. Kötelező, ha nem használsz x-api-key fejlécet vagy Bearer tokent
company_id string KÖTELEZŐ Egyedi vállalati entitás azonosító a keresési eredményekből
document_type string KÖTELEZŐ Dokumentum típus. Értékek: shareholders_list, articles_of_association, AD, CD, SI

Példa kérés

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

Válasz

Sikeres (200): PDF fájlt ad vissza közvetlenül

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

Hiba: JSON-t ad vissza hiba részletekkel

Dokumentum típusok

shareholders_list

Részvényesi nyilvántartási dokumentum

articles_of_association

Gesellschaftervertrag / Satzung / Statut Dokument

AD

Aktuális kivonatok (Aktuelle Daten)

CD

Történeti kivonatok (Chronologische Daten)

SI

Strukturierte Inhalte – als XML-Datei zurückgegeben.

Hibakezelés

200 OK

Kérés sikeres

400 Rossz kérés

Érvénytelen paraméterek

401 Jogosulatlan

Érvénytelen vagy hiányzó API kulcs

402 Fizetés szükséges

Elégtelen kreditek

429 Túl sok kérés

Sebességi korlát túllépve

500 Szerver hiba

Belső szerver hiba

Hiba válasz formátum

{
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "Your account has insufficient credits",
    "details": {
      "required": 10,
      "available": 5
    }
  }
}

Python SDK

PyPI GitHub v1.0.0 • Python 3.8+ • MIT licenc
Telepítés 
pip install handelsregister

Alapvető használat

from handelsregister import Handelsregister

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

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

Objektum interfész

from handelsregister import Company

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

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

Adatgazdagítás

client.enrich(
    file_path="companies.csv",
    query_properties={"name": "company_name", "location": "city"},
    features=["financial_kpi", "related_persons"],
    output_format="json"
)

npm SDK

npm GitHub v0.1.0 • Node.js 14+ • MIT Lizenz
Installation 
npm install handelsregister

Grundlegende Nutzung

const { Handelsregister, Company } = require('handelsregister');

const client = new Handelsregister('your-api-key');
const companyData = await client.fetchOrganization('OroraTech GmbH');

console.log(companyData.name);
console.log(companyData.registration);

TypeScript Unterstützung

import { Handelsregister, Company, CompanyData } from 'handelsregister';

const client = new Handelsregister(process.env.API_KEY);

const company: CompanyData = await client.fetchOrganization({
    q: 'Konux GmbH',
    features: ['financial_kpi', 'related_persons']
});

Async/Await Interface

// Using async/await
async function getCompanyInfo() {
    try {
        const company = await client.fetchOrganization('OroraTech GmbH');
        return company;
    } catch (error) {
        console.error('Error fetching company:', error.message);
    }
}

// Multiple companies
const companies = ['OroraTech GmbH', 'Konux GmbH', 'Celonis SE'];
const results = await Promise.all(
    companies.map(name => client.fetchOrganization(name))
);

Datenanreicherung

await client.enrich({
    filePath: 'companies.csv',
    queryProperties: { name: 'company_name', location: 'city' },
    features: ['financial_kpi', 'related_persons'],
    outputFormat: 'json'
});

MCP Server Beta

Universeller MCP (Model Context Protocol) Server für nahtlose Integration mit KI-Agenten und Workflow-Automatisierung.

Server URL
https://mcp.handelsregister.ai/mcp

Kompatibilität & Integration

Unser MCP Server ist mit jedem MCP-kompatiblen Client verwendbar und ermöglicht die einfache Integration von Handelsregister-Daten in Ihre KI-gestützten Workflows.

Hauptfunktionen

  • Universelle Kompatibilität mit allen MCP Clients
  • Echtzeit-Zugriff auf deutsche Unternehmensdaten
  • Perfekt für agentenbasierte Workflows
  • Native Integration mit OpenAI SDK

Verwendung mit OpenAI Python SDK

Der MCP Server kann direkt mit dem OpenAI Python SDK verwendet werden, um Handelsregister-Daten in Ihre KI-Anwendungen zu integrieren:

Python 
import os
from openai import OpenAI

client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])

resp = client.responses.create(
    model="gpt-5",
    input="Gib mir die aktuellsten Finanzdaten der Konux GmbH aus München und gebe diese als Markdown-Tabelle aus.",
    tools=[
        {
            "type": "mcp",
            "server_label": "handelsregister",
            "server_url": "https://mcp.handelsregister.ai/mcp",
            "require_approval": "never",
            "headers": {
                "X-API-Key": os.environ["HANDELSREGISTER_API_KEY"]
            },
        }
    ],
)

print(resp.output_text)

Authentifizierung

Die Authentifizierung erfolgt über Ihren handelsregister.ai API-Schlüssel, der als Header übermittelt wird:

X-API-Key: YOUR_API_KEY

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

Agentenbasierte Workflows

Der MCP Server ermöglicht die nahtlose Integration von Handelsregister-Daten in komplexe agentenbasierte Workflows:

  • • Automatische Datenextraktion und -analyse
  • • Multi-Agenten-Systeme mit Zugriff auf Unternehmensdaten
  • • Workflow-Automatisierung mit Echtzeit-Datenabruf
  • • Integration in bestehende KI-Pipelines

Credits & Preise

MCP-Anfragen verbrauchen dieselben Credits wie direkte API-Aufrufe, basierend auf den angeforderten Features. Die Preise entsprechen exakt den Preisen der Standard-REST-API.

Anforderungen

  • Gültiger handelsregister.ai API-Schlüssel
  • MCP-kompatibler Client (z.B. OpenAI SDK)
  • Python 3.8+ (für OpenAI SDK)

Wichtige Hinweise

  • • Diese Funktion befindet sich derzeit in der Beta-Phase. Funktionalität und API können sich ändern.
  • • Die Credit-Preise entsprechen exakt den Preisen der Standard-REST-API.
  • • Es gelten dieselben Rate Limits wie für die REST API.
  • • Bei Fragen oder Problemen wenden Sie sich bitte an unseren Support.