Alapfogalmak

A fetch-organization q paramétere háromféle bemenetet fogad. Az oldal példái a Hetzner Online GmbH-ra (Ansbach HRB 6089) vonatkozó kérések:

A cégjegyzékszám önmagában nem elég, mert minden cégbíróság saját számokat oszt ki. A sorrend viszont tetszőleges: a példában a HRB 6089 Ansbach ugyanazt a céget találja meg.

Ha az API nem talál céget, 404-gyel válaszol, és semmit nem számol fel. Pontatlan bemenethez ott az AI mód (ai_search=on-default): a névtöredékekből is megtalálja a céget, és utánanéz a weben. 20 extra kreditbe kerül, akkor is, ha nem talál céget. Ha egyszerre több jelöltet szeretnél, használd a Keresés és exportot.

Minden cégprofil tartalmazza az alapadatokat, köztük a nevet, a jogi formát, a státuszt, a nyilvántartási bejegyzést, a címet, a tevékenységi kört, az iparágat, a tőkét és a képviseleti szabályokat. Minden mást funkcióként kérsz, például related_persons az ügyvezetőkhöz vagy financial_kpi a pénzügyi KPI-khoz.

Több funkciót ismételt feature paraméterrel vagy listaként adsz meg: features=related_persons,financial_kpi. Minden funkció a saját kulcsa alatt jelenik meg a válaszban. Csak a publications neve ott history.

Az API az ismeretlen neveket hibaüzenet nélkül figyelmen kívül hagyja, ezért ellenőrizd a helyesírást. A csomagodban nem szereplő funkciók kimaradnak, és nem számoljuk fel őket.

Az összes funkció az árával a fetch-organization oldalon, minden mező az Adatkatalógusban található.

Az adatlekérések kreditbe kerülnek. Cégprofilnál ezek a szabályok érvényesek:

• A 5 kredites alapár akkor érvényes, ha az API visszaad egy céget.
• Egy funkció csak akkor kerül kreditbe, ha adatot ad vissza a válaszban. Az üres funkció ingyenes, a bejegyzések nélküli insolvency_publications is.
• A valós idejű mód és az AI mód nem funkció, hanem saját szabályokkal működő felár:
  • A valós idejű mód 10 extra kreditbe kerül, amint az élő lekérés sikerül. Ez akkor is érvényes, ha semmi újat nem mutat.
  • Az AI mód 20 extra kreditbe kerül, akkor is, ha nem talál céget. A felár csak akkor marad el, ha az API 408-cal megszakítja a kérést, mert túl sokáig tart.
• Minden más hiba ingyenes.

Az egyes funkciók szabálya az Elszámolás oldalon, az árak a fetch-organization oldalon vannak.

Egy példa: az alapadatok related_persons-szal és financial_kpi-val 5 + 2 + 1 = 8 kreditbe kerülnek, ha mindkét funkció ad vissza adatot.

Minden kérés előtt az API ellenőrzi, hogy az egyenleged fedezi-e a lehető legmagasabb árat. Ha nem, 402-vel válaszol, és semmit nem számol fel. A ténylegesen felszámított összeg a meta.request_credit_cost, az utána megmaradt egyenleged a meta.credits_remaining mezőben van.

Krediteket kezdő kreditként, kredit-előfizetéssel havonta, vagy egyszeri feltöltött kreditként kapsz. Kredit-előfizetés nélkül a kezdő és a feltöltött kreditek 30 napig érvényesek; aktív előfizetés mellett nem járnak le. Minden más az Elszámolás oldalon.

Alapértelmezésként a cégprofil az adatbázisunkból származik. Hogy egy információ mennyire friss, az a forrásától függ.

Az alapadatokat, a személyeket és a nyilvántartási közleményeket a nyilvántartásból folyamatosan frissen tartjuk az adatbázisunkban. Ez gyors, és a legtöbb célra elég.

Valós idejű móddal (realtime_mode=handelsregister-default) az API a kérésed pillanatában élőben lekéri az Aktueller Abdruck (AD, aktuális kivonat) dokumentumot a Handelsregisterből (német cégnyilvántartás), és JSON-ként adja vissza. A jelenleg bejegyzett személyeket is megkapod a related_persons.current alatt, anélkül hogy a funkcióért fizetnél.

Hogy az élő lekérés sikerült-e, a _realtime_mode.status mutatja. A valós idejű mód 10 kreditjét csak success esetén számoljuk fel.

Ha az élő lekérés nem sikerül, az API az adatbázisunkban tárolt adatokat adja vissza. Ezt a _realtime_mode.status mutatja, ilyenkor nem success. A valós idejű módot ekkor nem számoljuk fel, ahogy a meta.request_credit_cost is mutatja.

A valós idejű mód akkor éri meg, ha a mai állapot számít. Például új üzleti partnereket ellenőrzöl aláírás előtt, vagy látni akarod, ki képviselheti most a céget.

Naponta keressük az újonnan közzétett éves beszámolókat. A cégeknek azonban az üzleti év vége után legfeljebb tizenkét hónapjuk van a közzétételre (§ 325 HGB), és sokan ki is használják a teljes határidőt. Egyes cégek szándékosan elmulasztják a törvényes határidőt, és még később tesznek közzé.

A legfrissebb beszámoló ezért gyakran a tavalyelőtti évre vonatkozik. Bővebben: Frissesség.

A csődbíróságok közleményeiket általában a döntés napján vagy röviddel utána teszik közzé. Az insolvency_publications funkcióval kapod meg őket, mindegyiket bírósággal, ügyszámmal és dátummal.

A news funkció a webről ad vissza híreket a cégről, címmel, forrással, dátummal és linkkel. Hogy mennyire frissek, az attól függ, mikor írtak utoljára a cégről. Kis cégekről gyakran csak kevés releváns hír van.

Sok adat idővel változik. Az API ezért az aktuális állapotot és az előzményeket egymás mellett adja vissza:

• A current a mai állapot.
• A history minden bejegyzett állapotot felsorol effective_from és effective_to mezővel. Ha az effective_to értéke null, az állapot ma is érvényes.
• A személyek a related_persons.current és a related_persons.past alatt vannak, mindegyik start_date és end_date mezővel.

Minden előzményekkel rendelkező adat a nyilvántartásokból és a közzétételekből származik, például a Handelsregister Chronologischer Abdruck (CD, kronologikus kivonat) dokumentumából vagy az összes közzétett éves beszámolóból.

Így néz ki a példánkban a Hetzner Online GmbH képviseleti szabályainál. A példaválaszban 2015. július 28-ig az igazgatóságot, azóta az ügyvezetőket nevezik meg:

A legtöbb dátum YYYY-MM-DD formátumú. Hogy meddig nyúlnak vissza az előzmények, azt a Kor és előzmények írja le.

Nem minden cégnek van értéke minden mezőben. Az API ezt kétféleképpen jelzi:

• null: ennek a mezőnek nincs értéke.
• []: a listának nincsenek elemei, például nincsenek fizetésképtelenségi közzétételek.

Az adat nélküli kért funkció null vagy [] értékkel érkezik, és nem kerül semmibe.

A kódodban kezeld egyformán a hiányzó kulcsot, a null-t és a []-t, mert néhány üres objektum []-ként érkezik. A mezőket is a nevük alapján olvasd, mert a kulcsok sorrendje nem rögzített.

Ha egy érték hiányzik, a cégnek általában egyáltalán nem kell közzétennie. Hogy jogi formától és mérettől függően mit ír elő a törvény, azt az Adatok elérhetősége írja le. Néhány adatot szándékosan visszatartunk; ezeknél redacted: true áll.

Az API bővítéssel nő. Az új adatok és funkciók új mezőkként érkeznek. Meglévő mezőt soha nem távolítunk el, nem nevezünk át, és sem a típusát, sem a jelentését nem változtatjuk meg. Így minden verzió visszafelé kompatibilis marad.

A meglévő kódot eltörő változások csak új API-verzióban jönnek, például a /v2 alatt. A jelenlegi verzió a /v1 alatt fut.

Ezért a kliensed hagyja figyelmen kívül az ismeretlen mezőket, és az ismeretlen értékeket kezelje általános esetként. Az új mezők és funkciók a Changelogban szerepelnek.

A Cégprofilt, a Dokumentumokat, a Keresés és exportot és a Signalst minden fiókkal használhatod, kredit-előfizetés nélkül is. A kredit-előfizetés havonta új krediteket hoz, és több adatot nyit meg:

A csomagodon kívüli funkciókat az API hiba nélkül kihagyja, és nem számolja fel. A csomagodon kívüli személyprofilokat és keresőszűrőket 403-mal utasítja el, szintén díjmentesen. A Signalsnál ez a kifejezetten kért témákra vonatkozik; ezek nélkül egyszerűen a csomagod összes témáját kapod.

A csomagok árait és kreditjeit az árak oldalon találod.