---
title: "Stiùireadh an leasaiche"
description: "API REST Quire, OAuth, webhooks, frithealaiche MCP agus leudachain."
image: "https://docs.quirelms.com/og.png"
---

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

# Stiùireadh an leasaiche

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

Cleachd seòladh API na buidhne agad agus teisteanas le raointean cuingichte. Tòisich le iarrtas leughaidh, thoir sùil air an fhreagairt agus cùm dìomhaireachdan taobh a-muigh smachd-tùis agus eisimpleirean sgrìobhainnean.

Tha aon API poblach aig Quire: REST thar HTTPS, air a mhìneachadh ann an sgrìobhainn OpenAPI 3.1, le webhooks soidhnichte airson tachartasan agus frithealaiche MCP do luchd-cuideachaidh AI. Tha an [iomradh API](https://docs.quirelms.com/api/) a’ liostadh gach puing-crìche agus tachartas.

## Seòlaidhean <!--quire:addresses-->

Tha seòladh fhèin aig gach buidheann agus tha an API fo:

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

Tha an teisteanas a’ dearbhadh na buidhne. Thèid iuchair airson aon bhuidheann a chleachdadh aig seòladh buidhne eile a dhiùltadh.

Tha an sgrìobhainn OpenAPI ri fhaighinn aig `/api/v1/openapi.json` air seòladh buidheann sam bith; chì gineadairean cliant an tionndadh a tha thu a’ gairm an-còmhnaidh.

## Dearbhadh <!--quire:authentication-->

Tha **Iuchraichean API** airson sgriobtaichean is amalachadh frithealaiche-gu-frithealaiche. Cruthaichidh rianaire tè aig `/admin/integrations/api-keys`, taghaidh e na raointean aice agus chì e i aon turas. Cuir mar thòcan giùlain i:

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

Tòisichidh iuchraichean le `qk_live_` no `qk_test_`. Thoir iuchair eadar-dhealaichte do gach amalachadh.

Tha **OAuth 2.1** airson aplacaidean a tha ag obair mar neach clàraichte a-steach. Clàraich cliant aig `/admin/integrations/oauth-clients`, agus an uair sin cleachd sruth còd ceadachaidh le PKCE (`/oauth/authorize`, `/oauth/token`), no teisteanasan cliant airson cliant inneil. Tha lorg ri fhaighinn aig `/.well-known/oauth-authorization-server`. Caolaichidh raon na ghabhas tòcan dèanamh; cha toir e cothrom dha barrachd a dhèanamh na dh’fhaodadh an neach.

Is iad na raointean `resource:read`, `resource:write` agus `resource:delete`, mar `courses:read` no `enrolments:write`. Tha ceithir dhiubh fo shochairean agus nochdaidh rabhadh orra air sgrìn a’ cheadachaidh: `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>

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

- **Duilleagachadh**: tha gach liosta air a duilleagachadh le cursair. Cuir `limit` agus an uair sin `next_cursor` à `page` mar `cursor` fhad ’s a tha `has_more` fìor (faic an eisimpleir gu h-ìosal). Chan eil offset ann.
- **Atharrachaidhean o àm**: tillidh `updated_since` na dh’atharraich an dèidh àm. Cuir `include_deleted=true` ris no leugh `/<resource>/deletions` gus faighinn a-mach dè chaidh a thoirt air falbh.
- **Aithnichearan bhon taobh a-muigh**: gabhaidh a’ mhòr-chuid de ghoireasan ris an `external_id` agad fhèin, agus leughaidh no cuiridh `/<resource>/ext:{external_id}` suas e leis; cha leig sioncronachadh mar sin leat aithnichearan Quire a stòradh.
- **Idempotency**: cuir bann-cinn `Idempotency-Key` air `POST`, `PATCH` agus `DELETE`. Tillidh ath-oidhirp leis an aon iuchair a’ chiad fhreagairt an àite an obair a dhèanamh dà thuras. Feumaidh puingean-crìche mòra seo.
- **Tionndaidhean**: tha an tionndadh mòr san t-slighe (`/v1`). Taobh a-staigh dheth, ’s e lèirmheas le ceann-là a th’ ann an gach atharrachadh briste, taghte leis a’ bhann-cinn `Quire-Version`, mar `Quire-Version: 2026-09-20`. Gun a’ bhann-cinn, gheibh thu an lèirmheas a bha làithreach nuair a chaidh an teisteanas agad a chur a-mach.

Duilleag de liosta:

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

## Mearachdan <!--quire:errors-->

Tha gach mearachd na sgrìobhainn duilgheis RFC 9457:

```
{"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..."}
```

Stèidhich làimhseachadh air `code`, a tha seasmhach; tha `detail` sgrìobhte do dhaoine, sàbhailte ri shealltainn dhaibh agus faodaidh e atharrachadh. Nuair nach aithnich thu còd, cuir e sa bhucaid a rèir `category`:

| Roinn | Inbhe | Feuch a-rithist |
| --- | --- | --- |
| `validation` | 422, le fiosrachadh mu raointean ann an `errors` | Chan eil |
| `authentication` | 401 | Chan eil |
| `authorization` | 403 | Chan eil |
| `not_found` | 404 | Chan eil |
| `conflict` | 409 | Uaireannan |
| `precondition` | 412 | Chan eil |
| `quota` | 402 airson a’ phlana, 413 airson meud | Chan eil |
| `rate_limit` | 429, le `Retry-After` | Tha |
| `upstream` | 502 no 504 | Tha |
| `internal` | 500 | Tha |

Thoir luaidh air `request_id` nuair a chuireas tu fios gu taic.

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

Fo-sgrìobh aig `/admin/webhooks`, no tron API aig `/webhook_subscriptions`. Tagh tachartasan a rèir ainm (`enrolment.created`), a rèir raoin (`enrolment.*`) no iad uile (`*`). Cuiridh Quire `webhook.ping` an toiseach; tòisichidh an fho-sgrìobhadh nuair a fhreagras a’ phuing-crìche agad air.

Tha lìbhrigeadh a’ leantainn sònrachadh Standard Webhooks:

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

Gus lìbhrigeadh a dhearbhadh:

1. Tog an t-sreang `{webhook-id}.{webhook-timestamp}.{raw body}` às na dearbh bhaitean a fhuaireadh, mus dèanar parsadh JSON sam bith.
2. Obraich a-mach HMAC-SHA256 oirre leis an dìomhaireachd fo-sgrìobhaidh agad agus còdaich i mar base64.
3. Dèan coimeas ann an ùine sheasmhach ris gach luach `v1,` ann an `webhook-signature`. Dh’fhaodadh dà luach a bhith ann rè tionndadh dìomhaireachd; tha maids sam bith dligheach.
4. Diùlt stampa-ama a tha còrr is còig mionaidean bhon ghleoc agad.

```
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);
  });
}
```

Cuir às do dhùblaidhean a rèir `webhook-id`: dh’fhaodadh lìbhrigeadh ruigsinn barrachd is aon turas. Tha aithnichearan agus geàrr-chunntas goirid anns a’ chorp; faigh an goireas gus a staid làithreach fhaighinn. Feuchaidh Quire ri lìbhrigeadh a dh’fhàillig a-rithist le dàil mean air mhean airson suas ri 72 uair a thìde; faodar an ath-chluich on log lìbhrigidh.

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

Tha frithealaiche MCP Quire aig `/mcp` air seòladh na buidhne, tro HTTP sruthaichte. Lorgaidh cliant MCP am frithealaiche OAuth bho `/.well-known/oauth-protected-resource`, agus clàraidh an neach a-steach is bheir e cead dìreach mar le cliant OAuth sam bith. Bidh innealan ag obair mar an neach sin agus leis na ceadan aige; iarraidh innealan millteach dearbhadh. Taghaidh rianairean dè na h-innealan a bhios rim faighinn aig `/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>

## Planaichean is an API <!--quire:plans-and-the-api-->

Tha iuchraichean API, cliantan OAuth, webhooks agus frithealaiche MCP an urra ri còir API a’ phlana, agus tha a’ chòir sin anns gach plana àbhaisteach. Ma tha i a dhìth, thèid cruthachadh iuchrach, cliant no fo-sgrìobhaidh a dhiùltadh, thèid sgrìobhaidhean REST agus ceanglaichean MCP a dhiùltadh, ach leanaidh leughaidhean REST orra gus am bi an dàta às-phortail. ’S e sgrìobhainn duilgheis a th’ anns an diùltadh, leis a’ chòd `commerce.plan_entitlement`, san roinn `precondition`.

## Leudachain <!--quire:extensions-->

Tha seòrsaichean gnìomh, blocaichean, dòighean clàraidh, dòighean clàraidh a-steach, seòrsaichean cheistean, aithisgean, cuspairean agus amalachadh Quire fhèin air an cur an cèill tron aon chlàr-leudachaidh ris an urrainn do stàladh fèin-aoigheachd rudan a chur ris. Tha leudachain air an cur ri chèile: chan eil luchdadair plugan rè-ruith ann agus chan urrainn do bhuidheann aoigheachd fear a chur ris. Cuiridh rianairean gach leudachan air no dheth airson na buidhne aca aig `/admin/extensions` (faic [stiùireadh an rianaire](/gd/admin/extensions/)).

Gus fear a sgrìobhadh, tòisich leis a’ bhloc agus an cuspair sampall ann an `packages/integration/extensions/src/sample.ts`. Tagh puing leudachaidh agus leugh a cùmhnant ann an `points.ts`; an uair sin cuir an leudachan an cèill le ID, tionndadh, ceadachas, na tha e a’ toirt seachad agus ag iarraidh, agus an urrainn do bhuidheann a chur dheth. Clàraich e far a bheil an t-aplacaid-lìn agus am pròiseas obrach air an cur ri chèile gus am bi iad ag aontachadh le chèile. Nì an clàr sgrùdadh air riaghailtean puing fhèin nuair a thèid a thogail agus gach turas a ghairmeas tu `register`; diùlt e seata neo-dhligheach le ainm gach duilgheis agus fàgaidh e an clàr gun atharrachadh. Bu chòir do dheuchainnean an leudachain dearbhadh gu bheil `extensionContractProblems` falamh air a shon agus gu bheil cur dheth ag atharrachadh na tha e a’ toirt buaidh air.

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