---
title: "Gid pou devlopè"
description: "REST API Quire a, OAuth, webhook, sèvè MCP ak ekstansyon."
image: "https://docs.quirelms.com/og.png"
---

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

# Gid pou devlopè

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

Sèvi ak adrès API òganizasyon w lan ak kalifikatif ki gen scope limite. Kòmanse ak yon demann lekti, verifye repons lan, epi pa mete sekrè nan kontwòl kòd sous ni nan egzanp dokimantasyon.

Quire gen yon sèl API piblik: REST sou HTTPS, ki dokimante nan yon fichye OpenAPI 3.1, ak webhook siyen pou evènman ak sèvè MCP pou asistan IA. [Referans API a](https://docs.quirelms.com/api/) bay lis tout endpoint ak evènman.

## Adrès <!--quire:addresses-->

Chak òganizasyon gen pwòp adrès li, epi API a anba adrès sa a:

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

Se kalifikatif la ki detèmine òganizasyon an. Yo refize yon kle ki fèt pou yon òganizasyon si yo sèvi avè l sou adrès yon lòt.

Yo bay dokiman OpenAPI a nan `/api/v1/openapi.json` sou adrès nenpòt òganizasyon, konsa jeneratè client yo toujou wè vèsyon API w ap rele a.

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

**Kle API** sèvi pou script ak entegrasyon ant sèvè. Yon administratè kreye youn nan `/admin/integrations/api-keys`, chwazi scope li epi wè li yon sèl fwa. Voye li kòm bearer token:

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

Kle yo kòmanse ak `qk_live_` oswa `qk_test_`. Bay chak entegrasyon pwòp kle pa li.

**OAuth 2.1** sèvi pou aplikasyon ki aji kòm yon moun ki konekte. Anrejistre yon client nan `/admin/integrations/oauth-clients`, epi sèvi ak koule kòd otorizasyon ak PKCE (`/oauth/authorize`, `/oauth/token`), oswa kalifikatif client pou yon client machin. Dekouvèt disponib nan `/.well-known/oauth-authorization-server`. Yon scope limite sa token an kapab fè; li pa janm ba li plis dwa pase moun nan.

Scope yo se `resource:read`, `resource:write` ak `resource:delete`, pa egzanp `courses:read` oswa `enrolments:write`. Gen kat scope privilejye epi yo parèt avèk avètisman sou ekran konsantman an: `audit:read`, `roles:write`, `tenants:write` ak `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>

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

- **Paj**: tout lis sèvi ak cursor pou pajinasyon. Pase `limit`, epi mete `next_cursor` ki nan `page` kòm `cursor` toutotan `has_more` vre (gade egzanp pi ba). Pa gen offset.
- **Chanjman depi**: `updated_since` retounen sa ki chanje apre yon lè. Mete `include_deleted=true` avè l, oswa li `/<resource>/deletions`, pou konnen sa yo retire.
- **Idantifyan ekstèn**: pifò resous aksepte pwòp `external_id` pa w. `/<resource>/ext:{external_id}` li oswa kreye/mizajou sou baz ID sa a, konsa senkronizasyon pa bezwen konsève idantifyan Quire yo.
- **Idempotency**: voye header `Idempotency-Key` nan `POST`, `PATCH` ak `DELETE`. Lè w repete demann nan ak menm kle a, li retounen premye repons lan olye li fè travay la de fwa. Endpoint an gwo yo egzije li.
- **Vèsyon**: gwo vèsyon an nan chemen an (`/v1`). Andedan li, chak chanjman ki kraze konpatibilite se yon revizyon ak dat, yo chwazi ak header `Quire-Version`, pa egzanp `Quire-Version: 2026-09-20`. San header la, ou jwenn revizyon ki te aktyèl lè yo te bay kalifikatif ou a.

Men yon paj nan lis:

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

## Erè <!--quire:errors-->

Chak erè se yon dokiman pwoblèm 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..."}
```

Baze lojik ou sou `code`, ki estab; `detail` ekri pou moun, li san danje pou montre epi li ka chanje. Lè w pa rekonèt yon kòd, klase dapre `category`:

| Kategori | Estati | Eseye ankò |
| --- | --- | --- |
| `validation` | 422, ak detay chan nan `errors` | Non |
| `authentication` | 401 | Non |
| `authorization` | 403 | Non |
| `not_found` | 404 | Non |
| `conflict` | 409 | Pafwa |
| `precondition` | 412 | Non |
| `quota` | 402 pou plan, 413 pou gwosè | Non |
| `rate_limit` | 429, ak `Retry-After` | Wi |
| `upstream` | 502 oswa 504 | Wi |
| `internal` | 500 | Wi |

Lè w kontakte sèvis asistans lan, bay `request_id` la.

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

Abòne nan `/admin/webhooks` oswa atravè API a nan `/webhook_subscriptions`. Chwazi evènman pa non (`enrolment.created`), pa domèn (`enrolment.*`) oswa tout evènman (`*`). Quire voye `webhook.ping` an premye; abònman an kòmanse lè endpoint pa w la reponn.

Livrezon yo swiv spesifikasyon Standard Webhooks la:

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

Pou verifye livrezon an:

1. Avèk octet egzak ou resevwa yo, anvan analiz JSON, konstwi chèn `{webhook-id}.{webhook-timestamp}.{raw body}`.
2. Kalkile HMAC-SHA256 sou li ak sekrè abònman w lan epi konvèti l an base64.
3. Konpare li ak chak valè `v1,` nan `webhook-signature`, san varyasyon tan. Pandan chanjman sekrè, kapab genyen de; nenpòt nan yo ki koresponn valab.
4. Refize timestamp ki gen plis pase senk minit diferans ak revèy pa w.

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

Evite doublon dapre `webhook-id`: menm livrezon an ka rive plizyè fwa. Kò a gen idantifyan ak yon ti rezime; chèche resous la pou jwenn eta aktyèl li. Yo rekòmanse livrezon ki echwe yo avèk reta k ap ogmante pandan jiska 72 èdtan; ou kapab voye yo ankò nan jounal livrezon an.

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

Sèvè MCP Quire a nan `/mcp` sou adrès òganizasyon an, sou HTTP ki ka voye done an plizyè pati. Yon client MCP dekouvri sèvè OAuth la nan `/.well-known/oauth-protected-resource`; moun nan konekte epi bay konsantman menm jan ak pou nenpòt client OAuth. Zouti yo aji kòm moun nan, ak pèmisyon li; zouti ki destriktif mande konfimasyon. Administratè yo chwazi ki zouti ki disponib nan `/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>

## Plan ak API a <!--quire:plans-and-the-api-->

Kle API, client OAuth, webhook ak sèvè MCP antre nan dwa API plan an, epi tout plan estanda gen dwa sa a. Nan yon plan ki pa genyen li, yo refize kreye kle, client oswa abònman; yo refize ekriti REST ak koneksyon MCP, men lekti REST kontinye mache pou done yo ka ekspòte. Refiz la se yon dokiman pwoblèm ak kòd `commerce.plan_entitlement`, nan kategori `precondition`.

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

Yo deklare pwòp kalite aktivite, blòk, metòd enskripsyon, metòd koneksyon, kalite kesyon, rapò, tèm ak entegrasyon Quire yo nan menm rejis ekstansyon an kote enstalasyon oto-akomode kapab ajoute. Yo konpile ekstansyon yo nan aplikasyon an: pa gen loader plugin pandan ekzekisyon, epi yon òganizasyon ki sèvi ak sèvis akomode pa kapab ajoute youn. Administratè yo aktive oswa dezaktive chak ekstansyon pou òganizasyon yo nan `/admin/extensions` (gade [gid administratè a](/ht/admin/extensions/)).

Pou ekri youn, kòmanse ak blòk ak tèm egzanp nan `packages/integration/extensions/src/sample.ts`. Chwazi pwen ekstansyon an epi li kontra li nan `points.ts`; apre sa deklare ekstansyon an ak yon ID, vèsyon, lisans, sa li bay ak sa li bezwen, epi si yon òganizasyon kapab dezaktive li. Anrejistre li kote yo rasanble aplikasyon web la ak worker a pou yo dakò. Rejis la verifye pwòp règ chak pwen lè yo bati li ak chak fwa ou rele `register`; si yon seri pa valab, li refize li epi bay non chak pwoblèm, san li pa chanje rejis la. Tès ekstansyon an ta dwe verifye `extensionContractProblems` vid pou li epi dezaktive li chanje sa li afekte.

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