Basisbegrippen

De parameter q van fetch-organization accepteert drie soorten invoer. De voorbeelden op deze pagina zijn aanvragen voor Hetzner Online GmbH, Ansbach HRB 6089:

Het registernummer alleen is niet genoeg, omdat elke registerrechtbank eigen nummers uitgeeft. De volgorde is daarentegen vrij: in het voorbeeld vindt HRB 6089 Ansbach hetzelfde bedrijf.

Vindt de API geen bedrijf, dan antwoordt ze met 404 en berekent niets. Voor vage invoer is er de AI-modus (ai_search=on-default): die vindt het bedrijf ook aan de hand van delen van de naam en onderzoekt het op het web. Dat kost 20 extra credits, ook als er geen bedrijf wordt gevonden. Wil je meerdere kandidaten tegelijk, gebruik dan Zoeken & exporteren.

Elk bedrijfsprofiel bevat de basisgegevens, waaronder naam, rechtsvorm, status, registerinschrijving, adres, doel, branche, kapitaal en vertegenwoordigingsregels. Al het andere vraag je op als feature, bijvoorbeeld related_persons voor de bestuurders of financial_kpi voor de Financiële KPI’s.

Meerdere features geef je mee met een herhaalde feature of als lijst: features=related_persons,financial_kpi. Elke feature staat in het antwoord onder een eigen sleutel. Alleen publications heet daar history.

De API negeert onbekende namen zonder foutmelding, controleer dus de spelling. Features die niet in je plan zitten, worden weggelaten en niet berekend.

Alle features met hun prijzen staan in fetch-organization, elk veld in de Datacatalogus.

Gegevensaanvragen kosten credits. Voor een bedrijfsprofiel gelden deze regels:

• De basisprijs van 5 credits geldt zodra de API een bedrijf teruggeeft.
• Een feature kost alleen credits als die gegevens in het antwoord oplevert. Een lege feature is gratis, ook insolvency_publications zonder vermeldingen.
• Realtime en AI-modus zijn geen features maar toeslagen met eigen regels:
  • Realtime kost 10 extra credits zodra de live-opvraging slaagt. Dat geldt ook als ze niets nieuws laat zien.
  • De AI-modus kost 20 extra credits, ook als er geen bedrijf wordt gevonden. De toeslag vervalt alleen als de API de aanvraag met 408 afbreekt omdat ze te lang duurt.
• Alle andere fouten kosten niets.

De regel voor elke afzonderlijke feature staat in Afrekening, de prijzen in fetch-organization.

Een voorbeeld: de basisgegevens met related_persons en financial_kpi kosten 5 + 2 + 1 = 8 credits als beide features gegevens opleveren.

Vóór elke aanvraag controleert de API of je saldo de hoogst mogelijke prijs dekt. Is dat niet zo, dan antwoordt de API met 402 en berekent niets. Wat werkelijk is berekend, staat in meta.request_credit_cost, je saldo daarna in meta.credits_remaining.

Credits krijg je als startcredits, elke maand met een creditabonnement, of eenmalig als top-up-credits. Zonder creditabonnement zijn startcredits en top-up-credits 30 dagen geldig; met een actief abonnement vervallen ze niet. Al het andere staat in Afrekening.

Standaard komt het bedrijfsprofiel uit onze database. Hoe actueel een gegeven is, hangt af van de bron.

Basisgegevens, personen en registerbekendmakingen houden we in onze database actueel vanuit het register. Dat is snel en volstaat voor de meeste doeleinden.

Met Realtime (realtime_mode=handelsregister-default) haalt de API op het moment van je aanvraag de Aktueller Abdruck (AD, actueel uittreksel) live op uit het Handelsregister (Duits handelsregister) en levert die als JSON. Je krijgt daarbij ook de op dat moment ingeschreven personen in related_persons.current, zonder voor de feature te betalen.

Of de live-opvraging is gelukt, zie je in _realtime_mode.status. De 10 credits voor Realtime berekenen we alleen bij success.

Mislukt de live-opvraging, dan levert de API de opgeslagen gegevens uit onze database. Je herkent dat aan _realtime_mode.status, dat dan niet success is. Realtime wordt dan niet berekend, zoals ook meta.request_credit_cost laat zien.

Realtime loont als de stand van vandaag telt. Bijvoorbeeld als je nieuwe zakenpartners vóór de ondertekening controleert, of wilt zien wie het bedrijf op dit moment mag vertegenwoordigen.

We zoeken elke dag naar nieuw gepubliceerde jaarrekeningen. Bedrijven hebben echter tot twaalf maanden na het einde van het boekjaar om ze te publiceren (§ 325 HGB), en veel bedrijven gebruiken die hele termijn. Sommige bedrijven laten de wettelijke termijn bewust verstrijken en publiceren nog later.

De nieuwste jaarrekening gaat daarom vaak over het jaar vóór vorig jaar. Meer in Actualiteit.

De insolventierechtbanken publiceren hun bekendmakingen meestal op de dag van de beslissing of kort daarna. Je krijgt ze via de feature insolvency_publications, elk met rechtbank, zaaknummer en datum.

De feature news levert nieuws over het bedrijf van het web, met titel, bron, datum en link. Hoe actueel dat is, hangt af van wanneer er voor het laatst over het bedrijf is bericht. Voor kleine bedrijven zijn er vaak maar weinig passende berichten.

Veel gegevens veranderen in de loop van de tijd. De API levert daarom de actuele stand en de historie naast elkaar:

• current is de stand van vandaag.
• history bevat elke ingeschreven stand met effective_from en effective_to. Is effective_to gelijk aan null, dan geldt de stand vandaag nog.
• Personen staan in related_persons.current en related_persons.past, elk met start_date en end_date.

Elk gegeven met historie komt uit de registers en publicaties, bijvoorbeeld uit de Chronologischer Abdruck (CD, chronologisch uittreksel) van het Handelsregister of uit alle gepubliceerde jaarrekeningen.

Zo ziet dat er in ons voorbeeld uit voor de vertegenwoordigingsregels van Hetzner Online GmbH. In het voorbeeldantwoord noemen ze tot 28 juli 2015 het bestuur en sindsdien de bedrijfsleiders (Geschäftsführer):

De meeste datums komen in het formaat YYYY-MM-DD. Hoe ver de historie teruggaat, staat in Leeftijd en historie.

Niet elk bedrijf heeft een waarde voor elk veld. De API toont dat op twee manieren:

• null: voor dit veld is er geen waarde.
• []: de lijst heeft geen items, bijvoorbeeld geen insolventiepublicaties.

Een gevraagde feature zonder gegevens komt als null of [] en kost niets.

Behandel in je code een ontbrekende sleutel, null en [] gelijk, omdat sommige lege objecten als [] komen. Lees velden ook op hun naam, omdat de volgorde van de sleutels niet vastligt.

Ontbreekt een waarde, dan hoeft het bedrijf die meestal helemaal niet te publiceren. Wat de wet afhankelijk van rechtsvorm en omvang verlangt, staat in Beschikbaarheid van gegevens. Sommige gegevens houden we bewust achter; die hebben dan redacted: true.

De API groeit additief. Nieuwe gegevens en features komen erbij als nieuwe velden. Bestaande velden verwijderen we nooit, we hernoemen ze niet en we veranderen noch hun type noch hun betekenis. Zo blijft elke versie achterwaarts compatibel.

Wijzigingen die bestaande code zouden breken, komen alleen in een nieuwe API-versie, bijvoorbeeld onder /v2. De huidige versie draait onder /v1.

Laat je client dus onbekende velden negeren en onbekende waarden als algemeen geval behandelen. Nieuwe velden en features staan in de Changelog.

Bedrijfsprofiel, Documenten, Zoeken & exporteren en Signals kun je met elk account gebruiken, ook zonder creditabonnement. Een creditabonnement brengt elke maand nieuwe credits en ontgrendelt meer gegevens:

Features buiten je plan laat de API zonder fout weg en berekent ze niet. Persoonsprofielen en zoekfilters buiten je plan weigert ze met 403, ook zonder kosten. Bij Signals geldt dat voor onderwerpen die je expliciet opvraagt; zonder dat krijg je gewoon alle onderwerpen van je plan.

De prijzen en credits van de plannen vind je op de prijspagina.