API

Olvano udostępnia REST API do integracji z Twoimi systemami — twórz i odczytuj faktury, zarządzaj kontaktami oraz nasłuchuj zdarzeń przez webhooki. Ta strona przeprowadzi Cię od tokenu do pierwszego wywołania; pełna, gotowa do uruchomienia lista endpointów znajduje się w interaktywnej dokumentacji.

Zanim zaczniesz

Potrzebujesz dwóch rzeczy:

1. Konta w planie byznys (plan free nie ma API).
2. Tokenu API powiązanego z tym kontem (patrz niżej).

Tokeny tworzy właściciel konta. Jeden token należy do dokładnie jednego konta i ma własne uprawnienia (scopes), więc dla każdej integracji możesz wystawić osobny token.

Tworzenie tokenu API

W aplikacji przejdź do Ustawienia → Tokeny API (/app/{slug}/settings/api-tokens), wybierz Nowy token, nadaj mu nazwę i wybierz uprawnienia. Token w postaci jawnej jest wyświetlany tylko raz — skopiuj go od razu i przechowuj w bezpiecznym miejscu.

Tokeny mają prefiks sg_. Przechowywany jest wyłącznie skrót HMAC, więc tokenu nie da się ponownie wyświetlić — jeśli go zgubisz, utwórz nowy, a stary usuń.

Uprawnienia (scopes)

Odczyt (GET) typowych zasobów nie wymaga żadnego scope; zapis już tak. Operacje zarezerwowane dla właściciela (zarządzanie tokenami, webhookami i rachunkami bankowymi) nigdy nie są dostępne dla tokenu API — nawet token wystawiony przez właściciela zwróci 403.

Uwierzytelnianie i adres bazowy

Uwierzytelniaj każde żądanie tokenem w nagłówku Authorization:

Authorization: Bearer sg_your_token

Adres bazowy to domena Twojej instancji + /api. Endpointy konta mają postać /api/accounts/{slug}/…. Poniższe przykłady korzystają ze zmiennych środowiskowych:

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"

Pierwsze żądanie

Wyświetl listę faktur konta:

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

Odpowiedź to lista stronicowana:

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

Stronicowanie, sortowanie i wyszukiwanie

Endpointy listujące przyjmują następujące parametry zapytania:

Faktury można dodatkowo filtrować według status, documentType i subjectId. Nieprawidłowy parametr nigdy nie psuje listy — zamiast niego użyta zostanie wartość domyślna (np. ?page=abc → 1). Każda odpowiedź zawiera total, page i pageSize, więc liczbę stron łatwo wyliczyć.

Tworzenie faktury

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 to identyfikator klienta — pobierz go z listy kontaktów (GET /api/accounts/$SLUG/subjects) lub utwórz kontakt przez POST …/subjects. Pola wymagane to subjectId oraz co najmniej jedna pozycja w lines (każda z name i unitPrice). Opcjonalnie możesz przesłać documentType, currency, variableSymbol, due, issuedOn i inne — pełny schemat w interaktywnej dokumentacji.

W przypadku powodzenia zwracany jest kod 201 i utworzona faktura:

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

Błędy

Błędy mają spójną strukturę — status HTTP oraz JSON z polem statusMessage i polem data na potrzeby obsługi maszynowej:

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

W przypadku błędów domenowych data.code to kod do odczytu maszynowego (np. subject_not_found), na którym można polegać bardziej niż na treści komunikatu.

Limity planów

Plan free nie wykonuje żadnych wywołań API (limit 0); byznys ma API i wszystkie funkcje. Po przekroczeniu limitu (np. liczby kontaktów) API zwraca 402 z plan_limit_reached; dla funkcji spoza planu (webhooki, wydatki…) zwraca 403 z plan_feature_unavailable. Aktualne limity i zużycie swojego konta odczytasz przez:

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

Webhooki

Webhook powiadamia Cię o zdarzeniach w czasie rzeczywistym, zamiast odpytywać API. Webhooki to funkcja planu byznys, zarządzana przez właściciela konta.

Zarejestruj go przez API (lub w ustawieniach konta):

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

W events podaj konkretne nazwy lub * dla wszystkich. Dostępne zdarzenia:

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

Olvano wysyła POST na Twój adres URL z treścią:

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

• Jeśli ustawisz authHeader, zostanie on wysłany jako nagłówek Authorization — użyj go, aby zweryfikować, że żądanie naprawdę pochodzi ze Olvano.
• Każde doręczenie zawiera nagłówek Idempotency-Key (UUID) — użyj go do deduplikacji.
• Doręczenie jest ponawiane do 5× z wykładniczym odstępem, dopóki nie zwrócisz statusu 2xx. Nieudane doręczenia można wylistować przez GET …/webhooks/{id}/failed_deliveries.

Interaktywna dokumentacja

Kompletna, zawsze aktualna lista endpointów — z parametrami, schematami i możliwością wywołania ich bezpośrednio z przeglądarki:

• Otwórz dokumentację API (/api-docs)
• Schemat OpenAPI do odczytu maszynowego: /api/_openapi.json