API

Olvano heeft een REST API om je eigen systemen te koppelen — facturen aanmaken en uitlezen, contacten beheren en gebeurtenissen volgen via webhooks. Deze pagina brengt je van een token naar je eerste aanroep; de volledige, uitvoerbare lijst met endpoints vind je in de interactieve referentie.

Voordat je begint

Je hebt twee dingen nodig:

1. Een account op het byznys-abonnement (het free-abonnement heeft geen API).
2. Een API-token dat aan dat account is gekoppeld (zie hieronder).

Tokens worden aangemaakt door de accounteigenaar. Eén token hoort bij precies één account en draagt zijn eigen rechten (scopes), zodat je per integratie een apart token kunt uitgeven.

Een API-token aanmaken

Ga in de app naar Instellingen → API-tokens (/app/{slug}/settings/api-tokens), kies Nieuw token, geef het een naam en selecteer de rechten. Het token in platte tekst wordt maar één keer getoond — kopieer het meteen en bewaar het veilig.

Tokens beginnen met sg_. Er wordt alleen een HMAC-hash opgeslagen, dus het token kan nooit opnieuw worden getoond — ben je het kwijt, maak dan een nieuw aan en verwijder het oude.

Rechten (scopes)

Het lezen (GET) van veelgebruikte resources vereist geen scope; schrijven wel. Handelingen die alleen voor de eigenaar zijn (tokens, webhooks en bankrekeningen beheren) zijn nooit beschikbaar voor een API-token — zelfs een door een eigenaar uitgegeven token geeft 403 terug.

Authenticatie en basis-URL

Authenticeer elke aanvraag met het token in de Authorization-header:

Authorization: Bearer sg_your_token

De basis-URL is het domein van je instance + /api. Account-endpoints hebben de vorm /api/accounts/{slug}/…. De voorbeelden hieronder gebruiken omgevingsvariabelen:

export STARGATE="https://app.stargate.app"   # vervang door het domein van je instance (lokaal http://localhost:3000)
export SLUG="your-account-slug"
export TOKEN="sg_your_token"

Je eerste aanvraag

De facturen van een account opvragen:

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

De respons is een gepagineerde lijst:

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

Paginering, sortering en zoeken

De lijst-endpoints accepteren deze queryparameters:

Facturen kunnen daarnaast worden gefilterd op status, documentType en subjectId. Een ongeldige parameter breekt de lijst nooit — in plaats daarvan wordt de standaardwaarde gebruikt (bijv. ?page=abc → 1). Elke respons bevat total, page en pageSize, zodat het aantal pagina's eenvoudig is af te leiden.

Een factuur aanmaken

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 is de identificatie van de klant — haal die op uit de contactenlijst (GET /api/accounts/$SLUG/subjects) of maak er een aan via POST …/subjects. Verplichte velden zijn subjectId en minstens één regel in lines (elk met name en unitPrice). Optioneel kun je documentType, currency, variableSymbol, due, issuedOn en meer meesturen — volledig schema in de interactieve referentie.

Bij succes is de respons 201 met de aangemaakte factuur:

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

Fouten

Fouten delen een consistente envelope — een HTTP-status plus JSON met statusMessage en een data-veld voor geautomatiseerde verwerking:

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

Bij domeinfouten is data.code een machineleesbare code (bijv. subject_not_found) waarop je meer kunt vertrouwen dan op de tekst van de melding.

Abonnementslimieten

Het free-abonnement doet geen API-aanroepen (quotum 0); byznys heeft de API en alle functies. Wanneer een limiet wordt overschreden (bijv. het aantal contacten) geeft de API 402 met plan_limit_reached terug; voor een functie buiten het abonnement (webhooks, uitgaven…) geeft het 403 met plan_feature_unavailable terug. Lees de huidige limieten en het verbruik van je account uit via:

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

Webhooks

Een webhook stelt je in real time op de hoogte van gebeurtenissen, in plaats van de API te blijven pollen. Webhooks zijn een functie van het byznys-abonnement en worden beheerd door de accounteigenaar.

Registreer er een via de API (of in de accountinstellingen):

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

Zet specifieke namen in events, of * voor alle. Beschikbare gebeurtenissen:

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

Olvano stuurt een POST naar je URL met de body:

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

• Als je authHeader instelt, wordt die als Authorization-header meegestuurd — gebruik die om te controleren of de aanvraag echt van Olvano komt.
• Elke levering draagt een Idempotency-Key-header (UUID) — gebruik die om te ontdubbelen.
• De levering wordt tot 5× opnieuw geprobeerd met exponentiële backoff totdat je een 2xx-status teruggeeft. Mislukte leveringen worden opgesomd via GET …/webhooks/{id}/failed_deliveries.

Interactieve referentie

De volledige, altijd actuele lijst met endpoints — met parameters, schema's en de mogelijkheid om ze rechtstreeks vanuit de browser aan te roepen:

• Open de API-referentie (/api-docs)
• Machineleesbaar OpenAPI-schema: /api/_openapi.json