Concepte de bază – Documentație

Identifică fără ambiguitate companiile

Parametrul q al fetch-organization acceptă trei tipuri de intrare. Exemplele de pe această pagină sunt cereri pentru Hetzner Online GmbH, Ansbach HRB 6089:

Identifică fără ambiguitate companiile
Intrare	Exemplu	Când se potrivește
Denumirea companiei	`Hetzner Online GmbH`	Pentru început. Scrie denumirea cât mai complet, așa cum apare în registru.
Instanța de registru și numărul de registru	`Ansbach HRB 6089`	Unic pentru fiecare companie înregistrată. Instanța, tipul de registru și numărul merg împreună.
entity_id	`94eb910fef13f94585c48c263fa446d4`	Pentru cererile următoare. Îl primești în fiecare răspuns.

Numărul de registru singur nu ajunge, pentru că fiecare instanță de registru își atribuie propriile numere. Ordinea, în schimb, e liberă: în exemplu, HRB 6089 Ansbach găsește aceeași companie.

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

import requests

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

Dacă mai multe companii au același nume, API-ul poate returna una dintre ele, nu neapărat pe cea dorită, sau poate răspunde cu 404. Când contează compania corectă, interoghează după instanța de registru și numărul de registru sau după entity_id.

Dacă API-ul nu găsește nicio companie, răspunde cu 404 și nu taxează nimic. Pentru intrări vagi există Modul AI (ai_search=on-default): găsește compania și din părți ale numelui și o cercetează pe web. Costă 20 credite în plus, chiar dacă nu găsește nicio companie. Ca să primești mai mulți candidați deodată, folosește Căutare & Export.

Funcții

Fiecare profil de companie conține datele de bază, inclusiv denumire, formă juridică, status, înscriere în registru, adresă, obiect de activitate, industrie, capital și reguli de reprezentare. Tot restul îl ceri ca funcție, de exemplu related_persons pentru administratori sau financial_kpi pentru indicatorii financiari.

Transmiți mai multe funcții cu un feature repetat sau ca listă: features=related_persons,financial_kpi. Fiecare funcție apare în răspuns sub propria cheie. Doar publications se numește acolo history.

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

API-ul ignoră numele necunoscute fără mesaj de eroare, deci verifică scrierea. Funcțiile pe care planul tău nu le include sunt omise și nu se taxează.

Toate funcțiile cu prețurile lor sunt la fetch-organization, fiecare câmp în Catalogul de date.

Credite

Cererile de date costă credite. Pentru un profil de companie se aplică aceste reguli:

Prețul de bază de 5 credite se aplică atunci când API-ul returnează o companie.
O funcție costă credite doar când returnează date în răspuns. O funcție goală e gratuită, inclusiv insolvency_publications fără intrări.
Timp real și Modul AI nu sunt funcții, ci suprataxe cu reguli proprii:
- Timp real costă 10 credite în plus de îndată ce preluarea live reușește. Asta se aplică și când nu arată nimic nou.
- Modul AI costă 20 credite în plus, chiar dacă nu găsește nicio companie. Suprataxa se anulează doar când API-ul întrerupe cererea cu 408 pentru că durează prea mult.
Toate celelalte erori nu costă nimic.

Regula pentru fiecare funcție în parte este la Facturare, prețurile la fetch-organization.

Un exemplu: datele de bază cu related_persons și financial_kpi costă 5 + 2 + 1 = 8 credite dacă ambele funcții returnează date.

Înainte de fiecare cerere, API-ul verifică dacă soldul tău acoperă prețul maxim posibil. Dacă nu, API-ul răspunde cu 402 și nu taxează nimic. Ce s-a taxat de fapt găsești în meta.request_credit_cost, soldul de după în meta.credits_remaining.

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

200 · meta din cererea noastră exemplu, doar cu date de bază

Primești credite ca credite de start, lunar cu un abonament de credite sau o singură dată ca credite din reîncărcare. Fără abonament de credite, creditele de start și cele din reîncărcare sunt valabile 30 zile; cu un abonament activ nu expiră. Restul e la Facturare.

Date actuale și Timp real

Implicit, profilul de companie vine din baza noastră de date. Cât de actuală e o informație depinde de sursa ei.

Handelsregister

Ținem la zi în baza noastră de date, din registru, datele de bază, persoanele și publicațiile din registru. E rapid și suficient pentru majoritatea scopurilor.

Cu Timp real (realtime_mode=handelsregister-default), API-ul preia Aktueller Abdruck (AD, extrasul curent) live din Handelsregister (registrul comerțului) în momentul cererii tale și îl returnează ca JSON. Primești și persoanele înregistrate în prezent în related_persons.current, fără să plătești funcția.

Dacă preluarea live a reușit arată _realtime_mode.status. Cele 10 credite pentru Timp real le taxăm doar la success.

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

200 · Fragment dintr-un răspuns exemplu cu Timp real pentru Hetzner Online GmbH

Dacă preluarea live eșuează, API-ul returnează datele salvate din baza noastră de date. Recunoști asta după _realtime_mode.status, care atunci nu este success. Timp real nu se taxează atunci, după cum arată și meta.request_credit_cost.

Timp real merită când contează starea de azi. De exemplu, verifici parteneri de afaceri noi înainte de semnare sau vezi cine poate reprezenta compania chiar acum.

O preluare în Timp real durează mai mult decât una normală. Setează timeoutul clientului la cel puțin 120 de secunde. Dacă cererea durează prea mult, API-ul răspunde cu 408 și nu taxează nimic. Încearcă atunci din nou mai târziu.

Situații financiare anuale

Căutăm zilnic situații financiare anuale nou publicate. Companiile au însă până la douăsprezece luni după încheierea exercițiului financiar ca să le publice (§ 325 HGB), iar multe folosesc tot termenul. Unele companii depășesc intenționat termenul legal și publică și mai târziu.

Cea mai recentă situație acoperă de aceea adesea anul de dinainte de anul trecut. Mai multe la Actualitate.

Publicații de insolvență

Instanțele de insolvență își publică de obicei anunțurile în ziua hotărârii sau la scurt timp după. Le primești prin funcția insolvency_publications, fiecare cu instanță, număr de dosar și dată.

Știri

Funcția news returnează știri despre companie de pe web, cu titlu, sursă, dată și link. Cât de actuale sunt depinde de când s-a scris ultima dată despre companie. Pentru companiile mici există adesea doar câteva articole potrivite.

Istoric și valabilitate

Multe informații se schimbă în timp. De aceea API-ul returnează starea actuală și istoricul unul lângă altul:

current este starea de azi.
history listează fiecare stare înregistrată cu effective_from și effective_to. Dacă effective_to este null, starea e valabilă și azi.
Persoanele sunt în related_persons.current și related_persons.past, fiecare cu start_date și end_date.

Fiecare informație cu istoric provine din registre și publicații, de exemplu din Chronologischer Abdruck (CD, extrasul cronologic) al Handelsregister sau din toate situațiile financiare anuale publicate.

Iată cum arată asta în exemplul nostru pentru regulile de reprezentare ale Hetzner Online GmbH. În răspunsul exemplu, ele numesc consiliul de administrație până pe 28 iulie 2015 și administratorii de atunci încoace:

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}

Răspuns exemplu: representation_scheme al Hetzner Online GmbH

Majoritatea datelor calendaristice vin în formatul YYYY-MM-DD. Cât de departe în trecut merge istoricul afli la Vechime și istoric.

Valori goale

Nu orice companie are o valoare pentru fiecare câmp. API-ul arată asta în două moduri:

null: nu există nicio valoare pentru acest câmp.
[]: lista nu are intrări, de exemplu niciun anunț de insolvență.

O funcție cerută fără date vine ca null sau [] și nu costă nimic.

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}

Fragment dintr-un răspuns exemplu pentru dm-drogerie markt GmbH + Co. KG, cu valori goale

În codul tău, tratează la fel o cheie lipsă, null și [], pentru că unele obiecte goale vin ca []. Citește și câmpurile după nume, pentru că ordinea cheilor nu este fixă.

Dacă lipsește o valoare, de obicei compania nici nu trebuie să o publice. Ce cere legea în funcție de forma juridică și mărime afli la Disponibilitatea datelor. Unele informații le reținem intenționat; ele poartă atunci redacted: true.

Stabilitate și versiuni

API-ul crește aditiv. Datele și funcțiile noi vin ca câmpuri noi. Nu eliminăm niciodată câmpuri existente, nu le redenumim și nu le schimbăm nici tipul, nici semnificația. Astfel fiecare versiune rămâne compatibilă cu cele anterioare.

Schimbările care ar strica codul existent vin doar într-o versiune nouă a API-ului, de exemplu sub /v2. Versiunea actuală rulează sub /v1.

Lasă deci clientul tău să ignore câmpurile necunoscute și tratează valorile necunoscute ca un caz general. Câmpurile și funcțiile noi sunt listate în Changelog.

Planuri

Profil companie, Documente, Căutare & Export și Signals le poți folosi cu orice cont, chiar și fără abonament de credite. Un abonament de credite aduce credite noi în fiecare lună și deblochează mai multe date:

Planuri
Ce primești în plus	Plus	Pro	Max
Profil persoană: Rolurile și participațiile persoanelor	inclus	inclus	inclus
Căutare & Export: Filtre după proprietate, conducere și insolvență	neinclus	inclus	inclus
Profil companie: Peste 90 de indicatori financiari extinși	neinclus	inclus	inclus
Profil companie: Situații financiare pe activități ale furnizorilor de energie (§ 6b EnWG)	neinclus	neinclus	inclus
Profil companie: Asociați detaliat (`shareholders_deep`)	neinclus	neinclus	inclus
Rețeaua companiei (`network`)	neinclus	inclus	inclus
Signals: Insolvențe	neinclus	inclus	inclus
Signals: Transformări & M&A	neinclus	neinclus	inclus

API-ul omite fără eroare funcțiile din afara planului tău și nu le taxează. Profilurile de persoană și filtrele de căutare din afara planului le respinge cu 403, tot fără costuri. Pentru Signals, asta se aplică temelor pe care le ceri explicit; fără asta primești pur și simplu toate temele planului tău.

Prețurile și creditele planurilor le găsești pe pagina de prețuri.

Mai departe

Preia un profil de companie Nume, număr de registru sau entity_id în practică. Disponibilitatea datelor Ce date există în funcție de forma juridică și mărime. Facturare Toate prețurile și cum le verifici în fiecare răspuns. Erori Cum arată erorile și ce poți face.