API

Olvano har et REST API til at forbinde dine egne systemer — opret og læs fakturaer, administrer kontakter og lyt til hændelser via webhooks. Denne side tager dig fra et token til dit første kald; den fulde, kørbare liste over endpoints findes i den interaktive reference.

Før du går i gang

Du har brug for to ting:

1. En konto på byznys-abonnementet (free-abonnementet har intet API).
2. Et API-token knyttet til den konto (se nedenfor).

Tokens oprettes af kontoens ejer. Ét token tilhører præcis én konto og bærer sine egne tilladelser (scopes), så du kan udstede et separat token pr. integration.

Oprettelse af et API-token

I appen skal du gå til Indstillinger → API-tokens (/app/{slug}/settings/api-tokens), vælge Nyt token, navngive det og vælge dets tilladelser. Tokenet i klartekst vises kun én gang — kopiér det med det samme, og opbevar det sikkert.

Tokens har præfikset sg_. Kun en HMAC-digest gemmes, så tokenet kan aldrig vises igen — mister du det, så opret et nyt og slet det gamle.

Tilladelser (scopes)

Læsning (GET) af almindelige ressourcer kræver ingen scope; skrivning gør. Operationer kun for ejere (administration af tokens, webhooks og bankkonti) er aldrig tilgængelige for et API-token — selv et udstedt af en ejer returnerer 403.

Godkendelse og base-URL

Godkend hver forespørgsel med tokenet i Authorization-headeren:

Authorization: Bearer sg_your_token

Base-URL'en er din instans' domæne + /api. Konto-endpoints har formen /api/accounts/{slug}/…. Eksemplerne nedenfor bruger miljøvariabler:

export STARGATE="https://app.stargate.app"   # replace with your instance domain (locally http://localhost:3000)
export SLUG="your-account-slug"
export TOKEN="sg_your_token"

Din første forespørgsel

List en kontos fakturaer:

curl "$STARGATE/api/accounts/$SLUG/invoices" \
  -H "Authorization: Bearer $TOKEN"

Svaret er en pagineret liste:

{
  "invoices": [ { "id": "…", "number": "2026-0001", "status": "open", "total": "3630.00" } ],
  "total": 128,
  "page": 1,
  "pageSize": 40
}

Paginering, sortering og søgning

List-endpoints accepterer disse query-parametre:

Fakturaer kan desuden filtreres efter status, documentType og subjectId. En ugyldig parameter ødelægger aldrig listen — standarden bruges i stedet (f.eks. ?page=abc → 1). Hvert svar indeholder total, page og pageSize, så sideantallet er let at udlede.

Oprettelse af en faktura

curl -X POST "$STARGATE/api/accounts/$SLUG/invoices" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "subjectId": "CUSTOMER_ID",
    "lines": [
      { "name": "Consulting", "quantity": 2, "unitPrice": "1500", "vatRate": 21 }
    ]
  }'

subjectId er kundens ID — hent det fra kontaktlisten (GET /api/accounts/$SLUG/subjects) eller opret en via POST …/subjects. Påkrævede felter er subjectId og mindst én linje i lines (hver med name og unitPrice). Valgfrit kan du sende documentType, currency, variableSymbol, due, issuedOn med flere — det fulde skema findes i den interaktive reference.

Ved succes returneres 201 og den oprettede faktura:

{ "invoice": { "id": "…", "number": "2026-0002", "status": "open", "total": "3630.00" } }

Fejl

Fejl deler en ensartet struktur — en HTTP-status plus JSON med statusMessage og et data-felt til maskinel håndtering:

{
  "statusCode": 400,
  "statusMessage": "Invalid invoice",
  "data": { "formErrors": [], "fieldErrors": { "subjectId": ["Required"] } }
}

Ved domænefejl er data.code en maskinlæsbar kode (f.eks. subject_not_found), som du kan stole mere på end på beskedteksten.

Abonnementsgrænser

Free-abonnementet foretager ingen API-kald (kvote 0); byznys har API'et og alle funktioner. Når en grænse overskrides (f.eks. antal kontakter), returnerer API'et 402 med plan_limit_reached; for en funktion uden for abonnementet (webhooks, udgifter …) returnerer det 403 med plan_feature_unavailable. Læs din kontos aktuelle grænser og forbrug via:

curl "$STARGATE/api/accounts/$SLUG/entitlements" -H "Authorization: Bearer $TOKEN"

Webhooks

En webhook giver dig besked om hændelser i realtid i stedet for at polle API'et. Webhooks er en funktion på byznys-abonnementet og administreres af kontoens ejer.

Registrér via API'et (eller i kontoindstillingerne):

curl -X POST "$STARGATE/api/accounts/$SLUG/webhooks" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "webhookUrl": "https://your-server.com/hooks/stargate",
    "events": ["invoice_paid", "invoice_sent"],
    "authHeader": "Bearer your-shared-secret"
  }'

Angiv specifikke navne i events, eller * for alle. Tilgængelige hændelser:

invoice_created, invoice_sent, invoice_paid, invoice_overdue, invoice_cancelled, invoice_uncollectible, invoice_viewed, invoice_reminder_sent, recurring_generator_invoice_created.

Olvano sender en POST til din URL med følgende body:

{ "event_name": "invoice_paid", "body": { "…": "event data" } }

• Hvis du angiver authHeader, sendes den som Authorization-header — brug den til at verificere, at forespørgslen virkelig kom fra Olvano.
• Hver levering bærer en Idempotency-Key-header (UUID) — brug den til at fjerne dubletter.
• Levering forsøges op til 5× med eksponentiel backoff, indtil du returnerer en 2xx-status. Mislykkede leveringer vises via GET …/webhooks/{id}/failed_deliveries.

Interaktiv reference

Den komplette, altid opdaterede liste over endpoints — med parametre, skemaer og mulighed for at kalde dem direkte fra browseren:

• Åbn API-referencen (/api-docs)
• Maskinlæsbart OpenAPI-skema: /api/_openapi.json