OpenRegister Dokumentation
⌘ K
API wird geprüft v1
Developer APIStable v1

Ein Schema für Register verschiedener Länder.

Suchen Sie Unternehmen in normalisiertem JSON und greifen Sie bei Bedarf auf nationale Felder, Datei und Hash der Primärquelle zurück.

API-Schlüssel erhalten Erste Anfrage senden ↓
PROVENANCE TRACE
  1. 01
    SOURCE FILEregistry.csv
  2. 02
    INTEGRITYsha256 verified
  3. 03
    NORMALIZElegal_entity
  4. 04
    RESPONSEGET /entities/{id}
BASE URLhttps://md.hanta.io/api/v1

Schnellstart

In drei Schritten vom Schlüssel zu den Daten

Alle Datenendpunkte verwenden denselben Authentifizierungsvertrag. Ein SDK ist nicht nötig; ein normaler HTTP-Client genügt.

  1. 1

    Schlüssel erstellen

    Öffnen Sie das API-Konto, benennen Sie die Umgebung und speichern Sie das Geheimnis sofort — es wird nicht erneut angezeigt.

    API-Konto öffnen →
  2. 2

    Schlüssel im Header senden

    Verwenden Sie X-API-Key oder Bearer. In der API-Konsole sind URL und Parameter bereits korrekt gesetzt.

  3. 3

    Anfrage-ID speichern

    Die Antwort enthält X-Request-ID. Geben Sie diese ID dem Support zur Analyse einer bestimmten Anfrage.

Authentifizierung

Der API-Schlüssel gehört zur Umgebung

Erstellen Sie getrennte Schlüssel für Produktion, Staging und Analyse. Jeder Schlüssel handelt für das Konto und verbraucht dessen gemeinsames Monatskontingent.

Empfohlen

X-API-Key

X-API-Key: or_live_…
Kompatible Alternative

Bearer token

Authorization: Bearer or_live_…
Der Schlüssel bleibt ausschließlich bei Ihnen.

OpenRegister speichert nur einen SHA-256-Hash. Legen Sie das Geheimnis nicht in Query-Strings, Frontend-Bundles, Logs oder öffentlichen Repositorys ab.

Registry APIX-API-Key

Serverintegrationen und Datenanfragen.

Account APIClerk session

Konto, Schlüssel und Abonnementverwaltung.

Stripe webhookStripe-Signature

Nur signierte Ereignisse von Stripe.

Paginierung

Seiten mit vorhersehbarer Größe

Die Suche wird nach Name und stabiler ID sortiert. Verwenden Sie die Werte aus meta, statt die Seitenzahl im Client zu berechnen.

page1…N

Nummer der angeforderten Seite.

pageSize1…100

Standardmäßig werden 25 Datensätze zurückgegeben.

meta.totalinteger

Datensatzanzahl für den aktuellen Filter.

meta.pageCountinteger

Anzahl der verfügbaren Seiten.

Limits und Kontingente

Zwei Zähler für jede Anfrage

Das Minutenlimit schützt die API vor Lastspitzen; das Monatskontingent begrenzt den Tarifumfang. Beide Zähler werden nach jeder erfolgreichen Datenanfrage zurückgegeben.

HeaderWert
X-RateLimit-LimitAnfragelimit pro Minute.
X-RateLimit-RemainingVerbleibende Anfragen im aktuellen Fenster.
X-RateLimit-ResetUnix-Zeitstempel für das Zurücksetzen des Fensters.
X-Monthly-Quota-LimitKontingent des Abrechnungszeitraums.
X-Monthly-Quota-RemainingVerbleibende Anfragen im Zeitraum.
X-Monthly-Quota-ResetBeginn des neuen Zeitraums im ISO-8601-Format.
Antwort 429 erhalten?Lesen Sie Retry-After, fügen Sie eine zufällige Verzögerung hinzu und wiederholen Sie die Anfrage.

Fehler

Ein einheitliches Format für alle Endpunkte

Verarbeiten Sie error.code programmatisch und schreiben Sie message in die Logs. requestId verknüpft den Fehler mit der Serveranfrage.

ERROR · 401 
{
  "error": {
    "code": "invalid_api_key",
    "message": "The API key is invalid or revoked",
    "requestId": "69a27c71-44ab-4c0c-a95d-1a1ea8da24cc",
    "docs": "https://md.hanta.io/docs/api"
  }
}
400invalid_request

Parameter oder UUID hat ein ungültiges Format.

401api_key_required

Der Header mit dem API-Schlüssel fehlt.

401invalid_api_key

Der Schlüssel ist unbekannt, widerrufen oder beschädigt.

404entity_not_found

Kein Datensatz mit dieser OpenRegister-ID gefunden.

429rate_limit_exceeded

Das Minutenlimit des Schlüssels ist ausgeschöpft.

429monthly_quota_exceeded

Das Kontingent des Abrechnungszeitraums ist ausgeschöpft.

Versionierung

Die Version ist in der URL verankert

Der aktuelle stabile Vertrag ist /api/v1. Innerhalb von v1 können neue nullable-Felder und Endpunkte hinzukommen; Felder werden jedoch weder entfernt noch ohne neue Version im Typ geändert.

Maschinenlesbarer VertragOpenAPI 3.1 JSON
Herunterladen ↗

API-Referenz

Registry-API-Endpunkte

Alle drei Endpunkte benötigen einen API-Schlüssel und liefern Rate-Limit-Header. Mit „Beispiel anzeigen“ öffnen Sie eine fertige Anfrage in der Konsole.

GET/countries

Länderliste

Derzeit verfügbare und geplante Register.

API key application/json

Keine Parameter erforderlich.

GET/entities

Unternehmen suchen

Suche nach Name oder IDNO mit Filtern und stabiler Paginierung.

API key application/json

Parameter

qstring

Teil des Namens oder der Registernummer, unabhängig von Groß- und Kleinschreibung.

countrystring

Zweistelliger Ländercode nach ISO 3166-1.

legalFormstring

Exakter nationaler Wert der Rechtsform.

activitystring

Tätigkeitscode oder russischer bzw. rumänischer Namensteil.

activityTypeunlicensed | licensed

Tätigkeitsliste: unlicensed oder licensed.

registeredWithin7d | 30d | 90d | 1y

Gleitender Gründungszeitraum: 7, 30, 90 Tage oder 1 Jahr.

registeredFromdate

Inklusives Anfangsdatum im Format YYYY-MM-DD.

registeredTodate

Inklusives Enddatum im Format YYYY-MM-DD.

includeClosedboolean

Geschlossene Unternehmen einbeziehen. Standardmäßig ausgeschlossen.

sortname | newest | updated

Sortierung nach Name, Gründungsdatum oder letzter Aktualisierung.

pageinteger

Seitennummer. Standardwert: 1.

pageSizeinteger

Seitengröße von 1 bis 100. Standardwert: 25.

GET/entities/{id}

Vollständiger Unternehmensdatensatz

Normalisierte Felder, nationaler Datensatz und Quellenherkunft.

API key application/json

Parameter

iduuiderforderlich

OpenRegister-ID aus dem Suchergebnis.

API-Referenz

Entity-Objekt

Normalisierte Felder sind in allen Ländern gleich. Die nationale Struktur bleibt in registry und sourceData; neue Länder ändern daher den gemeinsamen Vertrag nicht.

iduuid

Stabile OpenRegister-ID.

countryCodestring

ISO-3166-1-Alpha-2-Code des Rechtsgebiets.

canonicalNamestring

Name für Suche und Anzeige.

statusstring

Normalisierter Status des Datensatzes.

legalFormstring | null

Nationale Rechtsform.

registryobject

Typisierte und aufgelöste nationale Felder.

sourceDataobject

Originalfelder ohne Verlust oder Umbenennung.

registrationsarray

Registrierungsnummern und lokale Status.

provenanceobject | null

Datei, Hash, Importdatum und URL der Primärquelle.

API-Tarife

Festpreis ohne Mehrverbrauchskosten

Wenn das Kontingent ausgeschöpft ist, stoppt die API Anfragen mit 429 — unerwartete Rechnungen entstehen nicht.

GET/api/v1/plansöffentlich

Free

€0/ Monat

Für Prototypen und die API-Evaluierung

  • 1.000 Anfragen / Zeitraum
  • 60 Anfragen / Minute
  • 1 aktive API-Schlüssel

Pro

Beliebt
9,99 €/ Monat

Für produktive Integrationen

  • 100.000 Anfragen / Zeitraum
  • 600 Anfragen / Minute
  • 5 aktive API-Schlüssel

Business

29,99 €/ Monat

Für große Datenmengen und mehrere Umgebungen

  • 1.000.000 Anfragen / Zeitraum
  • 3.000 Anfragen / Minute
  • 20 aktive API-Schlüssel

Konto-Endpunkte

Konto, Unternehmenslisten und Zustellung

Diese Endpunkte verwalten Konto, Schlüssel, materialisierte Unternehmenslisten und ausgehende Webhooks. Sie verwenden ein Clerk-Token oder Sitzungscookie; ein Registry-API-Schlüssel ist dafür nicht gültig.

GET /api/v1/account

Tarif, Nutzung, Abrechnungsstatus und aktive Schlüssel.

GET /api/v1/auth/me

Profil des aktuellen Clerk-Nutzers.

GET /api/v1/api-keys

Aktive Schlüssel ohne Geheimnisse auflisten.

POST /api/v1/api-keys

Schlüssel erstellen und das vollständige Geheimnis einmalig zurückgeben.

DELETE /api/v1/api-keys/{id}

Schlüssel des aktuellen Kontos widerrufen.

GET /api/v1/saved-searches

Gespeicherte Suchen und aktuelle Ergebnis-URLs auflisten.

POST /api/v1/saved-searches

Kriterien des Unternehmensverzeichnisses speichern.

PUT /api/v1/saved-searches/{id}

Eine gespeicherte Suche vollständig aktualisieren.

DELETE /api/v1/saved-searches/{id}

Eine gespeicherte Suche des aktuellen Kontos löschen.

GET /api/v1/lists

Materialisierte Unternehmenslisten und Datensatzanzahl auflisten.

POST /api/v1/lists

Eine leere Unternehmensliste erstellen.

GET /api/v1/lists/{id}

Liste mit paginierten Unternehmen, Verbindungen und Zustellverlauf abrufen.

PUT /api/v1/lists/{id}

Name und Beschreibung einer Liste ersetzen.

DELETE /api/v1/lists/{id}

Eine Unternehmensliste löschen.

POST /api/v1/lists/{id}/items

Unternehmen hinzufügen und neue Zustellungen einreihen.

DELETE /api/v1/lists/{id}/items/{entityId}

Unternehmen aus einer Liste entfernen.

GET /api/v1/webhook-endpoints

Zustellendpunkte ohne Geheimnisse auflisten.

POST /api/v1/webhook-endpoints

Einen universellen JSON-Webhook-Endpunkt erstellen oder optional die Hanta-Vorlage verwenden.

PATCH /api/v1/webhook-endpoints/{id}

Einen Endpunkt aktivieren oder deaktivieren.

DELETE /api/v1/webhook-endpoints/{id}

Endpunkt deaktivieren und Verlauf beibehalten.

PUT /api/v1/lists/{id}/webhook-endpoints/{endpointId}

Einen Zustellendpunkt mit einer Liste verbinden.

DELETE /api/v1/lists/{id}/webhook-endpoints/{endpointId}

Einen Zustellendpunkt von einer Liste trennen.

POST /api/v1/webhook-deliveries/{id}/retry

Eine fehlgeschlagene Zustellung erneut einreihen.

Dienststatus

GET/api/v1/health/live

Der Prozess läuft und nimmt HTTP-Anfragen an.

GET/api/v1/health/ready

Anwendung und PostgreSQL sind für Datenverkehr bereit.

Stripe-Abrechnung

Checkout und Abonnement

Kostenpflichtige Tarife werden über Stripe Checkout abgeschlossen. Rechnungen, Zahlungsart, Tarifwechsel und Kündigung sind über das Stripe Customer Portal im API-Konto verfügbar.

1CheckoutAbonnement erstellen
→
2WebhookStatus prüfen
→
3EntitlementsNeue API-Limits

Der Zugriff ändert sich erst nach einem signierten Stripe-Webhook-Ereignis, nicht nach der Weiterleitung aus Checkout.

Abrechnungsendpunkte

GET /api/v1/plans

Öffentlicher Tarif- und Leistungsumfangskatalog.

POST /api/v1/billing/checkout

Stripe-Checkout-Sitzung erstellen.

POST /api/v1/billing/portal

Stripe-Customer-Portal-Sitzung erstellen.

POST /api/v1/billing/webhook

Interner Endpunkt mit Stripe-Signature-Header.

Unterstützte Ereignisse
checkout.session.completedcustomer.subscription.createdcustomer.subscription.updatedcustomer.subscription.deletedcustomer.subscription.pausedcustomer.subscription.resumed

Die Ereignis-ID wird vor der Verarbeitung gespeichert, daher ist eine erneute Zustellung sicher. Ein älteres Ereignis überschreibt keinen neueren Abonnementstatus.