---
title: "Vadovas programuotojui"
description: "Quire REST API, OAuth, „webhooks“, MCP serveris ir plėtiniai."
image: "https://docs.quirelms.com/og.png"
---

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

# Vadovas programuotojui

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

Naudokite savo organizacijos API adresą ir apimtimi apribotą prisijungimo
duomenį. Pradėkite nuo užklausos, kuri tik skaito, patikrinkite atsakymą ir
laikykite paslėptus duomenis už kodo kontrolės bei dokumentacijos pavyzdžių.

Quire turi vieną viešą API: REST per HTTPS, aprašytą „OpenAPI“ 3.1 dokumentu,
su pasirašytais „webhook“ įvykiams ir MCP serveriu dirbtinio intelekto
asistentams. [API dokumentacija](https://docs.quirelms.com/api/) išvardija kiekvieną tašką ir
įvykį.

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

Kiekviena organizacija turi savo adresą, ir API gyvena po juo:

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

Prisijungimo duomenys nulemia organizaciją. Vienai organizacijai skirtas
raktas, panaudotas kitos adresu, atmetamas.

„OpenAPI“ dokumentas pateikiamas adresu `/api/v1/openapi.json` bet kurios
organizacijos adresu, todėl klientų generatoriai visada mato tą versiją,
kurios kviečiate.

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

**API raktai** skirti skriptams ir serverio bei serverio integracijoms.
Administratorius vieną jų sukuria adresu `/admin/integrations/api-keys`,
pasirenka jo apimtis ir mato tik kartą. Siųskite jį kaip nešėjo žetoną:

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

Raktai prasideda `qk_live_` arba `qk_test_`. Kiekvienai integracijai duokite
savo raktą.

**OAuth 2.1** skirtas programoms, kurios veikia prisijungusio žmogaus vardu.
Registruokite klientą adresu `/admin/integrations/oauth-clients`, tada
naudokite leidimo kodo srautą su PKCE (`/oauth/authorize`, `/oauth/token`)
arba kliento registracijos duomenis mašininiam klientui. Atradimo adresas yra
`/.well-known/oauth-authorization-server`. Apimtis susiaurina, ką žetonas
gali daryti; ji niekada neleidžia jam daugiau, nei galėtų žmogus.

Apimtys yra `resource:read`, `resource:write` ir `resource:delete`, pavyzdžiui
`courses:read` arba `enrolments:write`. Keturioms taikoma privilegija ir
sutikimo ekrane jos rodomos su įspėjimu: `audit:read`, `roles:write`,
`tenants:write` ir `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>

## Užklausos <!--quire:requests-->

- **Puslapiavimas**: kiekvienas sąrašas puslapiuojamas žymekliais. Perduokite
  `limit`, tada `next_cursor` iš `page` kaip `cursor`, kol `has_more`
  yra tiesa (pavyzdžiai žemiau). Nukrypimo (offset) nėra.
- **Pakeitimai nuo**: `updated_since` grąžina tai, kas pasikeitė po tam
  tikro laiko. Sujunkite jį su `include_deleted=true` arba skaitykite
  `/<resource>/deletions`, sužinoti, kas buvo pašalinta.
- **Išoriniai identifikatoriai**: dauguma išteklių priima jūsų paties
  `external_id`, o `/<resource>/ext:{external_id}` skaito arba įrašo pagal
  jį, todėl sinchronizacijai niekada nereikia saugoti Quire identifikatorių.
- **Idempotentumas**: siųskite antraštę `Idempotency-Key` su `POST`, `PATCH`
  ir `DELETE`. Pakartotinė užklausa su tuo pačiu raktu grąžina pirmąjį
  atsakymą vietoj to, kad darbas būtų atliktas du kartus. Masinėms užklausoms
  ji privaloma.
- **Versijos**: pagrindinė versija yra kelyje (`/v1`). Joje kiekvienas
  nesuderinamas pakeitimas yra datuota revisija, pasirenkama antrašte
  `Quire-Version`, pavyzdžiui `Quire-Version: 2026-09-20`. Be antraštės
  gaunate tą revisiją, kuri galiojo, kai buvo išduoti jūsų prisijungimo
  duomenys.

Sąrašo puslapis:

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

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

Kiekviena klaida yra RFC 9457 problema:

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

Sąlygas tikrinkite pagal `code`, jis yra pastovus; `detail` rašoma žmonėms,
jį galima rodyti ir jis gali keistis. Kai kodo nepažįstate, grupuokite pagal
`category`:

| Kategorija | Statusas | Bandyti dar kartą |
| --- | --- | --- |
| `validation` | 422, su laukų detalėmis `errors` | Ne |
| `authentication` | 401 | Ne |
| `authorization` | 403 | Ne |
| `not_found` | 404 | Ne |
| `conflict` | 409 | Kartais |
| `precondition` | 412 | Ne |
| `quota` | 402 plano atveju, 413 dydžio atveju | Ne |
| `rate_limit` | 429, su `Retry-After` | Taip |
| `upstream` | 502 arba 504 | Taip |
| `internal` | 500 | Taip |

Kreipdamiesi į palaikymo tarnybą cituokite `request_id`.

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

Prenumeruokite adresu `/admin/webhooks` arba per API adresu
`/webhook_subscriptions`. Pasirinkite įvykius pagal pavadinimą
(`enrolment.created`), pagal sritį (`enrolment.*`) arba visus (`*`). Quire
pirma išsiunčia `webhook.ping`; prenumerata pradedama, kai jūsų taškas į jį
atsako.

Pristatymai atitinka „Standard Webhooks“ specifikaciją:

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

Kad patikrintumėte pristatymą:

1. Sudarykite eilutę `{webhook-id}.{webhook-timestamp}.{raw body}` iš
   tiksliai gautų baitų, dar prieš bet kokį JSON analizavimą.
2. Apskaičiuokite jam HMAC-SHA256 su savo prenumeratos paslaptimi ir
   konvertuokite į base64.
3. Palyginkite nuolatiniu laiku su kiekviena `v1,` reikšme laukelyje
   `webhook-signature`. Paslapties keitimo metu jų gali būti dvi; tinka
   atitikusi bet kuri.
4. Atmeskite laiko žymą, nuo jūsų laikrodžio skiriančią daugiau nei penkias
   minutes.

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

Dublikatus šalinkite pagal `webhook-id`: pristymas gali ateiti daugiau nei
kartą. Kūne yra identifikatoriai ir trumpa suvestina; dabartinę būseną
pasiimkite iš paties išteklio. Nepavykę pristatymai kartojami su atgaliniu
delsimu iki 72 valandų ir gali būti pakartoti iš pristatymo žurnalo.

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

Quire MCP serveris yra adresu `/mcp` organizacijos adresu per srautinį HTTP.
MCP klientas atranda OAuth serverį iš
`/.well-known/oauth-protected-resource`, o žmogus prisijungia ir sutinka taip
pat kaip ir su bet kokiu OAuth klientu. Įrankiai veikia to žmogaus vardu su
jo leidimais, o naikinimo įrankiai prašo patvirtinimo. Administratoriai
pasirenka, kurie įrankiai prieinami, adresu `/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>

## Planai ir API <!--quire:plans-and-the-api-->

API raktai, OAuth klientai, „webhook“ prenumeratos ir MCP serveris priklauso
plano API teisei, ir ją turi kiekvienas standartinis planas. Plane be jos
rakto, kliento ar prenumeratos kurti neleidžiama, REST įrašymai ir MCP
ryšiai atmetami, o REST skaitymas ir toliau veikia, kad duomenys liktų
išeksportuojami. Atmetimas yra problema su kodu `commerce.plan_entitlement`,
kategorijoje `precondition`.

## Plėtiniai <!--quire:extensions-->

Pačios Quire veiklos tipai, blokai, įtraukimo būdai, prisijungimo būdai,
klausimų tipai, ataskaitos, temos ir integracijos yra deklaruojami per tą
patį plėtinių registrą, kurį gali papildyti ir savo prieglobos turimas
diegimas. Plėtiniai kompiliuojami iš anksto: vykdymo metu įskiepių įkėlio nėra,
o prieglobyje esanti organizacija jo pridėti negali. Administratoriai kiekvieną
plėtinį savo organizacijai įjungia arba išjungia adresu `/admin/extensions`
(žr. [vadovą administratoriui](/lt/admin/extensions/)).

Kad jį parašytumėte, pradėkite nuo pavyzdinio bloko ir temos faile
`packages/integration/extensions/src/sample.ts`. Pasirinkite plėtinio tašką ir
perskaitykite jo sutartį faile `points.ts`, tada deklaruokite plėtinį su
identifikatoriumi, versija, licencija, tuo, ką jis teikia ir ko reikalauja, ir
ar organizacija gali jį išjungti. Registruokite ten, kur jungiama žiniatinklio
programa ir darbininkas, kad abu sutartų. Registras tikrina kiekvieno taško
svojas taisykles statydamas ir kiekvieną kartą, kai kviečiate `register`,
atmeta rinkinį, kuris būtų netinkamas, suvardindamas kiekvieną problemą, ir
tokiais atvejais registro nekeičia. Paties plėtinio testai turėtų tikrinti, kad
`extensionContractProblems` jam tuščias, ir kad jo išjungimas pakeičia tai,
ką jis veikia.

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