API for utviklere | Byggvekst

Oversikt

Dette API-et er laget for maskin-til-maskin-integrasjoner: eksportere og oppdatere data i Byggvekst fra egne systemer, eller motta hendelser via webhooks.

Opprette og administrere API-nøkler gjør du i Byggvekst-appen under Innstillinger → Integrasjoner (API-nøkler). Hver nøkkel kan begrenses med egne scopes, slik at integrasjonen bare får tilgang til det den trenger.

Base-URL og versjon

Alle kall går mot versjonerte stier under /api/public/v1. I produksjon er basis typisk:

https://app.byggvekst.no/api/public/v1

Egen drift: Hvis dere kjører eget miljø, bytt ut vert med app-domenet deres.

Autentisering

Beskyttede endepunkter krever en Bearer-token i Authorization-headeren. Tokenet er API-nøkkelen deres, med formatet:

Authorization: Bearer bcrm_<lookup>_<hemmelighet>

Nøkkelen utstedes når du oppretter en integrasjonsnøkkel i appen. Del den aldri i klient-side kode, loggfiler som lekker offentlig, eller i versjonskontroll.

Tilganger (scopes)

Hver nøkkel har ett eller flere scopes. Wildcard * gir alle tilganger knyttet til nøkkelen (bruk med omtanke).

Scope	Brukes til
`clients:read`	Les kunder (liste, søk, enkeltkunde)
`clients:write`	Opprette kunder
`quotes:read`	Les tilbud, tilbudsmaler
`quotes:write`	Opprette og oppdatere tilbud
`products:read`	Les produkter
`webhooks:manage`	Registrere, liste, endre og slette webhook-endepunkter

Rate limit og idempotens

Rate limit: Autentiserte kall er begrenset per API-nøkkel (standard ca. 400 forespørsler per 15 minutter; kan overstyres med miljøvariabel på server). Når grensen nås, svarer API-et med rate-limit-headers og HTTP 429.

Idempotens: For POST /clients og POST /quotes kan du sende headeren Idempotency-Key (eller X-Idempotency-Key) med en unik streng per logisk operasjon. Gjentatte kall med samme nøkkel innen 24 timer returnerer det samme svaret som første vellykkede kall, slik at du unngår duplikater ved nettverksfeil eller retries.

Beskyttede ressurser

Alle stier som listes her krever gyldig Bearer-token. Feltene for forespørsel og svar er beskrevet for hvert endepunkt på denne siden.

GET /me

Returnerer selskap, nøkkel-id, navn på nøkkel og scopes for tokenet dere bruker.

Tilgang: gyldig nøkkel (alle scopes kan kalle).

GET /clients

Liste eller søk i kunder med paginering (limit, offset), fritekst search, filtre (name, email, phone, address, client_id) og updated_since (ISO-tidspunkt).

Scope: clients:read

POST /clients

Opprett ny kunde. Støtter idempotens-header.

Scope: clients:write

GET /clients/{id}

Hent én kunde på numerisk database-id.

Scope: clients:read

GET /quotes

Oversikt over tilbud med paginering og enkel søk.

Scope: quotes:read

POST /quotes

Opprett tilbud. Krever blant annet gyldig client_id. Valgfritt quote_template_id for å starte fra mal. Idempotens-header støttes. Kunden må tilhøre samme selskap som nøkkelen.

Scope: quotes:write

GET /quotes/{id}

Hent fullt tilbud (inkl. linjer og vedlegg der det finnes). {id} er tilbudets eksterne ID (typisk streng som QID_…, feltet quote_id) eller alternativt numerisk database-id fra Byggvekst.

Scope: quotes:read

PATCH /quotes/{id}

Oppdater tilbud. Bruk samme identifikator som i app og API-respons: tilbudets quote_id (streng, typisk QID_…). Numerisk database-id støttes også for bakoverkompatibilitet.

Scope: quotes:write

GET /products

Liste produkter for selskapet.

Scope: products:read

GET /products/{id}

Hent ett produkt.

Scope: products:read

GET /quote-templates

List maler for tilbud i selskapet (typisk brukt sammen med oppretting av tilbud).

Scope: quotes:read

GET /webhooks/endpoints

List registrerte webhook-URL-er, hendelser og status.

Scope: webhooks:manage

POST /webhooks/endpoints

Registrer nytt endepunkt. Signeringshemmelighet (whsec_…) returneres bare ved opprettelse — lagre den sikkert. URL må være offentlig tilgjengelig (private IP og liknende er blokkert).

Scope: webhooks:manage

PATCH /webhooks/endpoints/{id}

Skru endepunkt av/på eller oppdater etikett (label).

Scope: webhooks:manage

DELETE /webhooks/endpoints/{id}

Fjern webhook-endepunkt.

Scope: webhooks:manage

Utgående webhooks

Når hendelser inntreffer (for eksempel client.created eller quote.created), sender Byggvekst et POST med JSON til de aktive endepunktene som abonnerer på hendelsen (eller på *).

Kropp: JSON med feltene type (hendelsesnavn), created_at (ISO-tidspunkt) og data (hendelseslast, f.eks. opprettet kunde eller tilbud).

Signering: HTTP-headeren X-Byggvekst-Signature inneholder HMAC-SHA256 av den rå JSON-kroppen, i formatet sha256=<hex>, beregnet med din hemmelighet whsec_…. Verifiser alltid signaturen før du stoler på payloaden.

Øvrige headers er X-Byggvekst-Event (som type) og X-Byggvekst-Delivery (leveranse-id for feilsøking).

Vanlige feilkoder

HTTP	Betydning
`400`	Ugyldig forespørsel (manglende felt, feil id-format, blokkert webhook-URL, osv.)
`401`	Manglende eller ugyldig API-nøkkel
`403`	Nøkkel mangler påkrevd scope
`404`	Ressurs ikke funnet eller tilhører ikke selskapet
`429`	Rate limit overskredet
`500` / `503`	Serverfeil eller midlertidig utilgjengelighet (inkl. manglende DB-migrering for API/webhooks)