API

Olvano are un API REST pentru conectarea propriilor sisteme — creați și citiți facturi, gestionați contacte și ascultați evenimente prin webhook-uri. Această pagină vă duce de la un token până la primul apel; lista completă, executabilă a endpoint-urilor se află în referința interactivă.

Înainte de a începe

Aveți nevoie de două lucruri:

1. Un cont în planul byznys (planul free nu are API).
2. Un token API asociat acelui cont (vedeți mai jos).

Token-urile sunt create de proprietarul contului. Un token aparține exact unui singur cont și poartă propriile permisiuni (scopes), așa că puteți emite un token separat pentru fiecare integrare.

Crearea unui token API

În aplicație mergeți la Setări → Token-uri API (/app/{slug}/settings/api-tokens), alegeți Token nou, denumiți-l și selectați-i permisiunile. Token-ul în text clar este afișat o singură dată — copiați-l imediat și păstrați-l în siguranță.

Token-urile au prefixul sg_. Se stochează doar un digest HMAC, deci token-ul nu mai poate fi afișat niciodată — dacă îl pierdeți, creați unul nou și ștergeți-l pe cel vechi.

Permisiuni (scopes)

Citirea (GET) resurselor obișnuite nu necesită niciun scope; scrierea da. Operațiunile rezervate proprietarului (gestionarea token-urilor, a webhook-urilor și a conturilor bancare) nu sunt niciodată disponibile pentru un token API — chiar și unul emis de un proprietar returnează 403.

Autentificare și URL de bază

Autentificați fiecare cerere cu token-ul în antetul Authorization:

Authorization: Bearer sg_your_token

URL-ul de bază este domeniul instanței dumneavoastră + /api. Endpoint-urile de cont au forma /api/accounts/{slug}/…. Exemplele de mai jos folosesc variabile de mediu:

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"

Prima cerere

Listați facturile unui cont:

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

Răspunsul este o listă paginată:

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

Paginare, sortare și căutare

Endpoint-urile de listare acceptă acești parametri de interogare:

Facturile pot fi filtrate suplimentar după status, documentType și subjectId. Un parametru invalid nu strică niciodată lista — se folosește valoarea implicită în loc (de ex. ?page=abc → 1). Fiecare răspuns conține total, page și pageSize, așa că numărul de pagini se deduce ușor.

Crearea unei facturi

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 este ID-ul clientului — obțineți-l din lista de contacte (GET /api/accounts/$SLUG/subjects) sau creați unul prin POST …/subjects. Câmpurile obligatorii sunt subjectId și cel puțin o linie în lines (fiecare cu name și unitPrice). Opțional puteți trimite documentType, currency, variableSymbol, due, issuedOn și altele — schema completă în referința interactivă.

Succesul returnează 201 și factura creată:

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

Erori

Erorile au un format consecvent — un status HTTP plus JSON cu statusMessage și un câmp data pentru procesare automată:

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

Pentru erorile de domeniu, data.code este un cod citibil automat (de ex. subject_not_found) pe care vă puteți baza mai mult decât pe textul mesajului.

Limitele planurilor

Planul free nu face niciun apel API (cotă 0); byznys are API-ul și toate funcțiile. Când o limită este depășită (de ex. numărul de contacte), API-ul returnează 402 cu plan_limit_reached; pentru o funcție din afara planului (webhook-uri, cheltuieli…) returnează 403 cu plan_feature_unavailable. Citiți limitele și utilizarea curentă ale contului prin:

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

Webhook-uri

Un webhook vă notifică despre evenimente în timp real, în loc să interogați API-ul. Webhook-urile sunt o funcție a planului byznys și sunt gestionate de proprietarul contului.

Înregistrați prin API (sau în setările contului):

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

Puneți nume specifice în events, sau * pentru toate. Evenimente disponibile:

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

Olvano trimite un POST către URL-ul dumneavoastră cu corpul:

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

• Dacă setați authHeader, acesta este trimis ca antet Authorization — folosiți-l pentru a verifica faptul că cererea a venit într-adevăr de la Olvano.
• Fiecare livrare poartă un antet Idempotency-Key (UUID) — folosiți-l pentru deduplicare.
• Livrarea este reîncercată de până la 5× cu backoff exponențial până când returnați un status 2xx. Livrările eșuate sunt listate prin GET …/webhooks/{id}/failed_deliveries.

Referință interactivă

Lista completă, mereu actualizată, a endpoint-urilor — cu parametri, scheme și posibilitatea de a le apela direct din browser:

• Deschideți referința API (/api-docs)
• Schemă OpenAPI citibilă automat: /api/_openapi.json