---
title: "Arendaja juhend"
description: "Quire'i REST API, OAuth, veebikonksud, MCP-server ja laiendused."
image: "https://docs.quirelms.com/og.png"
---

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

# Arendaja juhend

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

Kasuta oma organisatsiooni API-aadressi ja piiratud ulatusega mandaati. Alusta lugemispäringuga, kontrolli vastust ning hoia saladused lähtekoodist ja dokumentatsiooni näidetest väljas.

Quire'il on üks avalik API: HTTPS-i kaudu kasutatav REST, mida kirjeldab
OpenAPI 3.1 dokument; sündmuste jaoks on allkirjastatud veebikonksud ning
tehisintellekti assistentidele MCP-server. [API viitedokumentatsioonis](https://docs.quirelms.com/api/)
on loetletud kõik lõpp-punktid ja sündmused.

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

Igal organisatsioonil on oma aadress, mille all paikneb ka API:

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

Organisatsiooni määrab mandaat. Kui ühe organisatsiooni võtit kasutatakse teise
organisatsiooni aadressil, lükatakse see tagasi.

OpenAPI dokumenti serveeritakse iga organisatsiooni aadressil
`/api/v1/openapi.json`, nii et koodi genereerivad tööriistad näevad alati
kasutatavat versiooni.

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

**API võtmed** sobivad skriptidele ja serveritevahelistele integratsioonidele.
Haldur loob võtme aadressil `/admin/integrations/api-keys`, määrab selle ulatused
ja näeb seda ühe korra. Saada see päises kandja märgina:

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

Võtmed algavad `qk_live_` või `qk_test_`. Anna igale integratsioonile oma võti.

**OAuth 2.1** sobib rakendustele, mis tegutsevad sisseloginud inimese nimel.
Registreeri klient aadressil `/admin/integrations/oauth-clients` ning kasuta
PKCE-ga autoriseerimiskoodi voogu (`/oauth/authorize`, `/oauth/token`) või
masinklientide jaoks kliendi mandaati. Avastusdokument asub aadressil
`/.well-known/oauth-authorization-server`. Ulatus piirab loa tegevusi; see ei
anna kunagi inimese enda õigustest suuremaid õigusi.

Ulatused on `resource:read`, `resource:write` ja `resource:delete`, näiteks
`courses:read` või `enrolments:write`. Neli privilegeeritud ulatust kuvatakse
nõusolekuvaates hoiatusega: `audit:read`, `roles:write`, `tenants:write` ja
`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>

## Päringud <!--quire:requests-->

- **Lehekülgede kaupa pärimine**: kõik loendid kasutavad kursoripõhist
  lehekülgede kaupa pärimist. Anna `limit` ning seejärel edasta `next_cursor`
  väljast `page` järgmises päringus `cursor`-ina, kuni `has_more` on tõene
  (näide allpool). Nihkepiirangut pole.
- **Muudatused alates ajast**: `updated_since` tagastab pärast määratud aega
  muutunud andmed. Koos sellega kasuta valikut `include_deleted=true` või loe
  eemaldatute leidmiseks `/<resource>/deletions`.
- **Välised tunnused**: enamik ressursse lubab määrata enda `external_id`-i;
  aadress `/<resource>/ext:{external_id}` võimaldab selle alusel lugeda või
  lisada-uuendada, nii et sünkroonimisel pole vaja Quire'i tunnuseid salvestada.
- **Korduste vältimine**: saada päis `Idempotency-Key` päringuga `POST`, `PATCH`
  või `DELETE`. Sama võtmega korduspäring tagastab algse vastuse, selle asemel et
  toimingu uuesti teha. Hulgi-lõpp-punktid nõuavad seda.
- **Versioonid**: põhiversioon paikneb tees (`/v1`). Selle piires valitakse iga
  katkestav muudatus kuupäevaga versioonina päises `Quire-Version`, näiteks
  `Quire-Version: 2026-09-20`. Päise puudumisel saad mandaadi väljastamise ajal
  kehtinud versiooni.

Loendi üks lehekülg:

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

## Tõrked <!--quire:errors-->

Kõik tõrked on RFC 9457 probleemidokumendid:

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

Haru vali `code` välja järgi, mis on püsiv; `detail` on inimestele mõeldud ohutu
tekst, mis võib muutuda. Tundmatu koodi korral kasuta rühmitamiseks välja
`category`:

| Kategooria | Olek | Korduspäring |
| --- | --- | --- |
| `validation` | 422, välja üksikasjad `errors` väljas | Ei |
| `authentication` | 401 | Ei |
| `authorization` | 403 | Ei |
| `not_found` | 404 | Ei |
| `conflict` | 409 | Mõnikord |
| `precondition` | 412 | Ei |
| `quota` | plaani puhul 402, suuruse puhul 413 | Ei |
| `rate_limit` | 429, päisega `Retry-After` | Jah |
| `upstream` | 502 või 504 | Jah |
| `internal` | 500 | Jah |

Toe poole pöördudes lisa `request_id`.

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

Telli aadressil `/admin/webhooks` või API kaudu aadressil
`/webhook_subscriptions`. Vali sündmused nime järgi (`enrolment.created`),
valdkonna järgi (`enrolment.*`) või kõik (`*`). Quire saadab esmalt sündmuse
`webhook.ping`; tellimus aktiveeritakse, kui sinu lõpp-punkt sellele vastab.

Edastused järgivad Standard Webhooks spetsifikatsiooni:

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

Edastuse kontrollimiseks:

1. Koosta string `{webhook-id}.{webhook-timestamp}.{raw body}` täpselt vastu
   võetud baitidest enne JSON-i parsimist.
2. Arvuta selle põhjal tellimuse saladusega HMAC-SHA256 ja kodeeri tulemus
   base64-vormingus.
3. Võrdle konstantse ajaga väärtust iga päise `v1,` väärtusega väljas
   `webhook-signature`. Saladuse vahetamise ajal võib neid olla kaks; sobib
   kumbki vaste.
4. Lükka tagasi ajatempel, mis erineb sinu kellaajast üle viie minuti.

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

Väldi kordusi `webhook-id` järgi: edastus võib saabuda mitu korda. Sisu sisaldab
tunnuseid ja lühikest kokkuvõtet; praeguse oleku hankimiseks päringu ressurssi.
Nurjunud edastusi proovitakse tagavaravahedega uuesti kuni 72 tundi; edastuslogist
saab need ka uuesti käivitada.

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

Quire'i MCP-server asub organisatsiooni aadressil `/mcp` ja kasutab
voogedastatavat HTTP-d. MCP-klient leiab OAuth-serveri aadressilt
`/.well-known/oauth-protected-resource`; inimene logib sisse ja annab nõusoleku
nagu iga OAuthi kliendi puhul. Tööriistad tegutsevad selle inimese õigustes ning
hävitatavad toimingud küsivad kinnitust. Haldurid valivad saadaval tööriistad
aadressil `/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>

## Paketid ja API <!--quire:plans-and-the-api-->

API õiguse juurde kuuluvad API võtmed, OAuthi kliendid, veebikonksud ja
MCP-server; see sisaldub igas tavapaketis. Paketis, mis seda ei sisalda,
keeldutakse võtme, kliendi või tellimuse loomisest, REST-i kirjutuspäringutest ja
MCP-ühendustest, kuid REST-i lugemispäringud töötavad edasi, et andmeid saaks
eksportida. Keeld tagastatakse probleemidokumendina koodiga
`commerce.plan_entitlement`, kategoorias `precondition`.

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

Quire'i enda tegevustüübid, plokid, registreerimis- ja sisselogimisviisid,
küsimusetüübid, aruanded, kujundused ning integratsioonid deklareeritakse sama
laienduste registri kaudu, mida saab ise majutatud paigaldusele täiendada.
Laiendused kompileeritakse rakendusse: käitusajal pluginate laadijat pole ning
majutatud organisatsioon ei saa ise laiendust lisada. Haldurid lülitavad laiendusi
oma organisatsioonis sisse ja välja aadressil `/admin/extensions` (vt
[halduri juhendit](/et/admin/extensions/)).

Laienduse kirjutamiseks alusta näidisplokist ja kujundusest failis
`packages/integration/extensions/src/sample.ts`. Vali laienduspunkt ja loe selle
lepingut failist `points.ts`, seejärel deklareeri laiendus tunnuse, versiooni,
litsentsi, pakutava ja vajaliku ning organisatsioonipoolse väljalülitamise
lubatavusega. Registreeri see kohas, kus koostatakse veebirakendus ja
töötlusteenus, et mõlemad kasutaksid sama seadistust. Register kontrollib
ehitamisel ja iga `register`-kutse puhul laienduspunkti reegleid, keeldub kõigist
kehtetutest kogumitest ning nimetab kõik probleemid; ebaõnnestumisel jääb register
muutmata. Laienduse enda testid peaksid kinnitama, et selle
`extensionContractProblems` on tühi ning väljalülitamine muudab vastavat
funktsionaalsust.

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