API-dokumentasjon: endepunkter og nøkler

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" \
  -H "Idempotency-Key: 3f1c9a2e-7b4d-4e8a-9c21-5d6e7f8a9b0c" \
  -d '{"fullName":"Kari Nordmann","email":"kari@bedrift.no"}' \
  https://<din-convex>.convex.site/api/v1/employees

Trygge nye forsøk (Idempotency-Key)

POST /employees, POST /webhooks og DELETE /webhooks/:id godtar headeren Idempotency-Key (maks 255 tegn). Bruk en ny, unik verdi per handling, for eksempel en UUID, og send den samme verdien når du prøver kallet på nytt. Da utføres handlingen bare én gang, og du får det første svaret tilbake med headeren Idempotent-Replayed: true. Sender du samme nøkkel med en annen body, svarer API-et 422 med koden idempotency_key_reused. Nøkkelen huskes i 24 timer.

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)
  );
}

Gjentatte leveranser

Svarer ikke endepunktet med 2xx, prøver vi igjen opptil tre ganger over omtrent en halvtime. Samme hendelse kan derfor komme mer enn én gang. Hver POST har to headere du kan deduplisere på:

X-Operra-Delivery-Id: likt for alle forsøk på samme leveranse til ditt endepunkt. Lagre den og hopp over verdier du har sett før.
X-Operra-Event-Id: likt for samme hendelse på tvers av alle endepunktene deres.
X-Operra-Delivery-Attempt: forsøksnummeret, fra 1.

API & Webhooks