API

Olvano turi REST API, skirtą jūsų sistemoms sujungti — kurkite ir skaitykite sąskaitas, tvarkykite kontaktus ir klausykitės įvykių per webhooks. Šis puslapis praves jus nuo rakto iki pirmojo užklausimo; visas, paleidžiamas galinių taškų sąrašas yra interaktyvioje dokumentacijoje.

Prieš pradedant

Jums reikia dviejų dalykų:

1. Paskyros su byznys planu (free planas API neturi).
2. Su ta paskyra susieto API rakto (žr. žemiau).

Raktus kuria paskyros savininkas. Vienas raktas priklauso lygiai vienai paskyrai ir turi savo teises (scopes), todėl kiekvienai integracijai galite išduoti atskirą raktą.

API rakto sukūrimas

Programoje eikite į Nustatymai → API raktai (/app/{slug}/settings/api-tokens), pasirinkite Naujas raktas, suteikite jam pavadinimą ir nurodykite teises. Atviro teksto raktas parodomas tik vieną kartą — iškart jį nukopijuokite ir saugiai išsaugokite.

Raktai turi priešdėlį sg_. Saugoma tik HMAC santrauka, todėl rakto vėliau parodyti nebeįmanoma — jei jį pametėte, sukurkite naują, o seną ištrinkite.

Teisės (scopes)

Bendrų išteklių skaitymui (GET) teisės nereikia; rašymui — reikia. Tik savininkui skirtos operacijos (raktų, webhooks ir banko sąskaitų valdymas) API raktui niekada neprieinamos — net savininko išduotas raktas grąžina 403.

Autentifikacija ir bazinis URL

Kiekvieną užklausą autentifikuokite raktu antraštėje Authorization:

Authorization: Bearer sg_your_token

Bazinis URL yra jūsų aplinkos domenas + /api. Paskyros galinių taškų formatas yra /api/accounts/{slug}/…. Žemiau pateiktuose pavyzdžiuose naudojami aplinkos kintamieji:

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"

Pirmasis užklausimas

Pateikite paskyros sąskaitų sąrašą:

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

Atsakymas yra puslapiuotas sąrašas:

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

Puslapiavimas, rikiavimas ir paieška

Sąrašo galiniai taškai priima šiuos užklausos parametrus:

Sąskaitas papildomai galima filtruoti pagal status, documentType ir subjectId. Neteisingas parametras sąrašo niekada nesugadina — vietoj jo naudojama numatytoji reikšmė (pvz., ?page=abc → 1). Kiekviename atsakyme yra total, page ir pageSize, todėl puslapių skaičių apskaičiuoti nesunku.

Sąskaitos kūrimas

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 yra kliento ID — jį gausite iš kontaktų sąrašo (GET /api/accounts/$SLUG/subjects) arba sukurkite naują per POST …/subjects. Privalomi laukai yra subjectId ir bent viena eilutė lines masyve (kiekviena su name ir unitPrice). Pasirinktinai galite siųsti documentType, currency, variableSymbol, due, issuedOn ir kt. — visa schema interaktyvioje dokumentacijoje.

Sėkmės atveju grąžinama 201 ir sukurta sąskaita:

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

Klaidos

Klaidos turi vienodą struktūrą — HTTP statusą ir JSON su statusMessage bei data lauku, skirtu apdoroti mašininiu būdu:

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

Dalykinių klaidų atveju data.code yra mašininiu būdu nuskaitomas kodas (pvz., subject_not_found), kuriuo galite pasikliauti labiau nei tekstu.

Plano limitai

Free planas API užklausų nevykdo (kvota 0); byznys turi API ir visas funkcijas. Pasiekus limitą (pvz., kontaktų skaičių) API grąžina 402 su plan_limit_reached; už planą išeinančiai funkcijai (webhooks, expenses…) grąžina 403 su plan_feature_unavailable. Dabartinius savo paskyros limitus ir naudojimą perskaitykite per:

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

Webhooks

Webhook praneša jums apie įvykius realiu laiku, užuot vykdžius pakartotines API užklausas. Webhooks yra byznys plano funkcija, kurią valdo paskyros savininkas.

Užregistruokite per API (arba paskyros nustatymuose):

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

Į events įrašykite konkrečius pavadinimus arba * visiems. Galimi įvykiai:

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

Olvano siunčia POST į jūsų URL su turiniu:

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

• Jei nustatėte authHeader, jis siunčiamas kaip antraštė Authorization — naudokite jį patikrinti, kad užklausa tikrai atėjo iš Olvano.
• Kiekvienas pristatymas turi antraštę Idempotency-Key (UUID) — naudokite ją dublikatams pašalinti.
• Pristatymas kartojamas iki 5× su eksponentiniu atidėjimu, kol grąžinsite 2xx statusą. Nepavykę pristatymai pateikiami per GET …/webhooks/{id}/failed_deliveries.

Interaktyvi dokumentacija

Pilnas, visada aktualus galinių taškų sąrašas — su parametrais, schemomis ir galimybe juos kviesti tiesiai iš naršyklės:

• Atidaryti API dokumentaciją (/api-docs)
• Mašininiu būdu nuskaitoma OpenAPI schema: /api/_openapi.json