Vadovas programuotojui

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 išvardija kiekvieną tašką ir įvykį.

Adresai

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

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.

Užklausos

• 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

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:

Kreipdamiesi į palaikymo tarnybą cituokite request_id.

Webhook’ai

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

Planai ir 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

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

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.