API

A Olvano REST API-val rendelkezik a saját rendszerei összekapcsolásához — számlákat hozhat létre és olvashat, partnereket kezelhet, és webhookokon keresztül figyelheti az eseményeket. Ez az oldal a tokentől az első hívásig vezeti végig; a végpontok teljes, futtatható listája az interaktív referenciában található.

Mielőtt elkezdi

Két dologra van szüksége:

1. Egy fiók a byznys csomagon (a free csomagban nincs API).
2. Egy adott fiókhoz kötött API-token (lásd alább).

A tokeneket a fiók tulajdonosa hozza létre. Egy token pontosan egy fiókhoz tartozik, és saját jogosultságokat (scope-okat) hordoz, így integrációnként külön tokent állíthat ki.

API-token létrehozása

Az alkalmazásban lépjen a Beállítások → API-tokenek menüpontba (/app/{slug}/settings/api-tokens), válassza az Új token lehetőséget, adjon neki nevet, és válassza ki a jogosultságait. A token nyílt szövegét csak egyszer mutatjuk meg — másolja ki azonnal, és tárolja biztonságosan.

A tokenek sg_ előtaggal kezdődnek. Csak egy HMAC-lenyomatot tárolunk, így a token soha nem jeleníthető meg újra — ha elveszíti, hozzon létre egy újat, és törölje a régit.

Jogosultságok (scope-ok)

A gyakori erőforrások olvasásához (GET) nincs szükség scope-ra; az íráshoz igen. A csak tulajdonosi műveletek (tokenek, webhookok és bankszámlák kezelése) API-token számára soha nem érhetők el — még a tulajdonos által kiállított token is 403 választ kap.

Hitelesítés és alap-URL

Minden kérést a tokennel hitelesítsen az Authorization fejlécben:

Authorization: Bearer sg_your_token

Az alap-URL a példánya domainje + /api. A fiókvégpontok formája /api/accounts/{slug}/…. Az alábbi példák környezeti változókat használnak:

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"

Az első kérése

Listázza egy fiók számláit:

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

A válasz egy lapozott lista:

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

Lapozás, rendezés és keresés

A listavégpontok az alábbi lekérdezési paramétereket fogadják el:

A számlák ezenfelül szűrhetők status, documentType és subjectId szerint. Az érvénytelen paraméter soha nem töri el a listát — helyette az alapértelmezett érték érvényesül (pl. ?page=abc → 1). Minden válasz tartalmazza a total, page és pageSize mezőket, így az oldalak száma könnyen kiszámítható.

Számla létrehozása

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

A subjectId az ügyfél azonosítója — szerezze be a partnerlistából (GET /api/accounts/$SLUG/subjects), vagy hozzon létre egyet a POST …/subjects hívással. A kötelező mezők a subjectId és legalább egy tétel a lines tömbben (mindegyikhez name és unitPrice). Opcionálisan elküldheti a documentType, currency, variableSymbol, due, issuedOn és további mezőket — a teljes séma az interaktív referenciában.

Sikeres esetben 201 választ ad a létrehozott számlával:

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

Hibák

A hibák egységes burokban érkeznek — egy HTTP-státusz, valamint JSON statusMessage mezővel és egy géppel feldolgozható data mezővel:

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

Domainhibák esetén a data.code egy géppel olvasható kód (pl. subject_not_found), amelyre jobban támaszkodhat, mint az üzenet szövegére.

Csomagkorlátok

A free csomag nem végez API-hívásokat (kvóta 0); a byznys rendelkezik az API-val és minden funkcióval. Ha egy korlát túllépésre kerül (pl. a partnerek száma), az API 402 választ ad plan_limit_reached kóddal; a csomagon kívüli funkció (webhookok, kiadások…) esetén 403 választ ad plan_feature_unavailable kóddal. A fiókja aktuális korlátait és felhasználását így kérheti le:

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

Webhookok

A webhook valós időben értesíti az eseményekről, az API lekérdezgetése helyett. A webhookok a byznys csomag funkciói, és a fiók tulajdonosa kezeli őket.

Regisztrálja az API-n keresztül (vagy a fiókbeállításokban):

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

Adjon meg konkrét neveket az events mezőben, vagy * az összeshez. Elérhető események:

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

A Olvano POST kérést küld az Ön URL-jére az alábbi törzzsel:

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

• Ha beállítja az authHeader mezőt, az Authorization fejlécként kerül elküldésre — ezzel ellenőrizheti, hogy a kérés valóban a Olvano-től érkezett.
• Minden kézbesítés tartalmaz egy Idempotency-Key fejlécet (UUID) — ezzel szűrheti ki a duplikátumokat.
• A kézbesítést legfeljebb 5× próbáljuk újra, exponenciálisan növekvő várakozással, amíg 2xx státuszt nem ad vissza. A sikertelen kézbesítések a GET …/webhooks/{id}/failed_deliveries hívással listázhatók.

Interaktív referencia

A végpontok teljes, mindig naprakész listája — paraméterekkel, sémákkal és azzal a lehetőséggel, hogy közvetlenül a böngészőből hívja meg őket:

• Nyissa meg az API-referenciát (/api-docs)
• Géppel olvasható OpenAPI-séma: /api/_openapi.json