---
title: "Ceļvedis izstrādātājiem"
description: "Quire REST API, OAuth, tīmekļa āķi, MCP serveris un paplašinājumi."
image: "https://docs.quirelms.com/og.png"
---

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

# Ceļvedis izstrādātājiem

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

Izmantojiet savas organizācijas API adresi un pilnvarotu akreditācijas datu
kopumu. Sāciet ar lasījuma pieprasījumu, pārbaudiet atbildi un turiet noslēpumus
ārpus versiju kontroles un dokumentācijas piemēriem.

Quire ir viena publiska API: REST pāri HTTPS, ko apraksta OpenAPI 3.1 dokuments,
ar parakstītiem tīmekļa āķiem notikumiem un MCP serveri mākslīgā intelekta
palīgiem. [API atsauce](https://docs.quirelms.com/api/) uzskaita katru gala punktu un notikumu.

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

Katrai organizācijai ir sava adrese, un API atrodas zem tās:

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

Akreditācijas dati nosaka organizāciju. Atslēga, kas izveidota vienai
organizācijai un izmantota citas adresē, tiek noraidīta.

OpenAPI dokuments ir pieejams vietnē `/api/v1/openapi.json` jebkuras
organizācijas adresē, tāpēc klientu ģeneratori vienmēr redz versiju, kuru tu
izsauc.

## Autentifikācija <!--quire:authentication-->

**API atslēgas** ir paredzētas skriptiem un serveris-serverim integrācijām.
Administrators to izveido vietnē `/admin/integrations/api-keys`, izvēlas tās
pilnvaras un redz to vienu reizi. Nosūtiet to kā nesēja (bearer) žetonu:

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

Atslēgas sākas ar `qk_live_` vai `qk_test_`. Katrai integrācijai dodiet savu
atslēgu.

**OAuth 2.1** ir lietojumprogrammām, kas rīkojas pierakstījušās personas vārdā.
Reģistrējiet klientu vietnē `/admin/integrations/oauth-clients`, pēc tam
izmantojiet pilnvarošanas koda plūsmu ar PKCE (`/oauth/authorize`,
`/oauth/token`) vai klienta datus mašīnklientam. Atrast notiek vietnē
`/.well-known/oauth-authorization-server`. Pilnvara (scope) šauri nosaka, ko
žetons drīkst darīt; tā nekad neļauj darīt vairāk nekā persona pati.

Pilnvaras ir `resource:read`, `resource:write` un `resource:delete`, piemēram,
`courses:read` vai `enrolments:write`. Četas ir privilēģētas un piekrišanas
ekrānā parādītas ar brīdinājumu: `audit:read`, `roles:write`, `tenants:write`
un `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>

## Pieprasījumi <!--quire:requests-->

- **Lappušu maiņa**: katrs saraksts izmanto kursoru lappušu maiņu. Norādiet `limit`,
  pēc tam `next_cursor` no `page` kā `cursor`, kamēr `has_more` ir
  patiess (piemērs zemāk). Nobīdes (offset) nav.
- **Izmaiņas kopš**: `updated_since` atgriež to, kas mainījies pēc noteikta
  laika. Sasaistiet to ar `include_deleted=true` vai lasiet
  `/<resource>/deletions`, lai uzzinātu, kas tika izdzēsts.
- **Ārējie identifikatori**: vairākums resursu pieņem tavu paša `external_id`,
  un `/<resource>/ext:{external_id}` to lasa vai atjauno pēc tā, tāpēc
  sinhronizācijai nekad nav jāglabā Quire identifikatori.
- **Idempotence**: nosūtiet `Idempotency-Key` galveni pieprasījumos `POST`,
  `PATCH` un `DELETE`. Atkārtots mēģinājums ar to pašu atslēgu atgriež pirmo
  atbildi, nevis izdara darbu divreiz. Masveida gala punkti to pieprasa.
- **Versijas**: lielā versija ir ceļā (`/v1`). Tās ietvaros katra laužošā
  izmaiņa ir ar datumu datota revīzija, ko izvēlas ar `Quire-Version` galveni,
  piemēram, `Quire-Version: 2026-09-20`. Bez šīs galvenes saņemsi revīziju, kas
  bija spēkā, kad tavi akreditācijas dati tika izsniegti.

Saraksta lapa:

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

## Kļūdas <!--quire:errors-->

Katra kļūda ir RFC 9457 problēmu dokuments:

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

Lemiet pēc `code`, kas ir stabils; `detail` ir rakstīts cilvēkiem, to droši rādīt
un tas var mainīties. Ja koda nepazīstat, grupējiet pēc `category`:

| Kategorija | Statuss | Atkārtot |
| --- | --- | --- |
| `validation` | 422, ar lauka detaļām `errors` | Nē |
| `authentication` | 401 | Nē |
| `authorization` | 403 | Nē |
| `not_found` | 404 | Nē |
| `conflict` | 409 | Dažkārt |
| `precondition` | 412 | Nē |
| `quota` | 402 plānam, 413 izmēram | Nē |
| `rate_limit` | 429, ar `Retry-After` | Jā |
| `upstream` | 502 vai 504 | Jā |
| `internal` | 500 | Jā |

Sazinoties ar atbalstu, citējiet `request_id`.

## Tīmekļa āķi <!--quire:webhooks-->

Abonējiet vietnē `/admin/webhooks` vai caur API vietnē
`/webhook_subscriptions`. Izvēlieties notikumus pēc nosaukuma
(`enrolment.created`), pēc zonas (`enrolment.*`) vai visus (`*`). Quire vispirms
nosūta `webhook.ping`; abonements sākas, kad tavs gala punkts uz to atbild.

Piegādes seko Standard Webhooks specifikācijai:

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

Lai pārbaudītu piegādi:

1. Uzbūvējiet virkni `{webhook-id}.{webhook-timestamp}.{raw body}` no
   tieši saņemtajiem baitiem, pirms jebkādas JSON analīzes.
2. Aprēķiniet tam HMAC-SHA256 ar sava abonementa noslēpumu un pārveidojiet
   base64.
3. Salīdziniet konstantā laikā ar katru `v1,` vērtību `webhook-signature`.
   Noslēpuma mainīšanas laikā var būt divas; jebkura no tām der.
4. Noraidiet laikspiedolu, kas no tava pulksteņa atšķiras vairāk nekā piecas
   minūtes.

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

Noņemiet dublikātus pēc `webhook-id`: piegāde var atnākt vairāk nekā vienu
reizi. Ķermenī ir identifikatori un īss kopsavilkums; pašreizējo stāvokli
nolasiet no resursa. Neizdevušās piegādes tiek atkārtotas ar atkāpšanos līdz 72
stundām, un tās var atskaņot no piegādes žurnāla.

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

Quire MCP serveris atrodas vietnē `/mcp` organizācijas adresē, pār straumējamu
HTTP. MCP klients atrod OAuth serveri vietnē
`/.well-known/oauth-protected-resource`, un persona pierakstās un piekrīt tāpat
kā jebkuram OAuth klientam. Rīki rīkojas šīs personas vārdā ar viņas atļaujām, un
destruktīvi rīki prasa apstiprinājumu. Administratori izvēlas, kuri rīki ir
pieejami, vietnē `/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>

## Plāni un API <!--quire:plans-and-the-api-->

API atslēgas, OAuth klienti, tīmekļa āķi un MCP serveris pieder plāna API
tiesībām, un katrs standarta plāns to iekļauj. Plānā, kurā tās nav, atslēgas,
klienta vai abonementa izveide tiek noraidīta, REST ierakstīšana un
savienojumi ar MCP tiek noraidīti, bet REST lasīšana turpina darboties, lai dati
paliktu eksportējami. Noraidījums ir problēmu dokuments ar kodu
`commerce.plan_entitlement` kategorijā `precondition`.

## Paplašinājumi <!--quire:extensions-->

Quire paša nodarbību veidi, bloki, ierakstīšanās metodes, pierakstīšanās metodes,
jautājumu tipi, atskaites, tēmas un integrācijas tiek deklarētas caur to pašu
paplašinājumu reģistru, ko pašmitināta instalācija var papildināt.
Paplašinājumi ir iekompilēti: nav izpildlaika spraudņu ielādētāja, un
mitināta organizācija nevar tādu pievienot. Administratori katru paplašinājumu
savai organizācijai ieslēdz vai izslēdz vietnē `/admin/extensions` (skat.
[ceļvedi administratoriem](/lv/admin/extensions/)).

Lai uzrakstītu kādu, sāciet no parauga bloka un tēmas failā
`packages/integration/extensions/src/sample.ts`. Izvēlieties paplašinājuma punktu
un izlasiet tā līgumu failā `points.ts`, pēc tam deklarējiet paplašinājumu ar
identifikatoru, versiju, licenci, ko tas nodrošina un kam tas nepieciešams, un
to, vai organizācija to drīkst izslēgt. Reģistrējiet to vietnē, kur tiek
sastādīta tīmekļa lietotne un darbinīk (worker), lai abi piekrīt. Reģistrs
pārbauda katra punkta paša noteikumus, kad tas tiek būvēts, un katru reizi, kad
izsaucat `register`, noraida kopumu, kas būtu nederīgs, nosaucot katru problēmu,
un šajā gadījumā reģistru atstāj nemainītu. Paša paplašinājuma testiem jāapstiprina,
ka tā `extensionContractProblems` ir tukšs un ka tā izslēgšana maina to, ko tas
ietekmē.

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