API

Tá REST API ag Olvano chun do chórais féin a nascadh — cruthaigh agus léigh sonraisc, bainistigh teagmhálaithe agus éist le himeachtaí trí webhooks. Tugann an leathanach seo ó chomhartha go dtí do chéad ghlao thú; tá an liosta iomlán inrite de chríochphointí sa tagairt idirghníomhach.

Sula dtosaíonn tú

Teastaíonn dhá rud uait:

1. Cuntas ar an bplean byznys (níl aon API ag an bplean free).
2. Comhartha API atá ceangailte leis an gcuntas sin (féach thíos).

Cruthaíonn úinéir an chuntais comharthaí. Baineann comhartha amháin le cuntas amháin go díreach agus iompraíonn sé a chuid ceadanna féin (scopes), mar sin is féidir leat comhartha ar leith a eisiúint do gach comhtháthú.

Comhartha API a chruthú

San aip téigh go Settings → API tokens (/app/{slug}/settings/api-tokens), roghnaigh New token, tabhair ainm air agus roghnaigh a chuid ceadanna. Taispeántar an comhartha gnáth-théacs uair amháin — cóipeáil láithreach é agus stóráil go sábháilte é.

Aithnítear comharthaí ar an réimír sg_. Ní stóráiltear ach a mhionsamhail HMAC, mar sin ní féidir an comhartha a thaispeáint arís — má chailleann tú é, cruthaigh ceann nua agus scrios an seancheann.

Ceadanna (scopes)

Ní theastaíonn scope chun gnáthacmhainní a léamh (GET); teastaíonn sé chun scríobh. Oibríochtaí don úinéir amháin (comharthaí, webhooks agus cuntais bhainc a bhainistiú) níl siad ar fáil trí chomhartha API riamh — fillfidh comhartha a d'eisigh úinéir féin 403.

Fíordheimhniú agus an URL bonn

Fíordheimhnigh gach iarratas leis an gcomhartha sa cheanntásc Authorization:

Authorization: Bearer sg_your_token

Is é an URL bonn fearann d'ásc féin + /api. Bíonn an fhoirm /api/accounts/{slug}/… ar chríochphointí cuntais. Úsáideann na samplaí thíos athróga timpeallachta:

export STARGATE="https://app.stargate.app"   # cuir fearann d'ásca féin ina ionad (go háitiúil http://localhost:3000)
export SLUG="your-account-slug"
export TOKEN="sg_your_token"

An chéad iarratas

Liostaigh sonraisc cuntais:

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

Is liosta leathanaithe an freagra:

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

Leathanú, sórtáil agus cuardach

Glacann críochphointí liostaithe leis na paraiméadair cheiste seo:

Is féidir sonraisc a scagadh freisin de réir status, documentType agus subjectId. Ní bhriseann luach paraiméadair neamhbhailí an liosta riamh — úsáidtear an réamhshocrú ina áit (m.sh. ?page=abc → 1). Iompraíonn gach freagra total, page agus pageSize, mar sin is furasta líon na leathanach a oibriú amach.

Sonrasc a chruthú

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

Is é subjectId aitheantas an chustaiméara — faigh ón liosta teagmhálaithe é (GET /api/accounts/$SLUG/subjects) nó cruthaigh ceann trí POST …/subjects. Is iad na réimsí éigeantacha ná subjectId agus líne amháin ar a laghad i lines (gach ceann le name agus unitPrice). Go roghnach is féidir leat documentType, currency, variableSymbol, due, issuedOn agus tuilleadh a sheoladh — an scéimre iomlán sa tagairt idirghníomhach.

Fillfidh rath 201 agus an sonrasc a cruthaíodh:

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

Earráidí

Roinneann earráidí clúdach comhsheasmhach — stádas HTTP móide JSON le statusMessage agus réimse data le haghaidh láimhseáil ag meaisín:

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

I gcás earráidí fearainn, is cód inléite ag meaisín é data.code (m.sh. subject_not_found) ar féidir brath air níos mó ná téacs na teachtaireachta.

Teorainneacha an phlean

Ní ghlaonn an plean free ar an API (cuóta 0); tá an API agus na gnéithe go léir ag byznys. Nuair a sháraítear teorainn (m.sh. líon na dteagmhálaithe) fillfidh an API 402 le plan_limit_reached; i gcás gné nach bhfuil sa phlean (webhooks, costais…) fillfidh sé 403 le plan_feature_unavailable. Léigh teorainneacha agus úsáid reatha do chuntais trí:

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

Webhooks

Cuireann webhook in iúl duit faoi imeachtaí i bhfíor-am, in ionad a bheith ag ceistiú an API arís agus arís eile. Is gné den phlean byznys iad webhooks agus is é úinéir an chuntais a bhainistíonn iad.

Cláraigh tríd an API (nó i socruithe an chuntais):

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

Cuir ainmneacha ar leith i events, nó * do gach ceann. Imeachtaí atá ar fáil:

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

Seolann Olvano POST chuig do URL leis an gcorp:

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

• Má shocraíonn tú authHeader, seoltar é mar an gceanntásc Authorization — úsáid é chun a dheimhniú gur ó Olvano a tháinig an t-iarratas i ndáiríre.
• Iompraíonn gach seachadadh ceanntásc Idempotency-Key (UUID) — úsáid é chun dúblachtaí a bhaint.
• Déantar an seachadadh a atriail suas le 5× le cúlú easpónantúil go dtí go bhfillfidh tú stádas 2xx. Tá seachadtaí teipthe le feiceáil trí GET …/webhooks/{id}/failed_deliveries.

Tagairt idirghníomhach

An liosta iomlán, atá cothrom le dáta i gcónaí, de chríochphointí — le paraiméadair, scéimrí agus an cumas iad a ghlaoch díreach ón mbrabhsálaí:

• Oscail an tagairt API (/api-docs)
• Scéimre OpenAPI inléite ag meaisín: /api/_openapi.json