Peruskäsitteet – Dokumentaatio

Löydä yritykset yksiselitteisesti

Päätepisteen fetch-organization parametri q ottaa kolmenlaisia syötteitä. Tämän sivun esimerkit ovat pyyntöjä yrityksestä Hetzner Online GmbH, Ansbach HRB 6089:

Löydä yritykset yksiselitteisesti
Syöte	Esimerkki	Milloin sopii
Toiminimi	`Hetzner Online GmbH`	Alkuun. Kirjoita nimi niin täydellisenä kuin se on rekisterissä.
Rekisterituomioistuin ja rekisterinumero	`Ansbach HRB 6089`	Yksiselitteinen jokaiselle rekisteröidylle yritykselle. Tuomioistuin, rekisterityyppi ja numero kuuluvat yhteen.
entity_id	`94eb910fef13f94585c48c263fa446d4`	Jatkopyyntöihin. Saat sen jokaisessa vastauksessa.

Pelkkä rekisterinumero ei riitä, koska jokainen rekisterituomioistuin antaa omat numeronsa. Järjestys sen sijaan on vapaa: esimerkissä HRB 6089 Ansbach löytää saman yrityksen.

curl -G "https://handelsregister.ai/api/v1/fetch-organization" \
  -H "x-api-key: SINUN_API_AVAIMESI" \
  --data-urlencode 'q=Ansbach HRB 6089'

import requests

response = requests.get(
    "https://handelsregister.ai/api/v1/fetch-organization",
    headers={"x-api-key": "SINUN_API_AVAIMESI"},
    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": "SINUN_API_AVAIMESI" },
});
const data = await response.json();

Jos usealla yrityksellä on sama nimi, API voi palauttaa yhden niistä, ei välttämättä haluamaasi, tai vastata 404. Kun oikealla yrityksellä on väliä, hae rekisterituomioistuimella ja rekisterinumerolla tai entity_id:llä.

Jos API ei löydä yritystä, se vastaa 404 eikä veloita mitään. Epätarkkoja syötteitä varten on AI-tila (ai_search=on-default): se löytää yrityksen myös nimen osista ja tutkii sitä verkossa. Se maksaa 20 lisäkrediittiä, vaikka se ei löytäisi yritystä. Saadaksesi useita ehdokkaita kerralla käytä Haku & vientiä.

Ominaisuudet

Jokainen yritysprofiili sisältää perustiedot, kuten nimen, yhtiömuodon, tilan, rekisterimerkinnän, osoitteen, toimialan, toimialaluokan, pääoman ja edustussäännöt. Kaiken muun pyydät ominaisuutena, esimerkiksi related_persons toimitusjohtajille tai financial_kpi taloudellisille tunnusluvuille.

Useita ominaisuuksia annat toistamalla parametrin feature tai listana: features=related_persons,financial_kpi. Jokainen ominaisuus näkyy vastauksessa omana avaimenaan. Vain publications on siellä nimeltään history.

curl -G "https://handelsregister.ai/api/v1/fetch-organization" \
  -H "x-api-key: SINUN_API_AVAIMESI" \
  --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": "SINUN_API_AVAIMESI"},
    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": "SINUN_API_AVAIMESI" },
});
const data = await response.json();

API ohittaa tuntemattomat nimet ilman virheilmoitusta, joten tarkista kirjoitusasu. Ominaisuudet, jotka eivät sisälly tilaukseesi, jätetään pois eikä niitä veloiteta.

Kaikki ominaisuudet hintoineen on lueteltu kohdassa fetch-organization, jokainen kenttä Datakatalogissa.

Krediitit

Datapyynnöt maksavat krediittejä. Yritysprofiiliin pätevät nämä säännöt:

5 krediitin perushinta veloitetaan, kun API palauttaa yrityksen.
Ominaisuus maksaa krediittejä vain, kun se palauttaa vastauksessa dataa. Tyhjä ominaisuus on maksuton, myös insolvency_publications ilman merkintöjä.
Reaaliaika ja AI-tila eivät ole ominaisuuksia vaan lisämaksuja omine sääntöineen:
- Reaaliaika maksaa 10 lisäkrediittiä heti, kun suora haku onnistuu. Tämä pätee myös, kun se ei näytä mitään uutta.
- AI-tila maksaa 20 lisäkrediittiä, vaikka se ei löytäisi yritystä. Lisämaksu jää pois vain, jos API keskeyttää pyynnön vastauksella 408, koska se kestää liian kauan.
Kaikki muut virheet eivät maksa mitään.

Kunkin ominaisuuden sääntö on kohdassa Laskutus, hinnat kohdassa fetch-organization.

Esimerkki: perustiedot ominaisuuksilla related_persons ja financial_kpi maksavat 5 + 2 + 1 = 8 krediittiä, jos molemmat ominaisuudet palauttavat dataa.

Ennen jokaista pyyntöä API tarkistaa, riittääkö saldosi korkeimpaan mahdolliseen hintaan. Jos ei riitä, API vastaa 402 eikä veloita mitään. Todellinen veloitus on kentässä meta.request_credit_cost, saldosi sen jälkeen kentässä meta.credits_remaining.

1{2  "meta": {3    "request_credit_cost": 5,4    "credits_remaining": 1455  }6}

200 · meta esimerkkipyynnöstämme, vain perustiedot

Krediittejä saat aloituskrediitteinä, krediittitilauksella joka kuukausi tai kertaostona lisäkrediitteinä. Ilman krediittitilausta aloituskrediitit ja lisäkrediitit ovat voimassa 30 päivää; aktiivisella tilauksella ne eivät vanhene. Kaikki muu on kohdassa Laskutus.

Ajantasainen data ja Reaaliaika

Oletuksena yritysprofiili tulee tietokannastamme. Tiedon ajantasaisuus riippuu sen lähteestä.

Handelsregister

Pidämme perustiedot, henkilöt ja rekisterikuulutukset tietokannassamme ajan tasalla rekisteristä. Se on nopeaa ja riittää useimpiin tarkoituksiin.

Reaaliajalla (realtime_mode=handelsregister-default) API hakee Aktueller Abdruckin (AD, ajantasainen ote) suoraan Handelsregisteristä (kaupparekisteri) pyyntösi hetkellä ja palauttaa sen JSONina. Saat myös tällä hetkellä rekisteröidyt henkilöt kentässä related_persons.current maksamatta ominaisuudesta.

Onnistuiko suora haku, näkyy kentässä _realtime_mode.status. Veloitamme Reaaliajan 10 krediittiä vain tilalla success.

curl -G "https://handelsregister.ai/api/v1/fetch-organization" \
  -H "x-api-key: SINUN_API_AVAIMESI" \
  --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": "SINUN_API_AVAIMESI"},
    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": "SINUN_API_AVAIMESI" },
});
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}

200 · Ote esimerkkivastauksesta Reaaliajalla yrityksestä Hetzner Online GmbH

Jos suora haku epäonnistuu, API palauttaa tallennetut tiedot tietokannastamme. Tunnistat sen kentästä _realtime_mode.status, joka ei silloin ole success. Reaaliaikaa ei silloin veloiteta, kuten myös meta.request_credit_cost näyttää.

Reaaliaika kannattaa, kun tämän päivän tilanteella on väliä. Esimerkiksi tarkistat uudet liikekumppanit ennen allekirjoitusta tai näet, kuka saa edustaa yritystä juuri nyt.

Reaaliaikahaku kestää tavallista hakua kauemmin. Aseta asiakasohjelmasi aikakatkaisuksi vähintään 120 sekuntia. Jos pyyntö kestää liian kauan, API vastaa 408 eikä veloita mitään. Yritä silloin myöhemmin uudelleen.

Tilinpäätökset

Etsimme uusia julkaistuja tilinpäätöksiä joka päivä. Yrityksillä on kuitenkin julkaisemiseen aikaa kaksitoista kuukautta tilikauden päättymisestä (HGB § 325), ja moni käyttää koko määräajan. Jotkin yritykset ylittävät lakisääteisen määräajan tietoisesti ja julkaisevat vielä myöhemmin.

Uusin tilinpäätös koskee siksi usein toissa vuotta. Lisää kohdassa Tuoreus.

Maksukyvyttömyyskuulutukset

Maksukyvyttömyystuomioistuimet julkaisevat kuulutuksensa yleensä päätöspäivänä tai pian sen jälkeen. Saat ne ominaisuudella insolvency_publications, kukin tuomioistuimen, diaarinumeron ja päivämäärän kanssa.

Uutiset

Ominaisuus news palauttaa verkon uutisia yrityksestä otsikon, lähteen, päivämäärän ja linkin kanssa. Ajantasaisuus riippuu siitä, milloin yrityksestä viimeksi uutisoitiin. Pienistä yrityksistä sopivia uutisia on usein vain vähän.

Historia ja voimassaolo

Monet tiedot muuttuvat ajan myötä. Siksi API palauttaa nykytilan ja historian rinnakkain:

current on tilanne tänään.
history listaa jokaisen rekisteröidyn tilan kentillä effective_from ja effective_to. Jos effective_to on null, tila on yhä voimassa.
Henkilöt ovat kentissä related_persons.current ja related_persons.past, kukin kentillä start_date ja end_date.

Jokainen historiallinen tieto tulee rekistereistä ja julkaisuista, esimerkiksi Handelsregisterin Chronologischer Abdruckista (CD, kronologinen ote) tai kaikista julkaistuista tilinpäätöksistä.

Tältä se näyttää esimerkissämme yrityksen Hetzner Online GmbH edustussäännöissä. Esimerkkivastauksessa ne nimeävät johtokunnan 28.7.2015 asti ja sen jälkeen toimitusjohtajat:

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}

Esimerkkivastaus: Hetzner Online GmbH:n representation_scheme

Useimmat päivämäärät tulevat muodossa YYYY-MM-DD. Kuinka kauas historia ulottuu, kerrotaan kohdassa Ikä ja historia.

Tyhjät arvot

Jokaisella yrityksellä ei ole arvoa jokaiselle kentälle. API näyttää tämän kahdella tavalla:

null: kentälle ei ole arvoa.
[]: listassa ei ole merkintöjä, esimerkiksi ei maksukyvyttömyyskuulutuksia.

Pyydetty ominaisuus ilman dataa tulee muodossa null tai [] eikä maksa mitään.

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}

Ote esimerkkivastauksesta yrityksestä dm-drogerie markt GmbH + Co. KG, tyhjine arvoineen

Käsittele koodissasi puuttuvaa avainta, null-arvoa ja []-listaa samoin, koska jotkin tyhjät objektit tulevat muodossa []. Lue kentät myös nimiensä perusteella, koska avainten järjestys ei ole kiinteä.

Jos arvo puuttuu, yrityksen ei yleensä tarvitse julkaista sitä lainkaan. Mitä laki vaatii yhtiömuodon ja koon mukaan, kerrotaan kohdassa Datan saatavuus. Joitakin tietoja jätämme tarkoituksella pois; niissä on silloin redacted: true.

Vakaus ja versiot

API kasvaa lisäämällä. Uusi data ja uudet ominaisuudet tulevat uusina kenttinä. Emme koskaan poista olemassa olevia kenttiä, emme nimeä niitä uudelleen emmekä muuta niiden tyyppiä tai merkitystä. Näin jokainen versio pysyy taaksepäin yhteensopivana.

Muutokset, jotka rikkoisivat olemassa olevaa koodia, tulevat vain uudessa API-versiossa, esimerkiksi polussa /v2. Nykyinen versio toimii polussa /v1.

Anna siis asiakasohjelmasi ohittaa tuntemattomat kentät ja käsitellä tuntemattomat arvot yleisenä tapauksena. Uudet kentät ja ominaisuudet on lueteltu Muutoslokissa.

Tilaukset

Yritysprofiilia, asiakirjoja, Haku & vientiä ja Signalsia voit käyttää jokaisella tilillä, myös ilman krediittitilausta. Krediittitilaus tuo uusia krediittejä joka kuukausi ja avaa lisää dataa:

Tilaukset
Mitä saat lisäksi	Plus	Pro	Max
Henkilöprofiili: Henkilöiden roolit ja omistukset	sisältyy	sisältyy	sisältyy
Haku & vienti: Suodattimet omistukselle, johdolle ja maksukyvyttömyydelle	ei sisälly	sisältyy	sisältyy
Yritysprofiili: Yli 90 laajennettua taloudellista tunnuslukua	ei sisälly	sisältyy	sisältyy
Yritysprofiili: Energiayhtiöiden toimintokohtaiset tilinpäätökset (§ 6b EnWG)	ei sisälly	ei sisälly	sisältyy
Yritysprofiili: Syvät osakastiedot (`shareholders_deep`)	ei sisälly	ei sisälly	sisältyy
Yritysverkosto (`network`)	ei sisälly	sisältyy	sisältyy
Signals: Maksukyvyttömyydet	ei sisälly	sisältyy	sisältyy
Signals: Rakennejärjestelyt & M&A	ei sisälly	ei sisälly	sisältyy

API jättää tilauksesi ulkopuoliset ominaisuudet pois ilman virhettä eikä veloita niitä. Tilauksesi ulkopuoliset henkilöprofiilit ja hakusuodattimet se hylkää vastauksella 403, myös maksutta. Signalsissa tämä koskee aiheita, joita pyydät erikseen; muuten saat yksinkertaisesti kaikki tilauksesi aiheet.

Tilausten hinnat ja krediitit löydät hinnastosivulta.

Seuraavaksi

Hae yritysprofiili Nimi, rekisterinumero tai entity_id käytännössä. Datan saatavuus Mitä dataa on saatavilla yhtiömuodon ja koon mukaan. Laskutus Kaikki hinnat ja miten jäljität ne jokaisessa vastauksessa. Virheet Miltä virheet näyttävät ja mitä voit tehdä.