API

Olvano'il on REST-API oma süsteemide ühendamiseks — loo ja loe arveid, halda kontakte ja kuula sündmusi webhookide kaudu. See leht juhatab sind tokenist esimese päringuni; täielik, käivitatav lõpp-punktide loend asub interaktiivses viites.

Enne kui alustad

Sul on vaja kahte asja:

1. Kontot byznys paketis (free paketil API-t pole).
2. Selle kontoga seotud API tokenit (vt allpool).

Tokeneid loob konto omanik. Üks token kuulub täpselt ühele kontole ja kannab oma õigusi (scope'e), nii et saad väljastada iga integratsiooni jaoks eraldi tokeni.

API tokeni loomine

Mine rakenduses Seaded → API tokenid (/app/{slug}/settings/api-tokens), vali Uus token, anna sellele nimi ja vali õigused. Token kuvatakse avatekstina ainult üks kord — kopeeri see kohe ja hoia turvaliselt.

Tokenitel on eesliide sg_. Salvestatakse ainult HMAC-räsi, nii et tokenit ei saa enam kunagi uuesti kuvada — kui kaotad selle, loo uus ja kustuta vana.

Õigused (scope'id)

Tavaliste ressursside lugemiseks (GET) ei ole scope'i vaja; kirjutamiseks on. Ainult omanikule mõeldud toimingud (tokenite, webhookide ja pangakontode haldamine) ei ole API tokenile kunagi kättesaadavad — isegi omaniku väljastatud token tagastab 403.

Autentimine ja baas-URL

Autendi iga päring tokeniga Authorization päises:

Authorization: Bearer sg_your_token

Baas-URL on sinu instantsi domeen + /api. Konto lõpp-punktid on kujul /api/accounts/{slug}/…. Allolevad näited kasutavad keskkonnamuutujaid:

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"

Sinu esimene päring

Kuva konto arvete loend:

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

Vastus on lehekülgedeks jaotatud loend:

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

Lehekülgedeks jaotamine, sorteerimine ja otsing

Loendi lõpp-punktid aktsepteerivad järgmisi päringuparameetreid:

Arveid saab lisaks filtreerida väljade status, documentType ja subjectId järgi. Vigane parameeter ei riku kunagi loendit — selle asemel kasutatakse vaikeväärtust (nt ?page=abc → 1). Iga vastus sisaldab välju total, page ja pageSize, nii et lehekülgede arvu on lihtne tuletada.

Arve loomine

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 kliendi ID — leia see kontaktide loendist (GET /api/accounts/$SLUG/subjects) või loo uus käsuga POST …/subjects. Kohustuslikud väljad on subjectId ja vähemalt üks rida väljas lines (igaühel name ja unitPrice). Valikuliselt saad saata documentType, currency, variableSymbol, due, issuedOn ja palju muud — täielik skeem interaktiivses viites.

Õnnestumisel tagastatakse 201 ja loodud arve:

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

Vead

Vigadel on ühtne struktuur — HTTP staatus pluss JSON väljadega statusMessage ja data masintöötluse jaoks:

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

Domeenivigade puhul on data.code masinloetav kood (nt subject_not_found), millele võid rohkem toetuda kui sõnumitekstile.

Paketi limiidid

Free pakett ei tee ühtegi API-päringut (kvoot 0); byznys sisaldab API-t ja kõiki funktsioone. Kui limiit ületatakse (nt kontaktide arv), tagastab API 402 koodiga plan_limit_reached; paketist välja jääva funktsiooni puhul (webhookid, kulud…) tagastab see 403 koodiga plan_feature_unavailable. Loe oma konto praeguseid limiite ja kasutust käsuga:

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

Webhookid

Webhook teavitab sind sündmustest reaalajas, selle asemel et API-t pidevalt pärida. Webhookid on byznys paketi funktsioon ja neid haldab konto omanik.

Registreeri API kaudu (või konto seadetes):

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

Pane väljale events konkreetsed nimed või * kõigi jaoks. Saadaolevad sündmused:

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

Olvano saadab sinu URL-ile POST-päringu kehaga:

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

• Kui määrad authHeader, saadetakse see Authorization päisena — kasuta seda, et kontrollida, kas päring tuli tõesti Olvano'ist.
• Iga kohaletoimetamine kannab Idempotency-Key päist (UUID) — kasuta seda dubleerimise vältimiseks.
• Kohaletoimetamist proovitakse uuesti kuni 5× eksponentsiaalse viivitusega, kuni tagastad 2xx staatuse. Ebaõnnestunud kohaletoimetamised leiad käsuga GET …/webhooks/{id}/failed_deliveries.

Interaktiivne viide

Täielik, alati ajakohane lõpp-punktide loend — koos parameetrite, skeemide ja võimalusega kutsuda neid otse brauserist:

• Ava API viide (/api-docs)
• Masinloetav OpenAPI skeem: /api/_openapi.json