API

Olvano má REST API, přes které napojíte vlastní systémy — vytváříte a čtete faktury, spravujete kontakty a nasloucháte událostem přes webhooky. Tahle stránka vás provede od tokenu k prvnímu volání; úplný seznam endpointů s možností je rovnou vyzkoušet najdete v interaktivní referenci.

Než začnete

Potřebujete dvě věci:

1. Účet na tarifu byznys (na free API nefunguje).
2. API token svázaný s tímto účtem (návod níže).

Token vytváří vlastník účtu. Jeden token patří právě jednomu účtu a nese vlastní oprávnění (scopes), takže můžete vydat samostatný token pro každou integraci.

Vytvoření API tokenu

V aplikaci jděte do Nastavení → API tokeny (/app/{slug}/settings/api-tokens), zvolte Nový token, pojmenujte ho a vyberte oprávnění. Plaintextový token se zobrazí jen jednou — hned ho zkopírujte a uložte bezpečně.

Token poznáte podle prefixu sg_. V databázi se ukládá jen jeho HMAC otisk, takže ho z aplikace nelze znovu zobrazit — když ho ztratíte, vytvořte nový a starý smažte.

Oprávnění (scopes)

Čtení (GET) běžných zdrojů scope nevyžaduje; zápis ano. Operace pro vlastníka (správa tokenů, webhooků a bankovních účtů) přes API token nikdy nejsou dostupné — i token vydaný vlastníkem vrátí 403.

Autentizace a základní URL

Každý požadavek autentizujte tokenem v hlavičce Authorization:

Authorization: Bearer sg_vas_token

Základní URL je doména vaší instance + /api. Účtové endpointy mají tvar /api/accounts/{slug}/…. V příkladech níže používáme proměnné prostředí:

export STARGATE="https://app.stargate.app"   # nahraďte doménou své instance (lokálně http://localhost:3000)
export SLUG="vas-ucet-slug"
export TOKEN="sg_vas_token"

První požadavek

Načtěte faktury účtu:

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

Odpověď je stránkovaný seznam:

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

Stránkování, řazení a hledání

Seznamové endpointy přijímají tyto query parametry:

Faktury jdou navíc filtrovat přes status, documentType a subjectId. Neplatná hodnota parametru seznam neshodí — použije se výchozí (např. ?page=abc → 1). Odpověď vždy obsahuje total, page a pageSize, takže snadno spočítáte počet stránek.

Vytvoření faktury

curl -X POST "$STARGATE/api/accounts/$SLUG/invoices" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "subjectId": "ID_ODBERATELE",
    "lines": [
      { "name": "Konzultace", "quantity": 2, "unitPrice": "1500", "vatRate": 21 }
    ]
  }'

subjectId je ID odběratele — získáte ho ze seznamu kontaktů (GET /api/accounts/$SLUG/subjects) nebo ho založíte přes POST …/subjects. Povinné je subjectId a alespoň jedna položka v lines (každá s name a unitPrice). Volitelně lze poslat documentType, currency, variableSymbol, due, issuedOn a další — kompletní schéma viz interaktivní reference.

Úspěch vrátí 201 a vytvořenou fakturu:

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

Chyby

Chyby mají konzistentní obálku — HTTP status + JSON s statusMessage a polem data pro strojové zpracování:

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

U doménových chyb je v data.code strojově čitelný kód (např. subject_not_found), na který se dá spolehnout víc než na text zprávy.

Limity plánu

Tarif free API nevolá (kvóta 0), byznys má API i všechny funkce. Při překročení limitu (např. počet kontaktů) vrací API 402 s plan_limit_reached, u funkce mimo plán (webhooky, výdaje…) 403 s plan_feature_unavailable. Aktuální limity a využití svého účtu si přečtete přes:

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

Webhooky

Webhook vás upozorní na události v reálném čase, místo abyste se API dokola ptali. Webhooky jsou funkce tarifu byznys a spravuje je vlastník účtu.

Registrace přes API (nebo v nastavení účtu):

curl -X POST "$STARGATE/api/accounts/$SLUG/webhooks" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "webhookUrl": "https://vas-server.cz/hooks/stargate",
    "events": ["invoice_paid", "invoice_sent"],
    "authHeader": "Bearer vas-sdileny-tajny-klic"
  }'

Do events dejte konkrétní názvy nebo * pro všechny. Dostupné události:

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

Na vaši URL pošle Olvano POST s tělem:

{ "event_name": "invoice_paid", "body": { "…": "data události" } }

• Pokud nastavíte authHeader, pošle se jako hlavička Authorization — tím si ověříte, že request je opravdu od Olvano.
• Každé doručení nese hlavičku Idempotency-Key (UUID) — použijte ji k deduplikaci.
• Doručení se opakuje až 5× s exponenciálním odstupem, dokud nevrátíte stav 2xx. Neúspěšná doručení najdete přes GET …/webhooks/{id}/failed_deliveries.

Interaktivní reference

Kompletní a vždy aktuální seznam endpointů — s parametry, schématy a možností volání rovnou z prohlížeče:

• Otevřít API referenci (/api-docs)
• Strojové OpenAPI schéma: /api/_openapi.json