Podstawowe pojęcia
Co wystarczy zrozumieć raz, by pewnie obsłużyć każdą odpowiedź.
Osiem pojęć niesie całe API. Gdy je znasz, poprawnie odczytujesz każdą odpowiedź i wiesz z góry, ile kosztuje zapytanie.
Jednoznaczne znajdowanie firm
Parametr q w fetch-organization przyjmuje trzy rodzaje danych wejściowych. Przykłady na tej stronie to zapytania o Hetzner Online GmbH, Ansbach HRB 6089:
| Dane wejściowe | Przykład | Kiedy pasuje |
|---|---|---|
| Nazwa firmy |
Hetzner Online GmbH |
Na początek. Wpisz nazwę tak pełną, jak stoi w rejestrze. |
| Sąd rejestrowy i numer rejestru |
Ansbach HRB 6089 |
Jednoznaczne dla każdej zarejestrowanej firmy. Sąd, typ rejestru i numer należą do siebie. |
| entity_id |
94eb910fef13f94585c48c263fa446d4 |
Do kolejnych zapytań. Dostajesz je w każdej odpowiedzi. |
Sam numer rejestru nie wystarcza, bo każdy sąd rejestrowy nadaje własne numery. Kolejność jest natomiast dowolna: w przykładzie HRB 6089 Ansbach znajduje tę samą firmę.
curl -G "https://handelsregister.ai/api/v1/fetch-organization" \ -H "x-api-key: TWOJ_KLUCZ_API" \ --data-urlencode 'q=Ansbach HRB 6089'
import requests response = requests.get( "https://handelsregister.ai/api/v1/fetch-organization", headers={"x-api-key": "TWOJ_KLUCZ_API"}, params={ "q": "Ansbach HRB 6089", }, ) data = response.json()
const url = new URL("https://handelsregister.ai/api/v1/fetch-organization"); url.searchParams.append("q", "Ansbach HRB 6089"); const response = await fetch(url, { headers: { "x-api-key": "TWOJ_KLUCZ_API" }, }); const data = await response.json();
entity_id.
Jeśli API nie znajdzie firmy, odpowiada 404 i nic nie nalicza. Dla nieprecyzyjnych danych jest tryb AI (ai_search=on-default): znajduje firmę także po fragmentach nazwy i wyszukuje ją w sieci. Kosztuje dodatkowo 20 kredytów, nawet jeśli nie znajdzie firmy. Aby dostać kilku kandydatów naraz, użyj Wyszukiwania i eksportu.
Features
Każdy profil firmy zawiera dane podstawowe, m.in. nazwę, formę prawną, status, wpis do rejestru, adres, przedmiot działalności, branżę, kapitał i zasady reprezentacji. Wszystko inne zamawiasz jako feature, np. related_persons dla członków zarządu lub financial_kpi dla KPI finansowych.
Kilka features przekazujesz powtarzanym feature albo jako listę: features=related_persons,financial_kpi. Każdy feature pojawia się w odpowiedzi pod własnym kluczem. Tylko publications nazywa się tam history.
curl -G "https://handelsregister.ai/api/v1/fetch-organization" \ -H "x-api-key: TWOJ_KLUCZ_API" \ --data-urlencode 'q=Hetzner Online GmbH' \ --data-urlencode 'feature=related_persons' \ --data-urlencode 'feature=financial_kpi'
import requests response = requests.get( "https://handelsregister.ai/api/v1/fetch-organization", headers={"x-api-key": "TWOJ_KLUCZ_API"}, params={ "q": "Hetzner Online GmbH", "feature": ["related_persons", "financial_kpi"], }, ) data = response.json()
const url = new URL("https://handelsregister.ai/api/v1/fetch-organization"); url.searchParams.append("q", "Hetzner Online GmbH"); url.searchParams.append("feature", "related_persons"); url.searchParams.append("feature", "financial_kpi"); const response = await fetch(url, { headers: { "x-api-key": "TWOJ_KLUCZ_API" }, }); const data = await response.json();
API ignoruje nieznane nazwy bez komunikatu o błędzie, więc sprawdzaj pisownię. Features, których nie obejmuje twój plan, są pomijane i nienaliczane.
Wszystkie features z cenami znajdziesz w fetch-organization, każde pole w Katalogu danych.
Kredyty
Zapytania o dane kosztują kredyty. Dla profilu firmy obowiązują te zasady:
- Cena bazowa 5 kredytów obowiązuje, gdy API zwraca firmę.
- Feature kosztuje kredyty tylko wtedy, gdy zwraca dane w odpowiedzi. Pusty feature jest bezpłatny, także
insolvency_publicationsbez wpisów. - Tryb czasu rzeczywistego i tryb AI nie są features, lecz dopłatami z własnymi zasadami:
- Tryb czasu rzeczywistego kosztuje dodatkowo 10 kredytów, gdy tylko pobranie na żywo się powiedzie. Dotyczy to także sytuacji, gdy nie pokazuje nic nowego.
- Tryb AI kosztuje dodatkowo 20 kredytów, nawet jeśli nie znajdzie firmy. Dopłata odpada tylko wtedy, gdy API przerywa zapytanie z kodem 408, bo trwa ono za długo.
- Wszystkie inne błędy nic nie kosztują.
Zasadę dla każdego pojedynczego feature znajdziesz w Rozliczaniu, ceny w fetch-organization.
Przykład: dane podstawowe z related_persons i financial_kpi kosztują 5 + 2 + 1 = 8 kredytów, jeśli oba features zwracają dane.
Przed każdym zapytaniem API sprawdza, czy twoje saldo pokrywa najwyższą możliwą cenę. Jeśli nie, API odpowiada 402 i nic nie nalicza. Co faktycznie naliczono, stoi w meta.request_credit_cost, twoje saldo po zapytaniu w meta.credits_remaining.
1{2 "meta": {3 "request_credit_cost": 5,4 "credits_remaining": 1455 }6}
Kredyty dostajesz jako kredyty startowe, co miesiąc w subskrypcji kredytów albo jednorazowo jako doładowanie. Bez subskrypcji kredyty startowe i z doładowań są ważne przez 30 dni; przy aktywnej subskrypcji nie wygasają. Wszystko inne w Rozliczaniu.
Aktualność danych i tryb czasu rzeczywistego
Domyślnie profil firmy pochodzi z naszej bazy danych. Jak aktualna jest dana informacja, zależy od jej źródła.
Handelsregister
Dane podstawowe, osoby i obwieszczenia rejestrowe utrzymujemy w naszej bazie na bieżąco z rejestru. To szybkie i wystarcza do większości zastosowań.
W trybie czasu rzeczywistego (realtime_mode=handelsregister-default) API pobiera Aktueller Abdruck (AD, odpis aktualny) na żywo z Handelsregister (rejestr handlowy) w chwili twojego zapytania i zwraca go jako JSON. Dostajesz też aktualnie wpisane osoby w related_persons.current, bez płacenia za feature.
Czy pobranie na żywo się udało, pokazuje _realtime_mode.status. 10 kredytów za tryb czasu rzeczywistego naliczamy tylko przy success.
curl -G "https://handelsregister.ai/api/v1/fetch-organization" \ -H "x-api-key: TWOJ_KLUCZ_API" \ --data-urlencode 'q=Hetzner Online GmbH' \ --data-urlencode 'realtime_mode=handelsregister-default'
import requests response = requests.get( "https://handelsregister.ai/api/v1/fetch-organization", headers={"x-api-key": "TWOJ_KLUCZ_API"}, params={ "q": "Hetzner Online GmbH", "realtime_mode": "handelsregister-default", }, ) data = response.json()
const url = new URL("https://handelsregister.ai/api/v1/fetch-organization"); url.searchParams.append("q", "Hetzner Online GmbH"); url.searchParams.append("realtime_mode", "handelsregister-default"); const response = await fetch(url, { headers: { "x-api-key": "TWOJ_KLUCZ_API" }, }); const data = await response.json();
1{2 "name": "Hetzner Online GmbH",3 "_realtime_mode": {4 "mode": "handelsregister-default",5 "status": "success"6 },7 "related_persons": {8 "current": [9 {10 "entity_id": "78ad32e16ff779f589a9e88d23356f74",11 "label": "MANAGING_DIRECTOR",12 "role": {13 "en": {14 "long": "Managing Director",15 "short": "MD"16 },17 "de": {18 "long": "Geschäftsführer",19 "short": "GF"20 }21 },22 "name": "Max Mustermann",23 "name_parts": {24 "given": "Max",25 "family": "Mustermann",26 "maiden": null,27 "canonical_name": "Mustermann, Max",28 "aliases": [29 "Mustermann, Max"30 ],31 "previous_names": null32 },33 "start_date": null,34 "end_date": null,35 "birth_date": "1976-01-15",36 "location": {37 "home": {38 "city": "Musterheim"39 }40 },41 "organization_representation_scheme": {42 "current": [43 "Ist nur ein Geschäftsführer bestellt, so vertritt er die Gesellschaft allein. Sind mehrere Geschäftsführer bestellt, so wird die Gesellschaft durch zwei Geschäftsführer oder durch einen Geschäftsführer gemeinsam mit einem Prokuristen vertreten."44 ],45 "history": []46 },47 "role_representation_scheme": {48 "current": [49 "einzelvertretungsberechtigt",50 "mit der Befugnis, im Namen der Gesellschaft mit sich im eigenen Namen oder als Vertreter eines Dritten Rechtsgeschäfte abzuschließen"51 ],52 "history": []53 }54 },55 {56 "entity_id": "73549375ff7d709b9e7e2941ad1ffaa3",57 "label": "MANAGING_DIRECTOR",58 "role": {59 "en": {60 "long": "Managing Director",61 "short": "MD"62 },63 "de": {64 "long": "Geschäftsführer",65 "short": "GF"66 }67 },68 "name": "Paul Musterwald",69 "name_parts": {70 "given": "Paul",71 "family": "Musterwald",72 "maiden": null,73 "canonical_name": "Musterwald, Paul",74 "aliases": [75 "Musterwald, Paul"76 ],77 "previous_names": null78 },79 "start_date": null,80 "end_date": null,81 "birth_date": "1989-07-18",82 "location": {83 "home": {84 "city": "Probebrück"85 }86 },87 "organization_representation_scheme": {88 "current": [89 "Ist nur ein Geschäftsführer bestellt, so vertritt er die Gesellschaft allein. Sind mehrere Geschäftsführer bestellt, so wird die Gesellschaft durch zwei Geschäftsführer oder durch einen Geschäftsführer gemeinsam mit einem Prokuristen vertreten."90 ],91 "history": []92 },93 "role_representation_scheme": {94 "current": [95 "einzelvertretungsberechtigt"96 ],97 "history": []98 }99 },100 {101 "entity_id": "cfecded2c1d17946c8ab0379aa786eed",102 "label": "MANAGING_DIRECTOR",103 "role": {104 "en": {105 "long": "Managing Director",106 "short": "MD"107 },108 "de": {109 "long": "Geschäftsführer",110 "short": "GF"111 }112 },113 "name": "Jan Musterhuber",114 "name_parts": {115 "given": "Jan",116 "family": "Musterhuber",117 "maiden": null,118 "canonical_name": "Musterhuber, Jan",119 "aliases": [120 "Musterhuber, Jan"121 ],122 "previous_names": null123 },124 "start_date": null,125 "end_date": null,126 "birth_date": "1955-11-06",127 "location": {128 "home": {129 "city": "Probeingen"130 }131 },132 "organization_representation_scheme": {133 "current": [134 "Ist nur ein Geschäftsführer bestellt, so vertritt er die Gesellschaft allein. Sind mehrere Geschäftsführer bestellt, so wird die Gesellschaft durch zwei Geschäftsführer oder durch einen Geschäftsführer gemeinsam mit einem Prokuristen vertreten."135 ],136 "history": []137 },138 "role_representation_scheme": {139 "current": [140 "einzelvertretungsberechtigt"141 ],142 "history": []143 }144 }145 ]146 },147 "meta": {148 "request_credit_cost": 15,149 "credits_remaining": 145150 }151}
Jeśli pobranie na żywo się nie uda, API zwraca zapisane dane z naszej bazy. Poznasz to po _realtime_mode.status, który wtedy nie jest success. Tryb czasu rzeczywistego nie jest wtedy naliczany, co pokazuje też meta.request_credit_cost.
Tryb czasu rzeczywistego opłaca się, gdy liczy się stan na dziś. Na przykład sprawdzasz nowych partnerów biznesowych przed podpisaniem umowy albo chcesz wiedzieć, kto może w tej chwili reprezentować firmę.
Sprawozdania finansowe
Codziennie szukamy nowo opublikowanych sprawozdań finansowych. Firmy mają jednak do dwunastu miesięcy po końcu roku obrotowego na ich publikację (§ 325 HGB), a wiele wykorzystuje pełny termin. Niektóre firmy celowo przekraczają ustawowy termin i publikują jeszcze później.
Najnowsze sprawozdanie dotyczy więc często roku przedostatniego. Więcej w Aktualności.
Obwieszczenia upadłościowe
Sądy upadłościowe publikują obwieszczenia zwykle w dniu postanowienia lub krótko po nim. Dostajesz je przez feature insolvency_publications, każde z sądem, sygnaturą akt i datą.
Wiadomości
Feature news zwraca wiadomości o firmie z sieci, z tytułem, źródłem, datą i linkiem. Ich aktualność zależy od tego, kiedy ostatnio pisano o firmie. Dla małych firm pasujących doniesień jest często niewiele.
Historia i ważność
Wiele informacji zmienia się z czasem. API zwraca więc obok siebie stan bieżący i historię:
currentto stan na dziś.historywymienia każdy wpisany stan zeffective_fromieffective_to. Jeślieffective_toma wartośćnull, stan obowiązuje do dziś.- Osoby są w
related_persons.currentirelated_persons.past, każda zstart_dateiend_date.
Każda informacja z historią pochodzi z rejestrów i publikacji, np. z Chronologischer Abdruck (CD, odpis chronologiczny) z Handelsregister albo ze wszystkich opublikowanych sprawozdań finansowych.
Tak wygląda to w naszym przykładzie dla zasad reprezentacji Hetzner Online GmbH. W przykładowej odpowiedzi do 28 lipca 2015 wymieniają one zarząd (Vorstand), a od tego czasu członków zarządu (Geschäftsführer):
1{2 "representation_scheme": {3 "current": [4 "Ist nur ein Geschäftsführer bestellt, so vertritt er die Gesellschaft allein. Sind mehrere Geschäftsführer bestellt, so wird die Gesellschaft durch zwei Geschäftsführer oder durch einen Geschäftsführer gemeinsam mit einem Prokuristen vertreten."5 ],6 "history": [7 {8 "value": [9 "Ist nur ein Vorstandsmitglied bestellt, so vertritt es die Gesellschaft allein. Sind mehrere Vorstandsmitglieder bestellt, so wird die Gesellschaft durch zwei Vorstandsmitglieder oder durch ein Vorstandsmitglied gemeinsam mit einem Prokuristen vertreten."10 ],11 "effective_from": "2002-10-15",12 "effective_to": "2015-07-28"13 },14 {15 "value": [16 "Ist nur ein Geschäftsführer bestellt, so vertritt er die Gesellschaft allein. Sind mehrere Geschäftsführer bestellt, so wird die Gesellschaft durch zwei Geschäftsführer oder durch einen Geschäftsführer gemeinsam mit einem Prokuristen vertreten."17 ],18 "effective_from": "2015-07-28",19 "effective_to": null20 }21 ]22 }23}
Większość dat ma format YYYY-MM-DD. Jak daleko wstecz sięga historia, opisuje Wiek i historia.
Puste wartości
Nie każda firma ma wartość w każdym polu. API pokazuje to na dwa sposoby:
null: dla tego pola nie ma wartości.[]: lista nie ma wpisów, np. brak obwieszczeń upadłościowych.
Zamówiony feature bez danych przychodzi jako null lub [] i nic nie kosztuje.
1{2 "name": "dm-drogerie markt GmbH + Co. KG",3 "legal_form": "GmbH & Co. KG",4 "contact_data": {5 "website": "https://www.dm.de",6 "phone_number": "+49 721 55920",7 "email": null8 },9 "capital": {10 "current": null,11 "history": []12 },13 "mergers_and_acquisitions": null,14 "insolvency_publications": []15}
W swoim kodzie traktuj brakujący klucz, null i [] tak samo, bo niektóre puste obiekty przychodzą jako []. Odczytuj też pola po nazwach, bo kolejność kluczy nie jest stała.
Jeśli brakuje wartości, firma zwykle w ogóle nie musi jej publikować. Czego prawo wymaga zależnie od formy prawnej i wielkości, opisuje Dostępność danych. Niektóre informacje celowo ukrywamy; mają wtedy redacted: true.
Stabilność i wersje
API rośnie addytywnie. Nowe dane i features pojawiają się jako nowe pola. Nigdy nie usuwamy istniejących pól, nie zmieniamy ich nazw ani typu czy znaczenia. Dzięki temu każda wersja pozostaje wstecznie kompatybilna.
Zmiany, które zepsułyby istniejący kod, pojawiają się tylko w nowej wersji API, np. pod /v2. Obecna wersja działa pod /v1.
Niech więc twój klient ignoruje nieznane pola i traktuje nieznane wartości jak przypadek ogólny. Nowe pola i features znajdziesz w Changelogu.
Plany
Z Profilu firmy, Dokumentów, Wyszukiwania i eksportu oraz Signals korzystasz na każdym koncie, także bez subskrypcji kredytów. Subskrypcja kredytów daje co miesiąc nowe kredyty i odblokowuje więcej danych:
| Co dostajesz dodatkowo | Plus | Pro | Max |
|---|---|---|---|
| Profil osoby: Funkcje i udziały osób | w zestawie | w zestawie | w zestawie |
| Wyszukiwanie i eksport: Filtry według właścicieli, zarządu i niewypłacalności | brak | w zestawie | w zestawie |
| Profil firmy: Ponad 90 rozszerzonych wskaźników finansowych | brak | w zestawie | w zestawie |
| Profil firmy: Sprawozdania z działalności dostawców energii (§ 6b EnWG) | brak | brak | w zestawie |
Profil firmy: Szczegółowe dane wspólników (shareholders_deep) |
brak | brak | w zestawie |
Sieć powiązań firmy (network) |
brak | w zestawie | w zestawie |
| Signals: Niewypłacalności | brak | w zestawie | w zestawie |
| Signals: Przekształcenia i M&A | brak | brak | w zestawie |
API pomija features spoza twojego planu bez błędu i ich nie nalicza. Profile osób i filtry wyszukiwania spoza planu odrzuca z kodem 403, także bezpłatnie. W Signals dotyczy to tematów, o które pytasz jawnie; bez tego dostajesz po prostu wszystkie tematy swojego planu.
Ceny i kredyty planów znajdziesz na stronie z cenami.