API

Olvano ima REST API za povezivanje vlastitih sustava — stvaranje i čitanje računa, upravljanje kontaktima i osluškivanje događaja putem webhookova. Ova stranica vodi vas od tokena do prvog poziva; potpun, izvršiv popis krajnjih točaka nalazi se u interaktivnoj referenci.

Prije nego što počnete

Trebate dvije stvari:

1. Račun na byznys planu (free plan nema API).
2. API token vezan uz taj račun (pogledajte u nastavku).

Tokene stvara vlasnik računa. Jedan token pripada točno jednom računu i nosi vlastite dozvole (scopes), pa možete izdati zaseban token za svaku integraciju.

Stvaranje API tokena

U aplikaciji idite na Postavke → API tokeni (/app/{slug}/settings/api-tokens), odaberite Novi token, imenujte ga i odaberite njegove dozvole. Token u čistom tekstu prikazuje se samo jednom — odmah ga kopirajte i sigurno pohranite.

Tokeni imaju prefiks sg_. Pohranjuje se samo HMAC sažetak, pa se token nikada više ne može prikazati — ako ga izgubite, stvorite novi i izbrišite stari.

Dozvole (scopes)

Čitanje (GET) uobičajenih resursa ne zahtijeva scope; pisanje da. Operacije samo za vlasnika (upravljanje tokenima, webhookovima i bankovnim računima) nikada nisu dostupne API tokenu — čak i onaj koji je izdao vlasnik vraća 403.

Autentikacija i osnovni URL

Svaki zahtjev autenticirajte tokenom u zaglavlju Authorization:

Authorization: Bearer sg_your_token

Osnovni URL je domena vaše instance + /api. Krajnje točke računa imaju oblik /api/accounts/{slug}/…. Primjeri u nastavku koriste varijable okruženja:

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 zahtjev

Dohvatite popis računa nekog računa:

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

Odgovor je stranicirani popis:

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

Straničenje, sortiranje i pretraživanje

Krajnje točke s popisima prihvaćaju ove parametre upita:

Računi se dodatno mogu filtrirati prema status, documentType i subjectId. Neispravan parametar nikada ne ruši popis — umjesto njega koristi se zadana vrijednost (npr. ?page=abc → 1). Svaki odgovor nosi total, page i pageSize, pa je broj stranica lako izvesti.

Stvaranje 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 kupca — dohvatite ga s popisa kontakata (GET /api/accounts/$SLUG/subjects) ili stvorite novi putem POST …/subjects. Obavezna polja su subjectId i barem jedna stavka u lines (svaka s name i unitPrice). Po želji možete poslati documentType, currency, variableSymbol, due, issuedOn i drugo — potpuna shema u interaktivnoj referenci.

Uspjeh vraća 201 i stvoreni račun:

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

Pogreške

Pogreške dijele dosljedan ovojni format — HTTP status uz JSON s statusMessage i poljem data za strojnu obradu:

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

Kod domenskih pogrešaka data.code je strojno čitljiv kod (npr. subject_not_found) na koji se možete osloniti više nego na tekst poruke.

Ograničenja plana

Free plan ne radi nijedan API poziv (kvota 0); byznys ima API i sve značajke. Kada se ograničenje premaši (npr. broj kontakata), API vraća 402 s plan_limit_reached; za značajku izvan plana (webhookovi, troškovi…) vraća 403 s plan_feature_unavailable. Trenutna ograničenja i potrošnju svog računa pročitajte putem:

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

Webhookovi

Webhook vas u stvarnom vremenu obavještava o događajima, umjesto da ispitujete API. Webhookovi su značajka byznys plana i njima upravlja vlasnik računa.

Registrirajte ih putem API-ja (ili u postavkama 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"
  }'

U events stavite određena imena ili * za sve. Dostupni događaji:

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

Olvano šalje POST na vaš URL s tijelom:

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

• Ako postavite authHeader, šalje se kao zaglavlje Authorization — koristite ga da provjerite da je zahtjev doista stigao od Olvanoa.
• Svaka isporuka nosi zaglavlje Idempotency-Key (UUID) — koristite ga za uklanjanje duplikata.
• Isporuka se ponavlja do 5× s eksponencijalnim odmakom dok ne vratite 2xx status. Neuspjele isporuke navedene su putem GET …/webhooks/{id}/failed_deliveries.

Interaktivna referenca

Potpun, uvijek ažuran popis krajnjih točaka — s parametrima, shemama i mogućnošću da ih pozovete izravno iz preglednika:

• Otvorite API referencu (/api-docs)
• Strojno čitljiva OpenAPI shema: /api/_openapi.json