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

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 uvádí všechny endpointy a události.

Adresy

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í

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.

Požadavky

• 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

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:

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

Webhooky

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

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.

Tarify a 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í

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).

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.