---
title: "Canllaw datblygwr"
description: "API REST Quire, OAuth, webhooks, gweinydd MCP ac estyniadau."
image: "https://docs.quirelms.com/og.png"
---

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

# Canllaw datblygwr

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

Defnyddiwch gyfeiriad API eich sefydliad a manylyn dilysu â chwmpas cyfyngedig. Dechreuwch â chais darllen, gwiriwch yr ymateb, a chadwch gyfrinachau y tu allan i reolaeth ffynhonnell ac enghreifftiau dogfennaeth.

Dim ond un API cyhoeddus sydd gan Quire: REST dros HTTPS, a ddisgrifir gan
ddogfen OpenAPI 3.1, gyda webhooks wedi'u llofnodi ar gyfer digwyddiadau a gweinydd MCP ar gyfer
cynorthwywyr AI. Mae'r [cyfeirnod API](https://docs.quirelms.com/api/) yn rhestru pob endpoint a digwyddiad.

## Cyfeiriadau <!--quire:addresses-->

Mae gan bob sefydliad ei gyfeiriad ei hun, ac mae'r API oddi tano:

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

Y manylyn dilysu sy'n pennu'r sefydliad. Gwrthodir allwedd ar gyfer un sefydliad a ddefnyddir yng
nghyfeiriad un arall.

Mae dogfen OpenAPI yn cael ei gwasanaethu yn `/api/v1/openapi.json` ar gyfeiriad unrhyw
sefydliad, felly mae generaduron cleientiaid bob amser yn gweld y fersiwn rydych yn ei
galw.

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

Mae **allweddi API** ar gyfer sgriptiau ac integreiddiadau rhwng gweinyddion. Mae
gweinyddwr yn creu un yn `/admin/integrations/api-keys`, yn dewis ei
chwmpasau, ac yn ei gweld unwaith. Anfonwch hi fel tocyn bearer:

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

Mae allweddi'n dechrau ag `qk_live_` neu `qk_test_`. Rhowch allwedd ar wahân i bob integreiddiad.

Mae **OAuth 2.1** ar gyfer rhaglenni sy'n gweithredu fel person sydd wedi mewngofnodi. Cofrestrwch
gleient yn `/admin/integrations/oauth-clients`, yna defnyddiwch lif cod awdurdodi
gyda PKCE (`/oauth/authorize`, `/oauth/token`), neu gymwysterau cleient
ar gyfer cleient peiriant. Mae darganfod yn `/.well-known/oauth-authorization-server`.
Mae cwmpas yn cyfyngu'r hyn y gall tocyn ei wneud; nid yw byth yn gadael iddo wneud mwy nag y gallai'r person.

Cwmpasau yw `resource:read`, `resource:write` a `resource:delete`, er
enghraifft `courses:read` neu `enrolments:write`. Mae pedwar'n freintiedig ac yn cael eu dangos
â rhybudd ar y sgrin cydsynio: `audit:read`, `roles:write`,
`tenants:write` a `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>

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

- **Tudaleniad**: mae pob rhestr yn defnyddio cyrchwyr. Anfonwch `limit`, yna'r
  `next_cursor` o `page` fel `cursor` tra bo `has_more` yn wir (enghraifft
  isod). Nid oes offset.
- **Newidiadau ers**: mae `updated_since` yn dychwelyd yr hyn a newidiodd ar ôl amser.
  Pârwch ef â `include_deleted=true`, neu darllenwch `/<resource>/deletions`, i
  wybod beth gafodd ei dynnu.
- **Dynodwyr allanol**: mae'r rhan fwyaf o adnoddau'n derbyn eich `external_id` eich hun,
  ac mae `/<resource>/ext:{external_id}` yn darllen neu'n uwchlwytho drwy'r ID hwnnw, felly nid oes
  angen i gydamseriad gadw dynodwyr Quire byth.
- **Idempotedd**: anfonwch bennawd `Idempotency-Key` ar `POST`, `PATCH` a
  `DELETE`. Mae cais arall gyda'r un allwedd yn dychwelyd yr ymateb cyntaf yn hytrach na
  gwneud y gwaith ddwywaith. Mae endpoints swmp yn ei gwneud yn ofynnol.
- **Fersiynau**: mae'r brif fersiwn yn y llwybr (`/v1`). Oddi mewn iddo, mae pob
  newid sy'n torri cydnawsedd yn adolygiad â dyddiad, wedi'i ddewis gyda'r pennawd
  `Quire-Version`, er enghraifft `Quire-Version: 2026-09-20`. Heb y pennawd, cewch
  yr adolygiad oedd yn gyfredol pan gyhoeddwyd eich manylyn dilysu.

Tudalen o restr:

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

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

Dogfen broblem RFC 9457 yw pob gwall:

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

Dewiswch weithred yn ôl `code`, sy'n sefydlog; mae `detail` wedi'i ysgrifennu i bobl, yn ddiogel i'w
ddangos iddynt, a gall newid. Pan nad ydych yn adnabod cod, grwpiwch yn ôl
`category`:

| Categori | Statws | Ailgeisio |
| --- | --- | --- |
| `validation` | 422, gyda manylion maes yn `errors` | Na |
| `authentication` | 401 | Na |
| `authorization` | 403 | Na |
| `not_found` | 404 | Na |
| `conflict` | 409 | Weithiau |
| `precondition` | 412 | Na |
| `quota` | 402 ar gyfer y cynllun, 413 ar gyfer maint | Na |
| `rate_limit` | 429, gyda `Retry-After` | Iawn |
| `upstream` | 502 neu 504 | Iawn |
| `internal` | 500 | Iawn |

Dyfynnwch `request_id` wrth gysylltu â'r tîm cymorth.

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

Tanysgrifiwch yn `/admin/webhooks`, neu drwy'r API yn
`/webhook_subscriptions`. Dewiswch ddigwyddiadau yn ôl enw (`enrolment.created`),
yn ôl ardal (`enrolment.*`) neu bob un (`*`). Mae Quire yn anfon `webhook.ping` yn gyntaf; mae'r
 tanysgrifiad yn dechrau unwaith y bydd eich endpoint yn ei ateb.

Mae dosbarthiadau'n dilyn manyleb Standard Webhooks:

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

I wirio dosbarthiad:

1. Lluniwch y llinyn `{webhook-id}.{webhook-timestamp}.{raw body}` o'r
   union beitiau a dderbyniwyd, cyn dosrannu unrhyw JSON.
2. Cyfrifwch HMAC-SHA256 drosto gyda chyfrinach eich tanysgrifiad, a'i amgodio yn base64.
3. Cymharwch yn gyson o ran amser bob gwerth `v1,` yn `webhook-signature`.
   Gall fod dau yn ystod newid cyfrinach; mae'r naill baru neu'r llall yn ddilys.
4. Gwrthodwch stamp amser sydd fwy na phum munud o'ch cloc.

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

Atal dyblygu drwy `webhook-id`: gall dosbarthiad gyrraedd fwy nag unwaith. Mae'r corff
yn cynnwys dynodwyr a chrynodeb byr; nôl yr adnodd i gael ei gyflwr cyfredol.
Ail-geisir dosbarthiadau a fethodd gydag oedi cynyddol am hyd at 72 awr, a
gellir eu hailchwarae o'r cofnod dosbarthu.

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

Mae gweinydd MCP Quire yn `/mcp` ar gyfeiriad y sefydliad, dros
HTTP ffrydiadwy. Mae cleient MCP yn darganfod gweinydd OAuth o
`/.well-known/oauth-protected-resource`, ac mae'r person yn mewngofnodi ac yn
cydsynio fel gydag unrhyw gleient OAuth. Mae offer yn gweithredu fel y person hwnnw, gyda'i
ganiatadau, ac mae offer dinistriol yn gofyn am gadarnhad. Gweinyddwyr sy'n
 dewis pa offer sydd ar gael yn `/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>

## Cynlluniau a'r API <!--quire:plans-and-the-api-->

Mae allweddi API, cleientiaid OAuth, webhooks a gweinydd MCP yn perthyn i hawl API y cynllun,
a chaiff pob cynllun safonol ei chynnwys. Ar gynllun heb yr hawl honno, gwrthodir creu
allwedd, cleient neu danysgrifiad, gwrthodir ysgrifennu REST a chysylltiadau MCP,
ac mae darlleniadau REST yn parhau i weithio fel bod modd allforio data. Dogfen broblem yw'r gwrthodiad gyda'r
cod `commerce.plan_entitlement`, yn y categori `precondition`.

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

Datganir mathau gweithgaredd, blociau, dulliau cofrestru, dulliau mewngofnodi, mathau
cwestiwn, adroddiadau, themâu ac integreiddiadau Quire ei hun drwy'r un gofrestrfa
estyniadau y gall gosodiad hunangynhaliol ychwanegu ati. Caiff estyniadau eu crynhoi i mewn:
nid oes llwythwr ategion amser rhedeg, ac ni all sefydliad lletyol ychwanegu un.
Mae gweinyddwyr yn troi pob estyniad ymlaen neu i ffwrdd ar gyfer eu sefydliad yn
`/admin/extensions` (gweler y [canllaw gweinyddwr](/cy/admin/extensions/)).

I ysgrifennu un, dechreuwch o'r bloc a'r thema sampl yn
`packages/integration/extensions/src/sample.ts`. Dewiswch y pwynt estyniad a
darllenwch ei gontract yn `points.ts`, yna datganwch yr estyniad gyda dynodwr, fersiwn,
trwydded, yr hyn mae'n ei ddarparu a'i angen, ac a all sefydliad ei ddiffodd.
Cofrestrwch ef lle mae'r rhaglen we a'r worker yn cael eu cyfansoddi, fel bod y ddau'n
cytuno. Mae'r gofrestrfa'n gwirio rheolau pob pwynt wrth ei hadeiladu a phob tro y
byddwch yn galw `register`, yn gwrthod set a fyddai'n annilys gan enwi pob problem,
ac yn gadael y gofrestrfa heb ei newid pan fydd hynny'n digwydd. Dylai profion yr estyniad ei hun
gadarnhau bod `extensionContractProblems` yn wag ar ei gyfer a bod ei ddiffodd yn newid
yr hyn mae'n effeithio arno.

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