API

Olvano ima REST API za povezovanje vaših sistemov — ustvarjajte in berite račune, upravljajte stike in poslušajte dogodke prek webhookov. Ta stran vas popelje od žetona do prvega klica; celoten, izvedljiv seznam končnih točk najdete v interaktivni referenci.

Preden začnete

Potrebujete dve stvari:

1. Uporabniški račun v paketu byznys (paket free nima API-ja).
2. API žeton, vezan na ta račun (glejte spodaj).

Žetone ustvari lastnik računa. En žeton pripada natanko enemu računu in nosi svoja dovoljenja (scopes), zato lahko za vsako integracijo izdate ločen žeton.

Ustvarjanje API žetona

V aplikaciji odprite Nastavitve → API žetoni (/app/{slug}/settings/api-tokens), izberite Nov žeton, ga poimenujte in izberite njegova dovoljenja. Žeton v čistem besedilu je prikazan samo enkrat — takoj ga kopirajte in varno shranite.

Žetoni imajo predpono sg_. Shrani se le zgostitev HMAC, zato žetona ni mogoče nikoli znova prikazati — če ga izgubite, ustvarite novega in starega izbrišite.

Dovoljenja (scopes)

Branje (GET) običajnih virov ne zahteva scope-a; pisanje ga. Operacije samo za lastnika (upravljanje žetonov, webhookov in bančnih računov) API žetonu niso nikoli na voljo — tudi tisti, ki ga izda lastnik, vrne 403.

Avtentikacija in osnovni URL

Vsak zahtevek avtenticirajte z žetonom v glavi Authorization:

Authorization: Bearer sg_your_token

Osnovni URL je domena vaše instance + /api. Končne točke računa imajo obliko /api/accounts/{slug}/…. Spodnji primeri uporabljajo okoljske spremenljivke:

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"

Vaš prvi zahtevek

Pridobite seznam računov za uporabniški račun:

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

Odgovor je seznam s paginacijo:

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

Paginacija, razvrščanje in iskanje

Končne točke s seznami sprejemajo te poizvedbene parametre:

Račune je mogoče dodatno filtrirati po status, documentType in subjectId. Neveljaven parameter nikoli ne pokvari seznama — namesto njega se uporabi privzeta vrednost (npr. ?page=abc → 1). Vsak odgovor vsebuje total, page in pageSize, zato je število strani enostavno izračunati.

Ustvarjanje računa

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 je ID stranke — pridobite ga s seznama stikov (GET /api/accounts/$SLUG/subjects) ali ga ustvarite prek POST …/subjects. Obvezna polja so subjectId in vsaj ena postavka v lines (vsaka z name in unitPrice). Neobvezno lahko pošljete documentType, currency, variableSymbol, due, issuedOn in drugo — celotna shema je v interaktivni referenci.

Ob uspehu vrne 201 in ustvarjeni račun:

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

Napake

Napake imajo enotno ovojnico — status HTTP ter JSON z statusMessage in poljem data za strojno obdelavo:

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

Pri domenskih napakah je data.code strojno berljiva koda (npr. subject_not_found), na katero se lahko zanesete bolj kot na besedilo sporočila.

Omejitve paketov

Paket free ne omogoča klicev API-ja (kvota 0); byznys ima API in vse funkcije. Ko je omejitev presežena (npr. število stikov), API vrne 402 s plan_limit_reached; za funkcijo zunaj paketa (webhooki, stroški …) vrne 403 s plan_feature_unavailable. Trenutne omejitve in porabo svojega računa preberete prek:

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

Webhooki

Webhook vas o dogodkih obvesti v realnem času, namesto da bi nenehno poizvedovali po API-ju. Webhooki so funkcija paketa byznys in jih upravlja lastnik računa.

Registrirajte ga prek API-ja (ali v nastavitvah računa):

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

V events vnesite konkretna imena ali * za vse. Razpoložljivi dogodki:

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

Olvano na vaš URL pošlje POST s telesom:

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

• Če nastavite authHeader, je poslan kot glava Authorization — z njim preverite, da je zahtevek res prišel od Olvano.
• Vsaka dostava nosi glavo Idempotency-Key (UUID) — uporabite jo za odstranjevanje podvojitev.
• Dostava se ponovi do 5× z eksponentnim zamikom, dokler ne vrnete statusa 2xx. Neuspele dostave so na voljo prek GET …/webhooks/{id}/failed_deliveries.

Interaktivna referenca

Popoln, vedno ažuren seznam končnih točk — s parametri, shemami in možnostjo klicanja neposredno iz brskalnika:

• Odprite API referenco (/api-docs)
• Strojno berljiva shema OpenAPI: /api/_openapi.json