Grundbegriffe

Der Parameter q von fetch-organization nimmt drei Arten von Angaben. Die Beispiele auf dieser Seite sind Anfragen für die Hetzner Online GmbH, Ansbach HRB 6089:

Die Registernummer allein reicht nicht, denn jedes Registergericht vergibt eigene Nummern. Die Reihenfolge ist dagegen frei: HRB 6089 Ansbach findet im Beispiel dieselbe Firma.

Findet die API keine Firma, antwortet sie mit 404 und berechnet nichts. Für unscharfe Angaben gibt es den AI-Mode (ai_search=on-default): Er findet die Firma auch aus Namensteilen und recherchiert dazu im Web. Er kostet 20 Credits zusätzlich, auch wenn er keine Firma findet. Mehrere Kandidaten auf einmal liefert Suche & Export.

Jedes Firmenprofil enthält die Basisdaten, darunter Name, Rechtsform, Status, Registereintrag, Anschrift, Gegenstand, Branche, Kapital und Vertretungsregelung. Alles Weitere forderst du als Feature an, etwa related_persons für die Geschäftsführung oder financial_kpi für die Finanz-KPIs.

Mehrere Features gibst du mit wiederholtem feature an oder als Liste: features=related_persons,financial_kpi. Jedes Feature steht in der Antwort unter seinem eigenen Schlüssel. Nur publications heißt dort history.

Unbekannte Namen ignoriert die API ohne Fehlermeldung, prüf also die Schreibweise. Features, die dein Plan nicht enthält, lässt sie weg und berechnet sie nicht.

Alle Features mit Preis stehen bei fetch-organization, jedes Feld im Datenkatalog.

Datenabrufe kosten Credits. Für ein Firmenprofil gelten diese Regeln:

• Der Grundpreis von 5 Credits fällt an, wenn die API eine Firma liefert.
• Ein Feature kostet nur, wenn es in der Antwort Daten liefert. Ein leeres Feature ist kostenlos, auch insolvency_publications ohne Einträge.
• Echtzeit und AI-Mode sind keine Features, sondern Aufschläge mit eigenen Regeln:
  • Echtzeit kostet 10 Credits zusätzlich, sobald der Live-Abruf gelingt. Das gilt auch, wenn er nichts Neues zeigt.
  • Der AI-Mode kostet 20 Credits zusätzlich, auch wenn er keine Firma findet. Nur wenn die API die Anfrage mit 408 abbricht, weil sie zu lange dauert, entfällt der Aufschlag.
• Alle anderen Fehler kosten nichts.

Die Regel für jedes einzelne Feature steht unter Abrechnung, die Preise bei fetch-organization.

Ein Beispiel: Die Basisdaten mit related_persons und financial_kpi kosten 5 + 2 + 1 = 8 Credits, wenn beide Features Daten liefern.

Vor jeder Anfrage prüft die API, ob dein Guthaben für den höchstmöglichen Preis reicht. Reicht es nicht, antwortet die API mit 402 und berechnet nichts. Was tatsächlich berechnet wurde, steht in meta.request_credit_cost, dein Guthaben danach in meta.credits_remaining.

Credits bekommst du als Startcredits, mit einem Credit-Abo jeden Monat neu oder einmalig als Top-up Credits. Ohne Credit-Abo gelten Startcredits und Top-up Credits 30 Tage, mit aktivem Abo verfallen sie nicht. Alles Weitere steht unter Abrechnung.

Ohne weitere Angabe kommt das Firmenprofil aus unserem Datenbestand. Wie aktuell eine Angabe ist, hängt von ihrer Quelle ab.

Basisdaten, Personen und Registerbekanntmachungen halten wir in unserem Datenbestand aus dem Register aktuell. Das geht schnell und reicht für die meisten Zwecke.

Mit Echtzeit (realtime_mode=handelsregister-default) holt die API im Moment der Anfrage den Aktuellen Abdruck (AD) live aus dem Handelsregister und liefert ihn als JSON. Du bekommst dabei die aktuell eingetragenen Personen unter related_persons.current, ohne das Feature extra zu bezahlen.

Ob der Live-Abruf geklappt hat, zeigt _realtime_mode.status. Nur bei success berechnen wir die 10 Credits für Echtzeit.

Gelingt der Live-Abruf nicht, liefert die API die gespeicherten Daten aus unserem Datenbestand. Du erkennst das an _realtime_mode.status, das dann nicht success lautet. Echtzeit wird dann nicht berechnet, das zeigt auch meta.request_credit_cost.

Echtzeit lohnt sich, wenn es auf den Stand von heute ankommt. Du prüfst damit etwa neue Geschäftspartner vor einer Unterschrift oder siehst, wer die Firma gerade vertreten darf.

Neu veröffentlichte Jahresabschlüsse suchen wir täglich. Firmen haben für die Veröffentlichung aber bis zu zwölf Monate nach dem Ende des Geschäftsjahres Zeit (§ 325 HGB), und viele nutzen die Frist aus. Einzelne Firmen halten die gesetzliche Frist bewusst nicht ein und veröffentlichen noch später.

Der neueste Abschluss betrifft deshalb oft das vorletzte Geschäftsjahr. Mehr dazu unter Aktualität.

Die Insolvenzgerichte veröffentlichen ihre Bekanntmachungen meist am Tag der Entscheidung oder kurz danach. Du bekommst sie über das Feature insolvency_publications, jeweils mit Gericht, Aktenzeichen und Datum.

Das Feature news liefert Nachrichten über die Firma aus dem Web, mit Titel, Quelle, Datum und Link. Wie aktuell sie sind, hängt davon ab, wann zuletzt über die Firma berichtet wurde. Zu kleinen Firmen gibt es oft nur wenige passende Meldungen.

Viele Angaben ändern sich mit der Zeit. Die API liefert deshalb den aktuellen Stand und die Historie nebeneinander:

• current ist der Stand von heute.
• history listet jeden eingetragenen Stand mit effective_from und effective_to. Ist effective_to null, gilt der Stand bis heute.
• Personen stehen in related_persons.current und related_persons.past, jeweils mit start_date und end_date.

Jede Angabe mit Historie stammt aus den Registern und Veröffentlichungen, etwa aus dem Chronologischen Abdruck (CD) des Handelsregisters oder aus allen veröffentlichten Jahresabschlüssen.

So sieht das in unserem Beispiel für die Vertretungsregelung der Hetzner Online GmbH aus. In der Beispielantwort nennt sie bis zum 28.07.2015 den Vorstand, seitdem die Geschäftsführer:

Die meisten Datumsangaben kommen im Format JJJJ-MM-TT. Wie weit die Historie zurückreicht, steht unter Alter und Historie.

Nicht jede Firma hat zu jedem Feld eine Angabe. Die API zeigt das auf zwei Arten:

• null: Für dieses Feld liegt kein Wert vor.
• []: Die Liste hat keine Einträge, etwa keine Insolvenzbekanntmachungen.

Ein angefordertes Feature ohne Daten kommt als null oder [] und kostet nichts.

Behandle in deinem Code einen fehlenden Schlüssel, null und [] gleich, denn manche leeren Objekte kommen als []. Lies Felder außerdem über ihre Namen, denn die Reihenfolge der Schlüssel steht nicht fest.

Fehlt ein Wert, muss die Firma ihn meist gar nicht veröffentlichen. Was das Gesetz je nach Rechtsform und Größe verlangt, steht unter Datenverfügbarkeit. Einzelne Angaben halten wir bewusst zurück; sie tragen dann redacted: true.

Die API wächst additiv. Neue Daten und Features kommen als neue Felder dazu. Bestehende Felder entfernen wir nie, wir benennen sie nicht um und ändern weder ihren Typ noch ihre Bedeutung. So bleibt jede Version abwärtskompatibel.

Änderungen, die bestehenden Code brechen würden, gibt es nur in einer neuen API-Version, etwa unter /v2. Die aktuelle Version läuft unter /v1.

Lass deinen Client deshalb unbekannte Felder ignorieren und unbekannte Werte als allgemeinen Fall behandeln. Neue Felder und Features stehen im Changelog.

Firmenprofil, Dokumente, Suche & Export und Signals nutzt du mit jedem Konto, auch ohne Credit-Abo. Ein Credit-Abo bringt jeden Monat neue Credits und schaltet weitere Daten frei:

Features außerhalb deines Plans lässt die API ohne Fehler weg und berechnet sie nicht. Personenprofile und Suchfilter außerhalb deines Plans lehnt sie mit 403 ab, ebenfalls ohne Kosten. Bei Signals gilt das für Themen, die du ausdrücklich anfragst; ohne Angabe bekommst du einfach alle Themen deines Plans.

Preise und Credits der Pläne findest du in der Preisübersicht.