API

Olvano piedāvā REST API tavu sistēmu pieslēgšanai — izveido un lasi rēķinus, pārvaldi kontaktus un klausies notikumus, izmantojot webhooks. Šī lapa tevi izvedīs no marķiera līdz pirmajam izsaukumam; pilns, izpildāms galapunktu saraksts atrodas interaktīvajā atsaucē.

Pirms sākt

Tev vajadzīgas divas lietas:

1. Konts ar byznys plānu (free plānā nav API).
2. API marķieris, kas piesaistīts šim kontam (skat. zemāk).

Marķierus izveido konta īpašnieks. Viens marķieris pieder tieši vienam kontam un nes savas atļaujas (scopes), tāpēc katrai integrācijai vari izsniegt atsevišķu marķieri.

API marķiera izveide

Lietotnē dodies uz Iestatījumi → API marķieri (/app/{slug}/settings/api-tokens), izvēlies Jauns marķieris, nosauc to un atlasi tā atļaujas. Marķiera atklātais teksts tiek parādīts tikai vienu reizi — nokopē to nekavējoties un glabā drošā vietā.

Marķieriem ir prefikss sg_. Tiek glabāts tikai HMAC jaucējkods, tāpēc marķieri vairs nekad nevar parādīt — ja to pazaudē, izveido jaunu un izdzēs veco.

Atļaujas (scopes)

Izplatīto resursu lasīšanai (GET) atļauja nav vajadzīga; rakstīšanai — ir. Tikai īpašniekam pieejamās darbības (marķieru, webhooks un bankas kontu pārvaldība) API marķierim nekad nav pieejamas — pat īpašnieka izsniegts marķieris atgriež 403.

Autentifikācija un bāzes URL

Autentificē katru pieprasījumu ar marķieri Authorization galvenē:

Authorization: Bearer sg_your_token

Bāzes URL ir tava instances domēns + /api. Konta galapunktiem ir forma /api/accounts/{slug}/…. Tālāk redzamie piemēri izmanto vides mainīgos:

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"

Tavs pirmais pieprasījums

Uzskaiti konta rēķinus:

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

Atbilde ir lapots saraksts:

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

Lapošana, kārtošana un meklēšana

Saraksta galapunkti pieņem šādus vaicājuma parametrus:

Rēķinus papildus var filtrēt pēc status, documentType un subjectId. Nederīgs parametrs nekad nesabojā sarakstu — tā vietā tiek izmantots noklusējums (piemēram, ?page=abc → 1). Katra atbilde satur total, page un pageSize, tāpēc lapu skaitu ir viegli aprēķināt.

Rēķina izveide

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 ir klienta identifikators — iegūsti to no kontaktu saraksta (GET /api/accounts/$SLUG/subjects) vai izveido jaunu ar POST …/subjects. Obligātie lauki ir subjectId un vismaz viena rinda sarakstā lines (katra ar name un unitPrice). Pēc izvēles vari nosūtīt documentType, currency, variableSymbol, due, issuedOn un citus — pilna shēma interaktīvajā atsaucē.

Veiksmes gadījumā atgriež 201 un izveidoto rēķinu:

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

Kļūdas

Kļūdām ir vienots ietvars — HTTP statuss plus JSON ar statusMessage un lauku data mašīnapstrādei:

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

Domēna kļūdām data.code ir mašīnlasāms kods (piemēram, subject_not_found), uz kuru vari paļauties vairāk nekā uz ziņojuma tekstu.

Plānu limiti

Free plāns neveic nevienu API izsaukumu (kvota 0); byznys plānam ir API un visas funkcijas. Kad limits ir pārsniegts (piemēram, kontaktu skaits), API atgriež 402 ar plan_limit_reached; funkcijai ārpus plāna (webhooks, izdevumi…) tā atgriež 403 ar plan_feature_unavailable. Sava konta aktuālos limitus un izmantojumu vari nolasīt ar:

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

Webhooks

Webhook tev paziņo par notikumiem reāllaikā, nevis tev nepārtraukti jāaptaujā API. Webhooks ir byznys plāna funkcija, un tos pārvalda konta īpašnieks.

Reģistrē to caur API (vai konta iestatījumos):

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

Norādi laukā events konkrētus nosaukumus vai * visiem. Pieejamie notikumi:

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

Olvano nosūta POST uz tavu URL ar saturu:

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

• Ja iestati authHeader, tas tiek nosūtīts kā Authorization galvene — izmanto to, lai pārbaudītu, ka pieprasījums tiešām nāca no Olvano.
• Katra piegāde satur Idempotency-Key galveni (UUID) — izmanto to dublikātu novēršanai.
• Piegāde tiek atkārtota līdz 5× ar eksponenciāli pieaugošu aizturi, līdz atgriez 2xx statusu. Neizdevušās piegādes ir uzskaitītas ar GET …/webhooks/{id}/failed_deliveries.

Interaktīvā atsauce

Pilns un vienmēr aktuāls galapunktu saraksts — ar parametriem, shēmām un iespēju izsaukt tos tieši no pārlūka:

• Atver API atsauci (/api-docs)
• Mašīnlasāma OpenAPI shēma: /api/_openapi.json