Grundbegrepp

Parametern q i fetch-organization tar emot tre sorters indata. Exemplen på den här sidan är förfrågningar för Hetzner Online GmbH, Ansbach HRB 6089:

Enbart registernumret räcker inte, eftersom varje registerdomstol tilldelar sina egna nummer. Ordningen är däremot fri: i exemplet hittar HRB 6089 Ansbach samma företag.

Om API:et inte hittar något företag svarar det med 404 och debiterar ingenting. För otydlig indata finns AI-läget (ai_search=on-default): det hittar företaget även från delar av namnet och researchar det på webben. Det kostar 20 extra krediter, även om det inte hittar något företag. För att få flera kandidater på en gång använder du Sök & export.

Varje företagsprofil innehåller grunddata, bland annat namn, bolagsform, status, registeranteckning, adress, verksamhetsföremål, bransch, kapital och företrädarregler. Allt annat begär du som funktion (feature), till exempel related_persons för de verkställande direktörerna eller financial_kpi för de finansiella nyckeltalen.

Flera funktioner skickar du med upprepad feature eller som lista: features=related_persons,financial_kpi. Varje funktion visas i svaret under sin egen nyckel. Bara publications heter history där.

API:et ignorerar okända namn utan felmeddelande, så kontrollera stavningen. Funktioner som din plan inte omfattar utelämnas och debiteras inte.

Alla funktioner med sina priser finns i fetch-organization, varje fält i Datakatalogen.

Dataförfrågningar kostar krediter. För en företagsprofil gäller dessa regler:

• Grundpriset på 5 krediter gäller när API:et returnerar ett företag.
• En funktion kostar krediter bara när den returnerar data i svaret. En tom funktion är gratis, även insolvency_publications utan poster.
• Realtid och AI-läge är inte funktioner utan tillägg med egna regler:
  • Realtid kostar 10 extra krediter så snart live-hämtningen lyckas. Det gäller även när den inte visar något nytt.
  • AI-läget kostar 20 extra krediter, även om det inte hittar något företag. Tillägget bortfaller bara när API:et avbryter förfrågan med 408 för att den tar för lång tid.
• Alla andra fel kostar ingenting.

Regeln för varje enskild funktion finns i Debitering, priserna i fetch-organization.

Ett exempel: grunddata med related_persons och financial_kpi kostar 5 + 2 + 1 = 8 krediter om båda funktionerna returnerar data.

Före varje förfrågan kontrollerar API:et om ditt saldo täcker det högsta möjliga priset. Om inte svarar API:et med 402 och debiterar ingenting. Vad som faktiskt debiterades står i meta.request_credit_cost, ditt saldo efteråt i meta.credits_remaining.

Du får krediter som startkrediter, varje månad med en kreditprenumeration, eller en gång som påfyllningskrediter. Utan kreditprenumeration är startkrediter och påfyllningskrediter giltiga i 30 dagar; med en aktiv prenumeration förfaller de inte. Allt annat finns i Debitering.

Som standard kommer företagsprofilen från vår databas. Hur aktuell en uppgift är beror på dess källa.

Vi håller grunddata, personer och registerkungörelser aktuella i vår databas från registret. Det är snabbt och räcker för de flesta ändamål.

Med Realtid (realtime_mode=handelsregister-default) hämtar API:et Aktueller Abdruck (AD, aktuellt utdrag) live från Handelsregister (handelsregistret) i ögonblicket för din förfrågan och returnerar det som JSON. Du får även de nu registrerade personerna i related_persons.current, utan att betala för funktionen.

Om live-hämtningen fungerade visas i _realtime_mode.status. Vi debiterar de 10 krediterna för Realtid bara vid success.

Om live-hämtningen misslyckas returnerar API:et sparade data från vår databas. Det ser du på _realtime_mode.status, som då inte är success. Realtid debiteras då inte, vilket även meta.request_credit_cost visar.

Realtid lönar sig när dagens läge spelar roll. Till exempel när du kontrollerar nya affärspartner innan ni skriver avtal, eller ser vem som får företräda företaget just nu.

Vi letar efter nypublicerade årsbokslut varje dag. Företagen har dock upp till tolv månader efter räkenskapsårets slut på sig att publicera dem (§ 325 HGB), och många utnyttjar hela fristen. Vissa företag missar medvetet den lagstadgade fristen och publicerar ännu senare.

Det senaste bokslutet avser därför ofta året före förra året. Mer i Aktualitet.

Insolvensdomstolarna publicerar oftast sina kungörelser samma dag som beslutet eller kort därefter. Du får dem via funktionen insolvency_publications, var och en med domstol, målnummer och datum.

Funktionen news returnerar nyheter om företaget från webben, med rubrik, källa, datum och länk. Hur aktuella de är beror på när det senast rapporterades om företaget. För små företag finns det ofta bara ett fåtal passande artiklar.

Många uppgifter ändras över tid. API:et returnerar därför det aktuella läget och historiken sida vid sida:

• current är läget per i dag.
• history listar varje registrerat tillstånd med effective_from och effective_to. Om effective_to är null gäller tillståndet fortfarande i dag.
• Personer finns i related_persons.current och related_persons.past, var och en med start_date och end_date.

Varje uppgift med historik kommer från registren och publikationerna, till exempel från Chronologischer Abdruck (CD, kronologiskt utdrag) i Handelsregister eller från alla publicerade årsbokslut.

Så här ser det ut i vårt exempel för företrädarreglerna hos Hetzner Online GmbH. I exempelsvaret nämner de styrelsen (Vorstand) fram till den 28 juli 2015 och de verkställande direktörerna sedan dess:

De flesta datum kommer i formatet YYYY-MM-DD. Hur långt bakåt historiken sträcker sig beskrivs i Ålder och historik.

Inte varje företag har ett värde för varje fält. API:et visar det på två sätt:

• null: det finns inget värde för detta fält.
• []: listan har inga poster, till exempel inga insolvenskungörelser.

En begärd funktion utan data kommer som null eller [] och kostar ingenting.

Behandla i din kod en saknad nyckel, null och [] likadant, eftersom vissa tomma objekt kommer som []. Läs också fälten via deras namn, eftersom nycklarnas ordning inte är fast.

Om ett värde saknas behöver företaget oftast inte publicera det alls. Vad lagen kräver beroende på bolagsform och storlek beskrivs i Datatillgänglighet. Vissa uppgifter håller vi medvetet tillbaka; de har då redacted: true.

API:et växer additivt. Nya data och funktioner kommer som nya fält. Vi tar aldrig bort befintliga fält, vi byter inte namn på dem, och vi ändrar varken deras typ eller betydelse. Därmed förblir varje version bakåtkompatibel.

Ändringar som skulle bryta befintlig kod kommer bara i en ny API-version, till exempel under /v2. Den aktuella versionen körs under /v1.

Låt därför din klient ignorera okända fält och behandla okända värden som ett allmänt fall. Nya fält och funktioner listas i Changelog.

Företagsprofil, Dokument, Sök & export och Signals kan du använda med varje konto, även utan kreditprenumeration. En kreditprenumeration ger nya krediter varje månad och låser upp mer data:

API:et utelämnar funktioner utanför din plan utan fel och debiterar dem inte. Personprofiler och sökfilter utanför din plan avvisas med 403, också utan kostnad. För Signals gäller detta ämnen som du uttryckligen begär; annars får du helt enkelt alla ämnen i din plan.

Planernas priser och krediter hittar du på prissidan.