Integrer Companybook i egen kode

Denne guiden er skrevet for utviklere og kodeagenter som skal hente selskapsdata fra Companybook inn i et eget system, for eksempel et CRM, et datavarehus eller en kundeliste som skal berikes hver natt. Følg stegene i rekkefølge. Alt som står her kan kontrolleres mot OpenAPI-kontrakten.

1. Hva du trenger

• En Companybook-konto med Plus. REST API er en del av Plus (personlig) og Business Plus (team). Free-kontoer kan bruke MCP, men får 403 plan_required på REST. Kontoer opprettes i lukket beta via ventelisten.
• En API-nøkkel. Opprett den under Agenttilgang → Ny tilgang. Er du medlem av et team med Business Plus, velg teamet under Trekk credits fra, så belastes teamets felles saldo.
• Nøkkelen i en miljøvariabel på serveren, for eksempel COMPANYBOOK_API_KEY. Aldri i kildekode, logger, nettleserkode eller en chat.

Kontroller tilgangen før du bygger noe:

curl -s https://companybook.co/api/v1/me -H "Authorization: Bearer $COMPANYBOOK_API_KEY"

Svaret skal ha "api_access": true. Feltet credential gjelder nøkkelen du kaller med: billed_to (personal eller team), hvilken saldo som belastes (credential.credits), grensene (credential.limits) og hvor mye som er brukt i dag og denne måneden (credential.used). For en teamnøkkel er det teamets saldo og grenser som gjelder; credits på toppnivå er brukerens personlige saldo. /me og /capabilities virker på alle planer; resten krever Plus.

2. Slik er API-et bygget opp

Base-URL er https://companybook.co/api/v1. Alle svar på dataoperasjoner er en cb/v1-konvolutt med data, coverage, warnings, as_of, truncated og cost.

Selskaps-ID-er har formen cb:org:<organisasjonsnummer>, for eksempel cb:org:923609016. Et organisasjonsnummer er alltid 9 siffer.

3. Hent mange selskaper i ett kall

Har du organisasjonsnumrene, bruk POST /entities/batch med extend:

curl -s https://companybook.co/api/v1/entities/batch \
  -H "Authorization: Bearer $COMPANYBOOK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": ["cb:org:923609016", "cb:org:817209882"],
    "extend": ["financial_history", "subunits", "web_identities", "group_parent"]
  }'

• ids: 1–100 ID-er per kall. Anbefalt: 50 per kall når du bruker alle fire utvidelsene, og kall sekvensielt, ikke parallelt.
• extend er valgfritt. Utelat utvidelser du ikke trenger; hver utvidelse øker datamengden som måles.
• include er noe annet: relasjoner (kanter) følger bare med når du ber om dem, for eksempel ["HAS_ROLE"], eller ["*"] for alle. Uten include får du ingen kanter, men hvert selskap har active_predicates som viser hvilke relasjoner som finnes og hvor mange. Kanter teller som poster.

Felter per selskap (data.entities[].payload)

Et felt som mangler i payload, er ukjent. Det betyr ikke false eller 0.

Utvidelser (data.extensions, nøklet på organisasjonsnummer)

Kontaktinformasjon som e-post og telefon leveres ikke via API-et.

Utvidelsene gjelder selskapet du ber om. For en underenhet ligger regnskap, konsern og ofte nettsted på hovedenheten: hent parent_org_nr i samme eller neste kall.

4. SDK for TypeScript og JavaScript (beta)

@companybook/sdk pakker stegene over: nøkkelkontroll, batcher på 50, sekvensielle kall, Retry-After ved 429 og typede feil. Ingen avhengigheter; krever Node 20 eller nyere.

import { Companybook } from '@companybook/sdk';

const cb = new Companybook({ apiKey: process.env.COMPANYBOOK_API_KEY });
const { entities, extensions, missing, units } = await cb.entities.batchAll(orgNumbers, {
  extend: ['financial_history', 'web_identities', 'group_parent'],
});
const { subunits, truncated } = await cb.entities.subunits('817209882');
const left = await cb.remaining(); // poster og kall igjen i dag og denne måneden

Feil kommer som CompanybookError med status, code, retryAfter og fatal (401, 402, 403: stopp kjøringen).

5. Når du bare har et navn

Bruk GET /resolve og kontroller treffet før du lagrer koblingen:

curl -s -G https://companybook.co/api/v1/resolve \
  -H "Authorization: Bearer $COMPANYBOOK_API_KEY" \
  --data-urlencode 'query=Vinmonopolet' \
  --data-urlencode 'types=["org"]' \
  --data-urlencode 'limit=5'

score rangerer kandidatene, men er ikke en sannsynlighet. Godta et treff automatisk bare når navnet og postnummeret eller poststedet stemmer med det du har fra før. Ellers: legg det til manuell kontroll.

6. Forbruk og grenser

• All bruk måles, også gratis data. Grunndata koster 0 credits, men teller mot volumgrensene: på Plus 120 kall i minuttet, 10 000 kall og 50 000 poster per døgn. Utvidelser teller som poster.
• API-et reserverer plass før kallet og avregner faktisk mengde etterpå. Et kall med 100 ID-er og alle utvidelser reserverer mye, men belaster bare det som leveres.
• Sjekk credential.used og credential.limits i GET /me før en stor kjøring; tellerne er de samme som grensene håndheves mot, og credential.resets sier når døgnet og måneden nullstilles (UTC).
• Følg eget forbruk i bruksoversikten eller med GET /usage. Teamnøkler vises under teamet i bruksoversikten.

7. Feil og hva du skal gjøre

8. Anbefalt oppsett for en nattlig synk

1. Les listen over organisasjonsnumre fra ditt eget system og fjern duplikater.
2. Del opp i grupper på 50 og kall POST /entities/batch sekvensielt med de utvidelsene du trenger.
3. Lagre as_of sammen med dataene. Hent ikke samme selskap oftere enn én gang i døgnet: registerdata endrer seg sjelden raskere.
4. Ved 429: vent Retry-After og fortsett der du slapp. Ved 403 eller 401: avbryt hele kjøringen og varsle.
5. Logg antall selskaper, antall mangler (coverage.missing) og cost.units per kjøring. Logg aldri nøkkelen.

9. Slik vet du at integrasjonen virker

• GET /me gir api_access: true.
• Et batch-kall med cb:org:923609016 (Equinor ASA) gir entity_type: "hovedenhet" og flere år i data.extensions.financial_history["923609016"].
• Et kall med en ID som ikke finnes gir ID-en i coverage.missing, ikke en feil.
• Forbruket vises i bruksoversikten innen et minutt.

Mer

• OpenAPI-kontrakt — autoritativ beskrivelse av alle operasjoner.
• MCP-guide — for agenter som kobler seg til med MCP i stedet for REST.
• Plan og tilgang — hva som inngår i Free og Plus.