Grundbegreber

Parameteren q i fetch-organization tager tre slags input. Eksemplerne på denne side er forespørgsler for Hetzner Online GmbH, Ansbach HRB 6089:

Registernummeret alene er ikke nok, for hver registerret tildeler sine egne numre. Rækkefølgen er derimod fri: i eksemplet finder HRB 6089 Ansbach den samme virksomhed.

Finder API’et ingen virksomhed, svarer det med 404 og trækker intet. Til uskarpt input findes AI-tilstand (ai_search=on-default): den finder også virksomheden ud fra dele af navnet og researcher den på nettet. Den koster 20 ekstra kreditter, også hvis den ikke finder nogen virksomhed. Vil du have flere kandidater på én gang, så brug Søgning & eksport.

Hver virksomhedsprofil indeholder grunddataene, herunder navn, selskabsform, status, registerindførsel, adresse, formål, branche, kapital og tegningsregler. Alt andet anmoder du om som feature, f.eks. related_persons for direktørerne eller financial_kpi for Finansielle nøgletal.

Flere features angiver du med en gentaget feature eller som liste: features=related_persons,financial_kpi. Hver feature optræder i svaret under sin egen nøgle. Kun publications hedder history dér.

API’et ignorerer ukendte navne uden fejlmeddelelse, så tjek stavemåden. Features, som dit abonnement ikke omfatter, udelades og afregnes ikke.

Alle features med priser står under fetch-organization, hvert felt i Datakataloget.

Dataforespørgsler koster kreditter. For en virksomhedsprofil gælder disse regler:

• Grundprisen på 5 kreditter gælder, når API’et returnerer en virksomhed.
• En feature koster kun kreditter, når den returnerer data i svaret. En tom feature er gratis, også insolvency_publications uden poster.
• Realtid og AI-tilstand er ikke features, men tillæg med egne regler:
  • Realtid koster 10 ekstra kreditter, så snart live-opslaget lykkes. Det gælder også, når det ikke viser noget nyt.
  • AI-tilstand koster 20 ekstra kreditter, også hvis den ikke finder nogen virksomhed. Tillægget bortfalder kun, når API’et afbryder forespørgslen med 408, fordi den tager for lang tid.
• Alle andre fejl koster intet.

Reglen for hver enkelt feature står under Afregning, priserne under fetch-organization.

Et eksempel: grunddataene med related_persons og financial_kpi koster 5 + 2 + 1 = 8 kreditter, hvis begge features returnerer data.

Før hver forespørgsel tjekker API’et, om din saldo dækker den højest mulige pris. Gør den ikke det, svarer API’et med 402 og trækker intet. Hvad der faktisk blev trukket, står i meta.request_credit_cost, din saldo bagefter i meta.credits_remaining.

Kreditter får du som startkreditter, hver måned med et kreditabonnement eller én gang som optankningskreditter. Uden kreditabonnement er startkreditter og optankningskreditter gyldige i 30 dage; med et aktivt abonnement udløber de ikke. Alt andet står under Afregning.

Som standard kommer virksomhedsprofilen fra vores database. Hvor aktuel en oplysning er, afhænger af dens kilde.

Grunddata, personer og registerbekendtgørelser holder vi opdateret i vores database ud fra registret. Det er hurtigt og nok til de fleste formål.

Med Realtid (realtime_mode=handelsregister-default) henter API’et Aktueller Abdruck (AD, aktuel udskrift) live fra Handelsregister (det tyske handelsregister) i det øjeblik, du forespørger, og returnerer den som JSON. Du får også de aktuelt registrerede personer i related_persons.current, uden at betale for featuren.

Om live-opslaget lykkedes, ser du i _realtime_mode.status. De 10 kreditter for Realtid trækker vi kun ved success.

Fejler live-opslaget, returnerer API’et de gemte data fra vores database. Det kan du se på _realtime_mode.status, som så ikke er success. Realtid afregnes så ikke, hvilket meta.request_credit_cost også viser.

Realtid kan betale sig, når dagens tilstand er vigtig. Du tjekker f.eks. nye forretningspartnere før underskrift eller ser, hvem der må tegne virksomheden lige nu.

Vi leder hver dag efter nyligt offentliggjorte årsregnskaber. Virksomheder har dog op til tolv måneder efter regnskabsårets afslutning til at offentliggøre dem (§ 325 HGB), og mange udnytter hele fristen. Nogle virksomheder overskrider bevidst den lovpligtige frist og offentliggør endnu senere.

Det seneste regnskab dækker derfor ofte forrige år. Mere under Aktualitet.

Insolvensretterne offentliggør som regel deres bekendtgørelser på dagen for afgørelsen eller kort efter. Du får dem via featuren insolvency_publications, hver med ret, sagsnummer og dato.

Featuren news returnerer nyheder om virksomheden fra nettet, med titel, kilde, dato og link. Hvor aktuelle de er, afhænger af, hvornår der sidst blev skrevet om virksomheden. For små virksomheder er der ofte kun få passende artikler.

Mange oplysninger ændrer sig over tid. API’et returnerer derfor den nuværende tilstand og historikken side om side:

• current er tilstanden i dag.
• history viser hver registreret tilstand med effective_from og effective_to. Er effective_to null, gælder tilstanden stadig i dag.
• Personer står i related_persons.current og related_persons.past, hver med start_date og end_date.

Hver oplysning med historik kommer fra registrene og offentliggørelserne, f.eks. fra Chronologischer Abdruck (CD, kronologisk udskrift) i Handelsregister eller fra alle offentliggjorte årsregnskaber.

Sådan ser det ud i vores eksempel for tegningsreglerne for Hetzner Online GmbH. I eksempelsvaret nævner de direktionen indtil 28. juli 2015 og direktørerne siden da:

De fleste datoer kommer i formatet YYYY-MM-DD. Hvor langt historikken rækker tilbage, er beskrevet under Alder og historik.

Ikke alle virksomheder har en værdi for hvert felt. API’et viser det på to måder:

• null: der er ingen værdi for dette felt.
• []: listen har ingen poster, f.eks. ingen insolvensbekendtgørelser.

En ønsket feature uden data kommer som null eller [] og koster intet.

Behandl i din kode en manglende nøgle, null og [] ens, for nogle tomme objekter kommer som []. Læs også felter via deres navne, for nøglernes rækkefølge er ikke fast.

Mangler en værdi, skal virksomheden som regel slet ikke offentliggøre den. Hvad loven kræver afhængigt af selskabsform og størrelse, er beskrevet under Datatilgængelighed. Nogle oplysninger tilbageholder vi bevidst; de har så redacted: true.

API’et vokser additivt. Nye data og features kommer som nye felter. Vi fjerner aldrig eksisterende felter, vi omdøber dem ikke, og vi ændrer hverken deres type eller betydning. Det holder hver version bagudkompatibel.

Ændringer, der ville bryde eksisterende kode, kommer kun i en ny API-version, f.eks. under /v2. Den aktuelle version kører under /v1.

Lad derfor din klient ignorere ukendte felter og behandle ukendte værdier som et generelt tilfælde. Nye felter og features står i Changelog.

Virksomhedsprofil, Dokumenter, Søgning & eksport og Signals kan du bruge med enhver konto, også uden kreditabonnement. Et kreditabonnement giver nye kreditter hver måned og låser op for flere data:

API’et udelader features uden for dit abonnement uden fejl og afregner dem ikke. Personprofiler og søgefiltre uden for dit abonnement afviser det med 403, også uden omkostninger. For Signals gælder det emner, du udtrykkeligt anmoder om; ellers får du blot alle emner i dit abonnement.

Abonnementernes priser og kreditter finder du på prissiden.