Ceļvedis izstrādātājiem

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 uzskaita katru gala punktu un notikumu.

Adreses

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

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.

Pieprasījumi

• 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

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:

Sazinoties ar atbalstu, citējiet request_id.

Tīmekļa āķi

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

Plāni un 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 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).

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