API-dokumentasjon

Integrer dine egne systemer med Operra. Du lager API-nøkler selv under Integrasjoner i dashbordet — der ser du også nøyaktig hvilken URL du skal kalle.

Kom i gang

Operra API-en er en REST-tjeneste som lar deg lese og skrive data fra dine egne systemer.

Base URL: https://<din-convex>.convex.site/api/v1
Format: JSON
Autentisering: Bearer token
Rate-limit: 60 kall/min standard, justerbar per kunde

Autentisering

Alle kall krever en Bearer-token i Authorization-headeren. Nøkkelen begynner med opk_ og lages av bedriftens egen admin under Integrasjoner. Base-URL-en (på formen https://<din-convex>.convex.site/api/v1) vises når du oppretter nøkkelen.

curl -H "Authorization: Bearer opk_xxxxxxxx" \
  https://<din-convex>.convex.site/api/v1/organization

Endepunkter

Tilgjengelig i v1:

GET/organizationReturnerer informasjon om din bedrift

GET/employeesListe over alle ansatte (filter: active, department)

POST/employeesOpprett ny ansatt

GET/employees/:idHent én ansatt

GET/shiftsListe over vakter (filter: from, to)

GET/customersListe over kunder

GET/regnskap/entitiesRegnskapsenheter (krever regnskap:read)

GET/regnskap/vouchersBilag (regnskap:read)

GET/regnskap/vouchers/:idEtt bilag med posteringer (regnskap:read)

GET/regnskap/accountsKontoplan (regnskap:read)

GET/regnskap/reports/saldobalanseSaldobalanse (regnskap:read)

Eksempel: opprett ansatt

curl -X POST -H "Authorization: Bearer opk_xxx" \
  -H "Content-Type: application/json" \
  -d '{"fullName":"Kari Nordmann","email":"kari@bedrift.no"}' \
  https://<din-convex>.convex.site/api/v1/employees

Webhooks

Operra POST-er events til en URL du oppgir når noe skjer i kontoen din. Bruk dette for å holde dine egne systemer synkronisert.

Event-typer

voucher.posted — et bilag ble bokført
voucher.reversed — et bilag ble reversert
employee.created — ny ansatt opprettet
employee.updated — ansatt oppdatert
* — bruk for å motta alle events

Payload-format

{
  "event": "employee.created",
  "organizationId": "kg2...",
  "payload": {
    "id": "j9k...",
    "fullName": "Kari Nordmann",
    "email": "kari@bedrift.no"
  },
  "timestamp": 1716393600000
}

Signaturverifisering

Hver webhook POST inkluderer en X-Operra-Signature-header med HMAC-SHA256 av payloaden, signert med din webhook-secret.

import crypto from "crypto";

function verifyWebhook(body, signature, secret) {
  const expected = "sha256=" + crypto
    .createHmac("sha256", secret)
    .update(body)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

API & Webhooks