---
title: "Příručka pro vývojáře"
description: "REST API Quire, OAuth, webhooky, server MCP a rozšíření."
image: "https://docs.quirelms.com/og.png"
---

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

# Příručka pro vývojáře

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

Používejte adresu API své organizace a přihlašovací údaj s omezeným rozsahem oprávnění. Začněte požadavkem pouze pro čtení, zkontrolujte odpověď a tajné údaje nikdy nevkládejte do zdrojového kódu ani do příkladů v dokumentaci.

Quire má jedno veřejné API: REST přes HTTPS popsané dokumentem OpenAPI 3.1, podepsané webhooky pro události a server MCP pro asistenty AI. [Referenční dokumentace API](https://docs.quirelms.com/api/) uvádí všechny endpointy a události.

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

Každá organizace má vlastní adresu a její API je dostupné pod ní:

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

Organizaci určuje přihlašovací údaj. Použití klíče jedné organizace na adrese jiné organizace se odmítne.

Dokument OpenAPI je dostupný na `/api/v1/openapi.json` na adrese kterékoli organizace, takže generátory klienta vždy uvidí verzi, se kterou komunikujete.

## Ověřování <!--quire:authentication-->

**Klíče API** jsou určeny pro skripty a integrace mezi servery. Administrátor vytvoří klíč na `/admin/integrations/api-keys`, zvolí jeho rozsahy a zobrazí se mu pouze jednou. Odešlete ho jako bearer token:

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

Klíče začínají na `qk_live_` nebo `qk_test_`. Každé integraci přidělte vlastní klíč.

**OAuth 2.1** je určen aplikacím, které jednají jako přihlášený uživatel. Zaregistrujte klienta na `/admin/integrations/oauth-clients` a použijte autorizační tok s kódem a PKCE (`/oauth/authorize`, `/oauth/token`), případně přihlašovací údaje klienta pro strojového klienta. Metadata pro zjištění serveru jsou na `/.well-known/oauth-authorization-server`. Rozsah omezuje, co token může dělat; nikdy mu nedává větší oprávnění, než má daný uživatel.

Rozsahy jsou `resource:read`, `resource:write` a `resource:delete`, například `courses:read` nebo `enrolments:write`. Čtyři jsou privilegované a na obrazovce souhlasu se zobrazují s upozorněním: `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>

## Požadavky <!--quire:requests-->

- **Stránkování**: každý seznam se stránkuje pomocí kurzoru. Předejte `limit` a potom `next_cursor` z `page` jako `cursor`, dokud je `has_more` rovno true (viz příklad níže). Offset se nepoužívá.
- **Změny od určitého okamžiku**: `updated_since` vrátí změny provedené po zadaném čase. Spojte ho s `include_deleted=true` nebo načtěte `/<resource>/deletions`, abyste zjistili, co bylo odstraněno.
- **Externí identifikátory**: většina prostředků přijímá vlastní `external_id`; přes `/<resource>/ext:{external_id}` lze prostředek načíst nebo vložit či aktualizovat podle tohoto identifikátoru. Synchronizace tak nemusí uchovávat identifikátory Quire.
- **Idempotence**: s požadavky posílejte hlavičku `Idempotency-Key` v metodách `POST`, `PATCH` a `DELETE`. Opakovaný požadavek se stejným klíčem vrátí první odpověď místo opakování operace. Hromadné endpointy tento klíč vyžadují.
- **Verze**: hlavní verze je v cestě (`/v1`). Každá zpětně nekompatibilní změna uvnitř verze je datovaná revize zvolená hlavičkou `Quire-Version`, například `Quire-Version: 2026-09-20`. Bez hlavičky získáte revizi platnou v době vydání přihlašovacího údaje.

Jedna stránka seznamu:

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

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

Každá chyba je problémový dokument podle 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..."}
```

Rozhodujte se podle stabilního `code`; `detail` je určen lidem, je bezpečné ho zobrazit a může se měnit. Pokud kód neznáte, zařaďte chybu podle `category`:

| Kategorie | Stav | Opakovat |
| --- | --- | --- |
| `validation` | 422, podrobnosti o poli v `errors` | Ne |
| `authentication` | 401 | Ne |
| `authorization` | 403 | Ne |
| `not_found` | 404 | Ne |
| `conflict` | 409 | Někdy |
| `precondition` | 412 | Ne |
| `quota` | 402 pro tarif, 413 pro velikost | Ne |
| `rate_limit` | 429, s hlavičkou `Retry-After` | Ano |
| `upstream` | 502 nebo 504 | Ano |
| `internal` | 500 | Ano |

Při kontaktování podpory uveďte `request_id`.

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

Přihlaste se k odběru na `/admin/webhooks` nebo přes API na `/webhook_subscriptions`. Události vybírejte podle názvu (`enrolment.created`), oblasti (`enrolment.*`) nebo všechny (`*`). Quire nejprve odešle `webhook.ping`; odběr začne po odpovědi vašeho endpointu.

Doručování se řídí specifikací Standard Webhooks:

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

Ověření doručení:

1. Z přesně přijatých bajtů sestavte řetězec `{webhook-id}.{webhook-timestamp}.{raw body}` ještě před parsováním JSON.
2. Pomocí tajného klíče předplatného vypočítejte HMAC-SHA256 a zakódujte ho jako base64.
3. V konstantním čase porovnejte výsledek s každou hodnotou `v1,` v `webhook-signature`. Při obměně tajného klíče mohou být dvě; platná je shoda s kteroukoli z nich.
4. Odmítněte časové razítko vzdálené od vašich hodin o více než pět minut.

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

Zamezte duplicitám podle `webhook-id`: jedno doručení může přijít vícekrát. Tělo obsahuje identifikátory a stručné shrnutí; aktuální stav načtěte z prostředku. Neúspěšná doručení se s postupně delšími prodlevami opakují až 72 hodin a lze je znovu přehrát z protokolu doručení.

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

Server MCP Quire je na `/mcp` na adrese organizace a používá streamovatelný protokol HTTP. Klient MCP zjistí server OAuth z `/.well-known/oauth-protected-resource`; uživatel se přihlásí a udělí souhlas stejně jako kterémukoli klientovi OAuth. Nástroje jednají s oprávněními daného uživatele a před destruktivní operací vyžadují potvrzení. Administrátoři určují dostupné nástroje na `/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>

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

Klíče API, klienti OAuth, webhooky a server MCP patří mezi oprávnění API v tarifu a obsahuje je každý standardní tarif. Tarif bez tohoto oprávnění nedovolí vytvářet klíče, klienty ani předplatná, odmítne zápisy REST a připojení MCP, ale ponechá čtení REST, aby bylo možné data exportovat. Odmítnutí je problémový dokument s kódem `commerce.plan_entitlement` a kategorií `precondition`.

## Rozšíření <!--quire:extensions-->

Typy aktivit, bloky, metody zápisu a přihlašování, typy otázek, reporty, motivy i integrace Quire se deklarují ve stejném registru rozšíření, do kterého může přidávat rozšíření self-hosted instalace. Rozšíření se kompilují do aplikace: za běhu se nenačítají žádné pluginy a hostovaná organizace je nemůže přidat. Administrátoři mohou pro svou organizaci jednotlivá rozšíření zapínat nebo vypínat na `/admin/extensions` (viz [příručka pro administrátory](/cs/admin/extensions/)).

Chcete-li rozšíření vytvořit, začněte ukázkovým blokem a motivem v `packages/integration/extensions/src/sample.ts`. Vyberte rozšiřující bod, přečtěte si jeho smlouvu v `points.ts` a deklarujte rozšíření s ID, verzí, licencí, tím, co poskytuje a vyžaduje, a informací, zda ho organizace může vypnout. Zaregistrujte ho v místě, kde se skládá webová aplikace a worker, aby se shodovaly. Registr při sestavení i při každém volání `register` kontroluje pravidla daného bodu. Neplatnou sadu odmítne, vypíše všechny problémy a stav registru nezmění. Vlastní testy rozšíření mají ověřit, že `extensionContractProblems` pro něj nic nevrací a že jeho vypnutí změní to, co rozšíření ovlivňuje.

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