---
title: "Treoir an fhorbróra"
description: "REST API Quire, OAuth, webhooks, an freastalaí MCP agus eisínteachtaí."
image: "https://docs.quirelms.com/og.png"
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.quirelms.com/ga/llms.txt
> Use this file to discover all available pages before exploring further.

# Treoir an fhorbróra

<span id="developer-guide"></span>

Úsáid seoladh API d’eagraíochta agus dintiúr a bhfuil scóip theoranta aige. Tosaigh le hiarratas léite, seiceáil an freagra, agus coinnigh rúin amach ón gcód foinseach agus ó shamplaí doiciméadachta.

Tá API poiblí amháin ag Quire: REST thar HTTPS, curtha síos i ndoiciméad OpenAPI 3.1, webhooks sínithe d’imeachtaí agus freastalaí MCP do chúntóirí AI. Liostaíonn an [tagairt API](https://docs.quirelms.com/api/) gach críochphointe agus imeacht.

## Seoltaí <!--quire:addresses-->

Tá a sheoladh féin ag gach eagraíocht, agus tá an API faoi:

```
https://acme.quirelms.com/api/v1/courses
```

Is é an dintiúr a shocraíonn an eagraíocht. Diúltaítear d’eochair eagraíochta amháin má úsáidtear í ag seoladh eagraíochta eile.

Déantar an doiciméad OpenAPI a sheirbheáil ag `/api/v1/openapi.json` ag seoladh aon eagraíochta, ionas go bhfeiceann gineadóirí cliaint an leagan a bhfuil tú ag glaoch air i gcónaí.

## Fíordheimhniú <!--quire:authentication-->

Is do scripteanna agus comhtháthuithe freastalaí le freastalaí iad **eochracha API**. Cruthaíonn riarthóir ceann ag `/admin/integrations/api-keys`, roghnaíonn sé a scóipeanna agus ní fheiceann sé ach uair amháin é. Seol é mar chomhartha iompróra:

```
curl -H "Authorization: Bearer qk_live_..." https://acme.quirelms.com/api/v1/users?limit=50
```

Tosaíonn eochracha le `qk_live_` nó `qk_test_`. Tabhair eochair ar leith do gach comhtháthú.

Is d’fheidhmchláir a ghníomhaíonn thar ceann duine sínithe isteach é **OAuth 2.1**. Cláraigh cliant ag `/admin/integrations/oauth-clients`, agus bain úsáid as sreabhadh cód údaraithe le PKCE (`/oauth/authorize`, `/oauth/token`), nó dintiúir chliaint do chliant meaisín. Tá an fionnachtain ag `/.well-known/oauth-authorization-server`. Cuireann scóip teorainn leis an méid is féidir le comhartha a dhéanamh; ní thugann sé cead dó riamh níos mó a dhéanamh ná mar a d’fhéadfadh an duine féin.

Is iad na scóipeanna `resource:read`, `resource:write` agus `resource:delete`, mar shampla `courses:read` nó `enrolments:write`. Tá ceithre scóip phribhléideacha a léirítear le rabhadh ar an scáileán toilithe: `audit:read`, `roles:write`, `tenants:write` agus `users:delete`.

<figure class="quire-shot" lang="en" dir="ltr"><img src="/screenshots/admin-api-keys.webp" alt="The API keys page with one key, the person it acts as, its scopes and its status, and a form to create another." width="944" height="700" loading="lazy" decoding="async"><figcaption>API keys list who each key acts as and what it may reach.</figcaption></figure>

## Iarratais <!--quire:requests-->

- **Uimhriú leathanaigh**: déantar uimhriú le cúrsóir ar gach liosta. Cuir `limit` ar aghaidh, agus ansin cuir `next_cursor` ó `page` ar aghaidh mar `cursor` fad is atá `has_more` fíor (féach an sampla thíos). Níl aon fhritháireamh ann.
- **Athruithe ó am áirithe**: tugann `updated_since` na hathruithe tar éis ama ar leith ar ais. Úsáid in éineacht le `include_deleted=true`, nó léigh `/<resource>/deletions`, chun a fháil amach cad a baineadh.
- **Aitheantóirí seachtracha**: glacann formhór na n-acmhainní le do `external_id` féin, agus léann nó nuashonraíonn `/<resource>/ext:{external_id}` de réir an aitheantóra sin. Ní gá, dá bhrí sin, d’aitheantóirí Quire a stóráil le haghaidh sioncronaithe.
- **Idéimpotaíocht**: seol ceanntásc `Idempotency-Key` le `POST`, `PATCH` agus `DELETE`. Tugann iarracht eile leis an eochair chéanna an chéad fhreagra ar ais seachas an obair a dhéanamh faoi dhó. Éilítear é ar chríochphointí ollmhóra.
- **Leaganacha**: tá an leagan mór sa chonair (`/v1`). Laistigh de, is athbhreithniú dátaithe é gach athrú briste, roghnaithe leis an gceanntásc `Quire-Version`, mar `Quire-Version: 2026-09-20`. Gan an ceanntásc faigheann tú an t-athbhreithniú a bhí i bhfeidhm nuair a eisíodh do dhintiúr.

Sampla de leathanach liosta:

```
{"data": [...], "page": {"next_cursor": "eyJ2Ijox...", "has_more": true, "limit": 100}}
```

## Earráidí <!--quire:errors-->

Is doiciméad faidhbe RFC 9457 é gach earráid:

```
{"type": "https://quire.com/errors/enrolment.seat_limit_reached",
 "title": "Seat limit reached", "status": 409,
 "code": "enrolment.seat_limit_reached", "category": "conflict",
 "detail": "The course has no seats left, so this enrolment was not created. ...",
 "request_id": "01JB7XQK4Z..."}
```

Bunaigh do láimhseáil ar `code`, atá seasmhach; scríobhtar `detail` do dhaoine, tá sé sábháilte a thaispeáint dóibh agus d’fhéadfadh sé athrú. Mura n-aithníonn tú cód, bain úsáid as a `category`:

| Catagóir | Stádas | Bain triail eile as |
| --- | --- | --- |
| `validation` | 422, le sonraí réimse in `errors` | Níl |
| `authentication` | 401 | Níl |
| `authorization` | 403 | Níl |
| `not_found` | 404 | Níl |
| `conflict` | 409 | Uaireanta |
| `precondition` | 412 | Níl |
| `quota` | 402 don phlean, 413 don mhéid | Níl |
| `rate_limit` | 429, le `Retry-After` | Tá |
| `upstream` | 502 nó 504 | Tá |
| `internal` | 500 | Tá |

Luaigh `request_id` nuair a théann tú i dteagmháil leis an tacaíocht.

## Webhooks <!--quire:webhooks-->

Liostáil ag `/admin/webhooks`, nó tríd an API ag `/webhook_subscriptions`. Roghnaigh imeachtaí de réir ainm (`enrolment.created`), de réir réimse (`enrolment.*`) nó gach imeacht (`*`). Seolann Quire `webhook.ping` ar dtús; cuirtear tús leis an síntiús nuair a fhreagraíonn do chríochphointe dó.

Leanann seachadtaí sonraíocht Standard Webhooks:

```
POST /hooks/quire
webhook-id: 01JB7XQK4Z8FQ2M3N4P5R6S7T8
webhook-timestamp: 1790000000
webhook-signature: v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE=
```

Chun seachadadh a fhíorú:

1. Tóg an téad `{webhook-id}.{webhook-timestamp}.{raw body}` ó na bearta cruinne a fuarthas, sula bparsálann tú JSON.
2. Ríomh HMAC-SHA256 uirthi le rún do shíntiúis, agus ionchódaigh an toradh mar base64.
3. Déan comparáid leanúnach ama idir é agus gach luach `v1,` in `webhook-signature`. D’fhéadfadh dhá cheann a bheith ann le linn rothlú rúin; tá aon mheaitseáil amháin bailí.
4. Diúltaigh stampa ama atá níos mó ná cúig nóiméad ó d’uaireadóir.

```
import { createHmac, timingSafeEqual } from 'node:crypto';

function verify(secret, id, timestamp, rawBody, header) {
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
  const expected = createHmac('sha256', Buffer.from(secret.replace(/^whsec_/, ''), 'base64'))
    .update(`${id}.${timestamp}.${rawBody}`).digest();
  return header.split(' ').some((part) => {
    const [version, value] = part.split(',');
    const given = Buffer.from(value ?? '', 'base64');
    return version === 'v1' && given.length === expected.length && timingSafeEqual(given, expected);
  });
}
```

Déan dúblaigh a dhí-dhúbailt ar `webhook-id`: d’fhéadfadh seachadadh teacht níos mó ná uair amháin. Bíonn aitheantóirí agus achoimre ghairid sa chorp; faigh an acmhainn chun a staid reatha a fháil. Déantar iarrachtaí athsheolta ar theipeanna le moill mhéadaithe ar feadh suas le 72 uair, agus is féidir iad a athsheoladh ón loga seachadta.

## MCP <!--quire:mcp-->

Tá freastalaí MCP Quire ag `/mcp` ar sheoladh na heagraíochta, trí HTTP sruthaithe. Aimsíonn cliant MCP freastalaí OAuth ó `/.well-known/oauth-protected-resource`; síníonn an duine isteach agus toilíonn sé mar a dhéanfadh sé le haon chliant OAuth. Gníomhaíonn uirlisí thar ceann an duine lena cheadanna, agus iarrann uirlisí millteanacha dearbhú. Roghnaíonn riarthóirí na huirlisí atá ar fáil ag `/admin/integrations/mcp`.

<figure class="quire-shot" lang="en" dir="ltr"><img src="/screenshots/admin-mcp.webp" alt="The AI assistants page with the server address to give an assistant and a table of the tools it can use." width="944" height="700" loading="lazy" decoding="async"><figcaption>AI assistants (MCP): the server address, and the tools an assistant may call.</figcaption></figure>

## Pleananna agus an API <!--quire:plans-and-the-api-->

Baineann eochracha API, cliaint OAuth, webhooks agus freastalaí MCP le teidlíocht API an phlean; cuimsíonn gach plean caighdeánach í. Mura bhfuil sí i bplean, diúltaítear do chruthú eochrach, cliaint nó síntiúis; diúltaítear d’iarratais scríofa REST agus do naisc MCP; leanann léamh REST ar aghaidh ionas gur féidir na sonraí a easpórtáil. Is doiciméad faidhbe é an diúltú leis an gcód `commerce.plan_entitlement`, sa chatagóir `precondition`.

## Eisínteachtaí <!--quire:extensions-->

Dearbhaítear cineálacha gníomhaíochta, bloic, modhanna clárúcháin, modhanna sínithe isteach, cineálacha ceiste, tuarascálacha, téamaí agus comhtháthuithe Quire sa chlárlann chéanna eisínteachtaí ar féidir le suiteáil féinóstáilte cur léi. Tiomsaítear eisínteachtaí isteach: níl lódálaí breiseán le linn rite ann agus ní féidir le heagraíocht óstáilte ceann a chur leis. Casann riarthóirí gach eisínteacht air nó as dá n-eagraíocht ag `/admin/extensions` (féach [treoir an riarthóra](/ga/admin/extensions/)).

Chun eisínteacht a scríobh, tosaigh leis an mbloc samplach agus an téama samplach in `packages/integration/extensions/src/sample.ts`. Roghnaigh an pointe eisínteachta agus léigh a chonradh in `points.ts`; dearbhaigh an eisínteacht ansin le haitheantas, leagan, ceadúnas, a bhfuil ar fáil agus a bhfuil de dhíth uirthi, agus an féidir le heagraíocht í a mhúchadh. Cláraigh í san áit a gcuirtear an feidhmchlár gréasáin agus an worker le chéile, ionas go n-aontaíonn siad. Seiceálann an chlárlann rialacha gach pointe nuair a thógtar í agus gach uair a ghlaonn tú `register`; diúltaíonn sí do thacar neamhbhailí agus luann sí gach fadhb, gan an chlárlann a athrú. Ba cheart do thástálacha na heisínteachta a dhearbhú go bhfuil `extensionContractProblems` folamh di agus go n-athraíonn múchadh na heisínteachta an méid a mbíonn tionchar aici air.

Source: https://docs.quirelms.com/ga/developer/index.mdx