API

Olvano għandu REST API biex tqabbad is-sistemi tiegħek stess — oħloq u aqra fatturi, immaniġġja kuntatti u isma' għall-avvenimenti permezz tal-webhooks. Din il-paġna teħodok minn token sal-ewwel sejħa tiegħek; il-lista sħiħa u li tista' tħaddem ta' endpoints tinsab fir-referenza interattiva.

Qabel ma tibda

Teħtieġ żewġ affarijiet:

1. Kont fuq il-pjan byznys (il-pjan free m'għandux API).
2. Token tal-API marbut ma' dak il-kont (ara hawn taħt).

It-tokens jinħolqu mis-sid tal-kont. Token wieħed jappartjeni eżattament lil kont wieħed u jġorr il-permessi tiegħu stess (scopes), għalhekk tista' toħroġ token separat għal kull integrazzjoni.

Kif toħloq token tal-API

Fl-app mur Settings → API tokens (/app/{slug}/settings/api-tokens), agħżel New token, agħtih isem u agħżel il-permessi tiegħu. It-token f'test sempliċi jintwera darba biss — ikkupjah minnufih u aħżnu b'mod sigur.

It-tokens għandhom il-prefiss sg_. Jinħażen biss id-diġest HMAC, għalhekk it-token qatt ma jista' jerġa' jintwera — jekk titilfu, oħloq wieħed ġdid u ħassar il-qadim.

Permessi (scopes)

Il-qari (GET) ta' riżorsi komuni ma jeħtieġ ebda scope; il-kitba iva. Operazzjonijiet għas-sid biss (l-immaniġġjar ta' tokens, webhooks u kontijiet bankarji) qatt ma huma disponibbli permezz ta' token tal-API — anke wieħed maħruġ minn sid jirritorna 403.

Awtentikazzjoni u l-URL bażi

Awtentika kull talba bit-token fil-header Authorization:

Authorization: Bearer sg_your_token

L-URL bażi huwa id-dominju tal-istanza tiegħek + /api. L-endpoints tal-kont għandhom il-forma /api/accounts/{slug}/…. L-eżempji hawn taħt jużaw varjabbli tal-ambjent:

export STARGATE="https://app.stargate.app"   # ibdel bid-dominju tal-istanza tiegħek (lokalment http://localhost:3000)
export SLUG="your-account-slug"
export TOKEN="sg_your_token"

L-ewwel talba tiegħek

Elenka l-fatturi ta' kont:

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

It-tweġiba hija lista paġnata:

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

Paġnar, ordni u tfittxija

L-endpoints tal-listi jaċċettaw dawn il-parametri tal-query:

Il-fatturi jistgħu jiġu ffiltrati wkoll skont status, documentType u subjectId. Parametru invalidu qatt ma jkisser il-lista — minflok jintuża d-default (eż. ?page=abc → 1). Kull tweġiba ġġorr total, page u pageSize, għalhekk l-għadd tal-paġni huwa faċli biex tikkalkulah.

Kif toħloq fattura

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 huwa l-ID tal-klijent — iksbu mil-lista tal-kuntatti (GET /api/accounts/$SLUG/subjects) jew oħloq wieħed permezz ta' POST …/subjects. Il-kampijiet obbligatorji huma subjectId u mill-inqas partita waħda f'lines (kull waħda b'name u unitPrice). B'mod fakultattiv tista' tibgħat documentType, currency, variableSymbol, due, issuedOn u aktar — l-iskema sħiħa fir-referenza interattiva.

Is-suċċess jirritorna 201 u l-fattura maħluqa:

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

Żbalji

L-iżbalji jaqsmu envelop konsistenti — status HTTP flimkien ma' JSON b'statusMessage u kamp data għall-immaniġġjar mill-magni:

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

Għall-iżbalji tad-dominju, data.code huwa kodiċi li jinqara mill-magni (eż. subject_not_found) li tista' toqgħod fuqu aktar mit-test tal-messaġġ.

Limiti tal-pjan

Il-pjan free ma jagħmel ebda sejħa lill-API (kwota 0); byznys għandu l-API u l-karatteristiċi kollha. Meta jinqabeż limitu (eż. l-għadd tal-kuntatti) l-API jirritorna 402 b'plan_limit_reached; għal karatteristika barra mill-pjan (webhooks, spejjeż…) jirritorna 403 b'plan_feature_unavailable. Aqra l-limiti u l-użu attwali tal-kont tiegħek permezz ta':

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

Webhooks

Webhook jinnotifikak dwar avvenimenti f'ħin reali, minflok ma tistaqsi l-API kontinwament. Il-webhooks huma karatteristika tal-pjan byznys u jiġu mmaniġġjati mis-sid tal-kont.

Irreġistra permezz tal-API (jew fis-settings tal-kont):

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

Poġġi ismijiet speċifiċi f'events, jew * għal kollha. Avvenimenti disponibbli:

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

Olvano jibgħat POST lill-URL tiegħek bil-korp:

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

• Jekk tissettja authHeader, jintbagħat bħala l-header Authorization — użah biex tivverifika li t-talba verament ġiet minn Olvano.
• Kull konsenja ġġorr header Idempotency-Key (UUID) — użah biex telimina d-duplikati.
• Il-konsenja terġa' tiġi pruvata sa 5× b'backoff esponenzjali sakemm tirritorna status 2xx. Il-konsenji li jfallew huma elenkati permezz ta' GET …/webhooks/{id}/failed_deliveries.

Referenza interattiva

Il-lista kompluta u dejjem aġġornata ta' endpoints — bil-parametri, l-iskemi u l-kapaċità li ssejħilhom direttament mill-browser:

• Iftaħ ir-referenza API (/api-docs)
• Skema OpenAPI li tinqara mill-magni: /api/_openapi.json