Grunnbegreper – Dokumentasjon | handelsregister.ai

Finn firmaer entydig

Parameteren q i fetch-organization tar imot tre typer inndata. Eksemplene på denne siden er forespørsler for Hetzner Online GmbH, Ansbach HRB 6089:

Finn firmaer entydig
Inndata	Eksempel	Når det passer
Firmanavn	`Hetzner Online GmbH`	For å komme i gang. Skriv navnet så fullstendig som det står i registeret.
Registerdomstol og registernummer	`Ansbach HRB 6089`	Entydig for hvert registrert firma. Domstol, registertype og nummer hører sammen.
entity_id	`94eb910fef13f94585c48c263fa446d4`	For oppfølgingsforespørsler. Du får den i hvert svar.

Registernummeret alene er ikke nok, fordi hver registerdomstol tildeler sine egne numre. Rekkefølgen er derimot fri: i eksempelet finner HRB 6089 Ansbach det samme firmaet.

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

import requests

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

Har flere firmaer samme navn, kan API-et returnere ett av dem, ikke nødvendigvis det du vil ha, eller svare med 404. Når det riktige firmaet er viktig, spør du via registerdomstol og registernummer eller via entity_id.

Finner API-et ikke noe firma, svarer det med 404 og belaster ingenting. For uskarpe inndata finnes AI-modus (ai_search=on-default): den finner firmaet også ut fra deler av navnet og undersøker det på nettet. Den koster 20 ekstra kreditter, også når den ikke finner noe firma. For å få flere kandidater på en gang bruker du Søk & eksport.

Funksjoner

Hver firmaprofil inneholder grunndataene, blant annet navn, selskapsform, status, registeroppføring, adresse, formål, bransje, kapital og representasjonsregler. Alt annet ber du om som funksjon, for eksempel related_persons for de daglige lederne eller financial_kpi for de økonomiske nøkkeltallene.

Flere funksjoner sender du med gjentatt feature eller som liste: features=related_persons,financial_kpi. Hver funksjon vises i svaret under sin egen nøkkel. Bare publications heter history der.

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

API-et ignorerer ukjente navn uten feilmelding, så sjekk stavemåten. Funksjoner som abonnementet ditt ikke omfatter, utelates og belastes ikke.

Alle funksjoner med priser står i fetch-organization, hvert felt i Datakatalogen.

Kreditter

Dataforespørsler koster kreditter. For en firmaprofil gjelder disse reglene:

Grunnprisen på 5 kreditter gjelder når API-et returnerer et firma.
En funksjon koster bare kreditter når den returnerer data i svaret. En tom funksjon er gratis, også insolvency_publications uten oppføringer.
Sanntid og AI-modus er ikke funksjoner, men tillegg med egne regler:
- Sanntid koster 10 ekstra kreditter så snart live-hentingen lykkes. Det gjelder også når den ikke viser noe nytt.
- AI-modus koster 20 ekstra kreditter, også når den ikke finner noe firma. Tillegget faller bort bare når API-et avbryter forespørselen med 408 fordi den tar for lang tid.
Alle andre feil koster ingenting.

Regelen for hver enkelt funksjon står i Avregning, prisene i fetch-organization.

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

Før hver forespørsel sjekker API-et om saldoen din dekker den høyest mulige prisen. Gjør den ikke det, svarer API-et med 402 og belaster ingenting. Hva som faktisk ble belastet, står i meta.request_credit_cost, saldoen din etterpå i meta.credits_remaining.

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

200 · meta fra eksempelforespørselen vår med bare grunndata

Du får kreditter som startkreditter, hver måned med et kredittabonnement, eller én gang som påfyllskreditter. Uten kredittabonnement gjelder startkreditter og påfyllskreditter i 30 dager; med et aktivt abonnement utløper de ikke. Alt annet står i Avregning.

Aktuelle data og Sanntid

Som standard kommer firmaprofilen fra databasen vår. Hvor aktuell en opplysning er, avhenger av kilden.

Handelsregister

Grunndata, personer og registerkunngjøringer holder vi oppdatert i databasen vår ut fra registeret. Det går raskt og holder for de fleste formål.

Med Sanntid (realtime_mode=handelsregister-default) henter API-et Aktueller Abdruck (AD, aktuell utskrift) live fra Handelsregister (handelsregisteret) i det øyeblikket du sender forespørselen, og returnerer den som JSON. Du får også personene som er registrert nå, i related_persons.current, uten å betale for funksjonen.

Om live-hentingen fungerte, vises i _realtime_mode.status. Vi belaster de 10 kredittene for Sanntid bare ved success.

curl -G "https://handelsregister.ai/api/v1/fetch-organization" \
  -H "x-api-key: YOUR_API_KEY" \
  --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": "YOUR_API_KEY"},
    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": "YOUR_API_KEY" },
});
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 · Utdrag av et eksempelsvar med Sanntid for Hetzner Online GmbH

Mislykkes live-hentingen, returnerer API-et de lagrede dataene fra databasen vår. Det ser du på _realtime_mode.status, som da ikke er success. Sanntid belastes da ikke, noe meta.request_credit_cost også viser.

Sanntid lønner seg når dagens tilstand er viktig. For eksempel sjekker du nye forretningspartnere før signering, eller ser hvem som kan representere firmaet akkurat nå.

En Sanntid-henting tar lengre tid enn en vanlig. Sett tidsavbruddet i klienten din til minst 120 sekunder. Tar forespørselen for lang tid, svarer API-et med 408 og belaster ingenting. Prøv da igjen senere.

Årsregnskap

Vi ser etter nylig publiserte årsregnskap hver dag. Firmaene har imidlertid inntil tolv måneder etter regnskapsårets slutt på å publisere dem (§ 325 HGB), og mange bruker hele fristen. Noen firmaer oversitter bevisst den lovpålagte fristen og publiserer enda senere.

Det nyeste regnskapet gjelder derfor ofte året før i fjor. Mer i Aktualitet.

Insolvenskunngjøringer

Insolvensdomstolene publiserer kunngjøringene sine som regel samme dag som beslutningen eller kort tid etter. Du får dem via funksjonen insolvency_publications, hver med domstol, saksnummer og dato.

Nyheter

Funksjonen news returnerer nyheter om firmaet fra nettet, med tittel, kilde, dato og lenke. Hvor aktuelle de er, avhenger av når det sist ble skrevet om firmaet. For små firmaer finnes det ofte bare få passende saker.

Historikk og gyldighet

Mange opplysninger endrer seg over tid. API-et returnerer derfor den aktuelle tilstanden og historikken side om side:

current er tilstanden per i dag.
history lister opp hver registrert tilstand med effective_from og effective_to. Er effective_to null, gjelder tilstanden fortsatt i dag.
Personer står i related_persons.current og related_persons.past, hver med start_date og end_date.

Hver opplysning med historikk kommer fra registrene og publikasjonene, for eksempel fra Chronologischer Abdruck (CD, kronologisk utskrift) fra Handelsregister eller fra alle publiserte årsregnskap.

Slik ser det ut i eksempelet vårt for representasjonsreglene til Hetzner Online GmbH. I eksempelsvaret nevner de styret (Vorstand) frem til 28. juli 2015 og de daglige lederne siden da:

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}

Eksempelsvar: representation_scheme for Hetzner Online GmbH

De fleste datoer kommer i formatet YYYY-MM-DD. Hvor langt tilbake historikken går, er beskrevet i Alder og historikk.

Tomme verdier

Ikke alle firmaer har en verdi for hvert felt. API-et viser dette på to måter:

null: det finnes ingen verdi for dette feltet.
[]: listen har ingen oppføringer, for eksempel ingen insolvenskunngjøringer.

En forespurt funksjon uten data kommer som null eller [] og koster ingenting.

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}

Utdrag av et eksempelsvar for dm-drogerie markt GmbH + Co. KG, med tomme verdier

I koden din behandler du en manglende nøkkel, null og [] likt, fordi noen tomme objekter kommer som []. Les også feltene via navnene deres, fordi rekkefølgen på nøklene ikke er fast.

Mangler en verdi, må firmaet som regel ikke publisere den i det hele tatt. Hva loven krever avhengig av selskapsform og størrelse, er beskrevet i Datatilgjengelighet. Noen opplysninger holder vi bevisst tilbake; de har da redacted: true.

Stabilitet og versjoner

API-et vokser additivt. Nye data og funksjoner kommer som nye felt. Vi fjerner aldri eksisterende felt, vi gir dem ikke nye navn, og vi endrer verken typen eller betydningen deres. Slik er hver versjon bakoverkompatibel.

Endringer som ville ødelegge eksisterende kode, kommer bare i en ny API-versjon, for eksempel under /v2. Den aktuelle versjonen kjører under /v1.

La derfor klienten din ignorere ukjente felt og behandle ukjente verdier som et generelt tilfelle. Nye felt og funksjoner står i Endringsloggen.

Abonnementer

Firmaprofil, Dokumenter, Søk & eksport og Signals kan du bruke med hver konto, også uten kredittabonnement. Et kredittabonnement gir nye kreditter hver måned og låser opp flere data:

Abonnementer
Hva du får i tillegg	Plus	Pro	Max
Personprofil: Personers roller og eierandeler	inkludert	inkludert	inkludert
Søk & eksport: Filtre for eierskap, ledelse og insolvens	ikke inkludert	inkludert	inkludert
Firmaprofil: Over 90 utvidede økonomiske nøkkeltall	ikke inkludert	inkludert	inkludert
Firmaprofil: Regnskap for virksomhetsområder hos energiselskaper (§ 6b EnWG)	ikke inkludert	ikke inkludert	inkludert
Firmaprofil: Dype eierdata (`shareholders_deep`)	ikke inkludert	ikke inkludert	inkludert
Firmanettverk (`network`)	ikke inkludert	inkludert	inkludert
Signals: Insolvenser	ikke inkludert	inkludert	inkludert
Signals: Omdannelser og M&A	ikke inkludert	ikke inkludert	inkludert

API-et utelater funksjoner utenfor abonnementet ditt uten feil og belaster dem ikke. Personprofiler og søkefiltre utenfor abonnementet ditt avviser det med 403, også uten kostnad. For Signals gjelder dette temaer du ber om eksplisitt; ellers får du rett og slett alle temaene i abonnementet ditt.

Prisene og kredittene i abonnementene finner du på prissiden.

Videre

Hent en firmaprofil Navn, registernummer eller entity_id i praksis. Datatilgjengelighet Hvilke data som finnes avhengig av selskapsform og størrelse. Avregning Alle priser, og hvordan du sporer dem i hvert svar. Feil Hvordan feil ser ut, og hva du kan gjøre.