API

Olvanossa on REST-rajapinta omien järjestelmiesi yhdistämiseen — luo ja lue laskuja, hallitse yhteystietoja ja kuuntele tapahtumia webhookien kautta. Tämä sivu vie sinut tokenista ensimmäiseen kutsuusi; täydellinen, suoritettava lista endpointeista löytyy interaktiivisesta referenssistä.

Ennen kuin aloitat

Tarvitset kaksi asiaa:

1. Tilin byznys-tilauksella (free-tilauksessa ei ole APIa).
2. Kyseiseen tiliin sidotun API-tokenin (katso alla).

Tokenit luo tilin omistaja. Yksi token kuuluu täsmälleen yhteen tiliin ja sisältää omat oikeutensa (scopet), joten voit luoda erillisen tokenin jokaista integraatiota varten.

API-tokenin luominen

Mene sovelluksessa kohtaan Asetukset → API-tokenit (/app/{slug}/settings/api-tokens), valitse Uusi token, nimeä se ja valitse sen oikeudet. Token näytetään selkokielisenä vain kerran — kopioi se heti ja säilytä turvallisesti.

Tokeneilla on etuliite sg_. Vain HMAC-tiiviste tallennetaan, joten tokenia ei voi koskaan näyttää uudelleen — jos kadotat sen, luo uusi ja poista vanha.

Oikeudet (scopet)

Tavallisten resurssien lukeminen (GET) ei vaadi scopea; kirjoittaminen vaatii. Vain omistajalle sallitut toiminnot (tokenien, webhookien ja pankkitilien hallinta) eivät ole koskaan API-tokenin käytettävissä — omistajankin luoma palauttaa 403.

Tunnistautuminen ja perus-URL

Tunnistaudu jokaisessa pyynnössä tokenilla Authorization-otsakkeessa:

Authorization: Bearer sg_your_token

Perus-URL on instanssisi verkkotunnus + /api. Tilin endpointit ovat muotoa /api/accounts/{slug}/…. Alla olevat esimerkit käyttävät ympäristömuuttujia:

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"

Ensimmäinen pyyntösi

Listaa tilin laskut:

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

Vastaus on sivutettu lista:

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

Sivutus, järjestäminen ja haku

List-endpointit hyväksyvät nämä query-parametrit:

Laskuja voi lisäksi suodattaa kentillä status, documentType ja subjectId. Virheellinen parametri ei koskaan riko listaa — sen sijaan käytetään oletusta (esim. ?page=abc → 1). Jokainen vastaus sisältää total, page ja pageSize, joten sivumäärä on helppo johtaa.

Laskun luominen

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 on asiakkaan tunnus — hae se yhteystietolistasta (GET /api/accounts/$SLUG/subjects) tai luo uusi kutsulla POST …/subjects. Pakolliset kentät ovat subjectId ja vähintään yksi rivi lines-taulukossa (kullakin name ja unitPrice). Valinnaisesti voit lähettää documentType, currency, variableSymbol, due, issuedOn ja muita — täysi skeema interaktiivisessa referenssissä.

Onnistuessaan palautuu 201 ja luotu lasku:

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

Virheet

Virheillä on yhtenäinen rakenne — HTTP-status sekä JSON, jossa on statusMessage ja koneellista käsittelyä varten data-kenttä:

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

Toimialavirheissä data.code on koneluettava koodi (esim. subject_not_found), johon voit luottaa enemmän kuin viestin tekstiin.

Tilauksen rajat

Free-tilaus ei tee API-kutsuja (kiintiö 0); byznys sisältää APIn ja kaikki ominaisuudet. Kun raja ylittyy (esim. yhteystietojen määrä), API palauttaa 402 ja plan_limit_reached; tilauksen ulkopuoliselle ominaisuudelle (webhookit, kulut …) se palauttaa 403 ja plan_feature_unavailable. Lue tilisi nykyiset rajat ja käyttö:

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

Webhookit

Webhook ilmoittaa tapahtumista reaaliajassa sen sijaan, että kyselisit APIa. Webhookit ovat byznys-tilauksen ominaisuus, ja niitä hallitsee tilin omistaja.

Rekisteröi APIn kautta (tai tilin asetuksissa):

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

Anna tietyt nimet kenttään events tai * kaikille. Käytettävissä olevat tapahtumat:

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

Olvano lähettää POST-pyynnön URL-osoitteeseesi seuraavalla bodylla:

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

• Jos asetat authHeader-arvon, se lähetetään Authorization-otsakkeena — käytä sitä varmistaaksesi, että pyyntö todella tuli Olvanosta.
• Jokainen toimitus sisältää Idempotency-Key-otsakkeen (UUID) — käytä sitä duplikaattien poistoon.
• Toimitusta yritetään enintään 5× eksponentiaalisella backoffilla, kunnes palautat 2xx-statuksen. Epäonnistuneet toimitukset listataan kutsulla GET …/webhooks/{id}/failed_deliveries.

Interaktiivinen referenssi

Täydellinen, aina ajantasainen lista endpointeista — parametrein, skeemoin ja mahdollisuudella kutsua niitä suoraan selaimesta:

• Avaa API-referenssi (/api-docs)
• Koneluettava OpenAPI-skeema: /api/_openapi.json