API

Olvano разполага с REST API за свързване със собствените ви системи — създавайте и четете фактури, управлявайте контакти и слушайте за събития чрез webhooks. Тази страница ще ви преведе от токен до първата заявка; пълният, изпълним списък с endpoints се намира в интерактивната справка.

Преди да започнете

Нуждаете се от две неща:

1. Акаунт в плана byznys (планът free няма API).
2. API токен, свързан с този акаунт (вижте по-долу).

Токените се създават от собственика на акаунта. Един токен принадлежи точно на един акаунт и носи собствени права (scopes), така че можете да издадете отделен токен за всяка интеграция.

Създаване на API токен

В приложението отидете на Настройки → API токени (/app/{slug}/settings/api-tokens), изберете Нов токен, дайте му име и изберете правата му. Токенът в явен вид се показва само веднъж — копирайте го веднага и го съхранете на сигурно място.

Токените започват с префикс sg_. Съхранява се само HMAC отпечатък, така че токенът никога не може да бъде показан отново — ако го изгубите, създайте нов и изтрийте стария.

Права (scopes)

Четенето (GET) на обичайните ресурси не изисква scope; записването — да. Операциите само за собственик (управление на токени, webhooks и банкови сметки) никога не са достъпни за API токен — дори издаден от собственик, той връща 403.

Удостоверяване и базов URL

Удостоверявайте всяка заявка с токена в хедъра Authorization:

Authorization: Bearer sg_your_token

Базовият URL е домейнът на вашата инстанция + /api. Endpoints за акаунт имат формата /api/accounts/{slug}/…. Примерите по-долу използват променливи на средата:

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"

Вашата първа заявка

Извеждане на фактурите на акаунт:

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

Отговорът е списък със странициране:

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

Странициране, сортиране и търсене

Endpoints за списъци приемат следните query параметри:

Фактурите могат допълнително да се филтрират по status, documentType и subjectId. Невалиден параметър никога не разваля списъка — вместо това се използва стойността по подразбиране (напр. ?page=abc → 1). Всеки отговор съдържа total, page и pageSize, така че броят на страниците лесно се изчислява.

Създаване на фактура

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 е идентификаторът на клиента — вземете го от списъка с контакти (GET /api/accounts/$SLUG/subjects) или създайте такъв чрез POST …/subjects. Задължителните полета са subjectId и поне един ред в lines (всеки с name и unitPrice). По избор можете да изпратите documentType, currency, variableSymbol, due, issuedOn и други — пълната схема е в интерактивната справка.

При успех се връща 201 и създадената фактура:

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

Грешки

Грешките използват единен формат — HTTP статус плюс JSON със statusMessage и поле data за машинна обработка:

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

При бизнес грешки data.code е машинночетим код (напр. subject_not_found), на който можете да разчитате повече, отколкото на текста на съобщението.

Лимити на плана

Планът free не прави API заявки (квота 0); byznys разполага с API и всички функции. Когато бъде надхвърлен лимит (напр. броят контакти), API връща 402 с plan_limit_reached; за функция извън плана (webhooks, разходи…) връща 403 с plan_feature_unavailable. Прочетете текущите лимити и потребление на вашия акаунт чрез:

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

Webhooks

Webhook ви уведомява за събития в реално време, вместо да заявявате API на интервали. Webhooks са функция на плана byznys и се управляват от собственика на акаунта.

Регистрирайте го чрез API (или в настройките на акаунта):

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

Поставете конкретни имена в events или * за всички. Налични събития:

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

Olvano изпраща POST към вашия URL с тялото:

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

• Ако зададете authHeader, той се изпраща като хедъра Authorization — използвайте го, за да проверите, че заявката наистина идва от Olvano.
• Всяка доставка носи хедъра Idempotency-Key (UUID) — използвайте го за дедупликация.
• Доставката се опитва повторно до 5 пъти с експоненциално нарастващо изчакване, докато върнете статус 2xx. Неуспешните доставки се извеждат чрез GET …/webhooks/{id}/failed_deliveries.

Интерактивна справка

Пълният, винаги актуален списък с endpoints — с параметри, схеми и възможност да ги извиквате директно от браузъра:

• Отворете API справката (/api-docs)
• Машинночетима OpenAPI схема: /api/_openapi.json