API

Olvano má REST API na prepojenie s vlastnými systémami — vytvárajte a načítavajte faktúry, spravujte kontakty a počúvajte udalosti cez webhooky. Táto stránka vás prevedie od tokenu k prvému volaniu; úplný, spustiteľný zoznam endpointov nájdete v interaktívnej referencii.

Než začnete

Potrebujete dve veci:

1. Účet v tarife byznys (tarif free nemá API).
2. API token viazaný na tento účet (pozri nižšie).

Tokeny vytvára vlastník účtu. Jeden token patrí práve jednému účtu a nesie vlastné oprávnenia (scopes), takže pre každú integráciu môžete vystaviť samostatný token.

Vytvorenie API tokenu

V aplikácii prejdite na Nastavenia → API tokeny (/app/{slug}/settings/api-tokens), zvoľte Nový token, pomenujte ho a vyberte jeho oprávnenia. Token v čitateľnej podobe sa zobrazí iba raz — okamžite si ho skopírujte a bezpečne uložte.

Tokeny majú predponu sg_. Ukladá sa len HMAC odtlačok, takže token už nikdy nemožno znovu zobraziť — ak ho stratíte, vytvorte nový a starý zmažte.

Oprávnenia (scopes)

Čítanie (GET) bežných zdrojov nevyžaduje žiadny scope; zápis áno. Operácie len pre vlastníka (správa tokenov, webhookov a bankových účtov) nie sú pre API token nikdy dostupné — aj token vystavený vlastníkom vráti 403.

Autentifikácia a základná URL

Každú požiadavku autentifikujte tokenom v hlavičke Authorization:

Authorization: Bearer sg_your_token

Základná URL je doména vašej inštancie + /api. Endpointy účtu majú tvar /api/accounts/{slug}/…. Príklady nižšie používajú premenné prostredia:

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ša prvá požiadavka

Vypíšte faktúry účtu:

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

Odpoveďou je stránkovaný zoznam:

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

Stránkovanie, triedenie a vyhľadávanie

Zoznamové endpointy prijímajú tieto parametre dotazu:

Faktúry možno navyše filtrovať podľa status, documentType a subjectId. Neplatný parameter zoznam nikdy nerozbije — namiesto neho sa použije predvolená hodnota (napr. ?page=abc → 1). Každá odpoveď nesie total, page a pageSize, takže počet stránok ľahko odvodíte.

Vytvorenie faktúry

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 zákazníka — získate ho zo zoznamu kontaktov (GET /api/accounts/$SLUG/subjects) alebo ho vytvoríte cez POST …/subjects. Povinné polia sú subjectId a aspoň jedna položka v lines (každá s name a unitPrice). Voliteľne môžete poslať documentType, currency, variableSymbol, due, issuedOn a ďalšie — úplná schéma je v interaktívnej referencii.

Úspech vráti 201 a vytvorenú faktúru:

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

Chyby

Chyby zdieľajú jednotnú obálku — HTTP status plus JSON s statusMessage a poľom data pre strojové spracovanie:

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

Pri doménových chybách je data.code strojovo čitateľný kód (napr. subject_not_found), na ktorý sa môžete spoľahnúť viac než na text správy.

Limity tarifu

Tarif free nerobí žiadne API volania (kvóta 0); byznys má API aj všetky funkcie. Pri prekročení limitu (napr. počtu kontaktov) API vráti 402 s plan_limit_reached; pri funkcii mimo tarifu (webhooky, náklady…) vráti 403 s plan_feature_unavailable. Aktuálne limity a využitie svojho účtu načítate cez:

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

Webhooky

Webhook vás upozorní na udalosti v reálnom čase namiesto opakovaného dopytovania API. Webhooky sú funkciou tarifu byznys a spravuje ich vlastník účtu.

Zaregistrujte ich cez API (alebo v nastaveniach účtu):

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

Do events dajte konkrétne názvy alebo * pre všetky. Dostupné udalosti:

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

Olvano pošle na vašu URL POST s telom:

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

• Ak nastavíte authHeader, odošle sa ako hlavička Authorization — použite ju na overenie, že požiadavka naozaj prišla zo Olvano.
• Každé doručenie nesie hlavičku Idempotency-Key (UUID) — použite ju na deduplikáciu.
• Doručenie sa opakuje až 5× s exponenciálnym odstupom, kým nevrátite status 2xx. Neúspešné doručenia vypíšete cez GET …/webhooks/{id}/failed_deliveries.

Interaktívna referencia

Úplný, vždy aktuálny zoznam endpointov — s parametrami, schémami a možnosťou volať ich priamo z prehliadača:

• Otvoriť API referenciu (/api-docs)
• Strojovo čitateľná OpenAPI schéma: /api/_openapi.json