API

Olvano har ett REST-API för att koppla ihop dina egna system — skapa och läs fakturor, hantera kontakter och lyssna på händelser via webhookar. Den här sidan tar dig från ett token till ditt första anrop; den fullständiga, körbara listan över endpoints finns i den interaktiva referensen.

Innan du börjar

Du behöver två saker:

1. Ett konto på byznys-abonnemanget (free-abonnemanget har inget API).
2. Ett API-token kopplat till det kontot (se nedan).

Token skapas av kontots ägare. Ett token tillhör exakt ett konto och bär sina egna behörigheter (scopes), så du kan utfärda ett separat token per integration.

Skapa ett API-token

I appen går du till Inställningar → API-token (/app/{slug}/settings/api-tokens), väljer Nytt token, namnger det och väljer dess behörigheter. Token i klartext visas bara en gång — kopiera det direkt och förvara det säkert.

Token har prefixet sg_. Endast en HMAC-digest lagras, så token kan aldrig visas igen — tappar du det skapar du ett nytt och raderar det gamla.

Behörigheter (scopes)

Att läsa (GET) vanliga resurser kräver ingen scope; att skriva gör det. Åtgärder enbart för ägare (hantera token, webhookar och bankkonton) är aldrig tillgängliga för ett API-token — även ett som utfärdats av en ägare returnerar 403.

Autentisering och bas-URL

Autentisera varje förfrågan med token i Authorization-huvudet:

Authorization: Bearer sg_your_token

Bas-URL:en är din instans domän + /api. Kontots endpoints har formen /api/accounts/{slug}/…. Exemplen nedan använder 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örsta förfrågan

Lista ett kontos fakturor:

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

Svaret är en paginerad lista:

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

Paginering, sortering och sökning

List-endpoints tar emot dessa query-parametrar:

Fakturor kan dessutom filtreras på status, documentType och subjectId. En ogiltig parameter förstör aldrig listan — standarden används i stället (t.ex. ?page=abc → 1). Varje svar innehåller total, page och pageSize, så antalet sidor är lätt att räkna ut.

Skapa 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 är kundens ID — hämta det från kontaktlistan (GET /api/accounts/$SLUG/subjects) eller skapa en med POST …/subjects. Obligatoriska fält är subjectId och minst en rad i lines (var och en med name och unitPrice). Valfritt kan du skicka documentType, currency, variableSymbol, due, issuedOn med flera — fullständigt schema i den interaktiva referensen.

Vid lyckat anrop returneras 201 och den skapade fakturan:

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

Fel

Fel delar en enhetlig struktur — en HTTP-status plus JSON med statusMessage och ett data-fält för maskinell hantering:

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

Vid domänfel är data.code en maskinläsbar kod (t.ex. subject_not_found) som du kan lita mer på än på meddelandetexten.

Abonnemangsgränser

Free-abonnemanget gör inga API-anrop (kvot 0); byznys har API:et och alla funktioner. När en gräns överskrids (t.ex. antal kontakter) returnerar API:et 402 med plan_limit_reached; för en funktion utanför abonnemanget (webhookar, utgifter …) returnerar det 403 med plan_feature_unavailable. Läs kontots aktuella gränser och förbrukning via:

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

Webhookar

En webhook meddelar dig om händelser i realtid i stället för att du pollar API:et. Webhookar är en funktion på byznys-abonnemanget och hanteras av kontots ägare.

Registrera via API:et (eller i kontoinställningarna):

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"
  }'

Ange specifika namn i events, eller * för alla. Tillgängliga händelser:

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

Olvano skickar en POST till din URL med följande body:

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

• Om du anger authHeader skickas den som Authorization-huvud — använd den för att verifiera att förfrågan verkligen kom från Olvano.
• Varje leverans bär ett Idempotency-Key-huvud (UUID) — använd det för att ta bort dubletter.
• Leverans görs om upp till 5× med exponentiell backoff tills du returnerar en 2xx-status. Misslyckade leveranser listas via GET …/webhooks/{id}/failed_deliveries.

Interaktiv referens

Den fullständiga, alltid aktuella listan över endpoints — med parametrar, scheman och möjlighet att anropa dem direkt från webbläsaren:

• Öppna API-referensen (/api-docs)
• Maskinläsbart OpenAPI-schema: /api/_openapi.json