Vodič za programere

Koristite API adresu svoje organizacije i pristupni podatak s ograničenim opsegom. Počnite zahtjevom za čitanje, provjerite odgovor i čuvajte tajne izvan kontrole verzija i primjera u dokumentaciji.

Quire ima jedan javni API: REST preko HTTPS-a, opisan OpenAPI 3.1 dokumentom, s potpisanim webhookovima za događaje i MCP serverom za AI asistente. API priručnik navodi sve krajnje tačke i događaje.

Adrese

Svaka organizacija ima vlastitu adresu, a API se nalazi ispod nje:

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

Pristupni podatak određuje organizaciju. Ključ jedne organizacije odbija se na adresi druge.

OpenAPI dokument dostupan je na /api/v1/openapi.json na adresi svake organizacije, tako da generatori klijenata uvijek dobijaju verziju kojoj pristupate.

Autentifikacija

API ključevi služe skriptama i integracijama server-server. Administrator kreira ključ na /admin/integrations/api-keys, odabere njegove opsege i vidi ga samo jednom. Šaljite ga kao bearer token:

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

Ključevi počinju s qk_live_ ili qk_test_. Svakoj integraciji dodijelite vlastiti ključ.

OAuth 2.1 namijenjen je aplikacijama koje djeluju u ime prijavljene osobe. Registrujte klijenta na /admin/integrations/oauth-clients, pa koristite tok autorizacijskog koda s PKCE-om (/oauth/authorize, /oauth/token) ili vjerodajnice klijenta za mašinski klijent. Otkriće je dostupno na /.well-known/oauth-authorization-server. Opseg sužava radnje tokena; nikada mu ne daje veća prava od same osobe.

Opsezi su resource:read, resource:write i resource:delete, npr. courses:read ili enrolments:write. Četiri su privilegovana i prikazuju se uz upozorenje na ekranu saglasnosti: audit:read, roles:write, tenants:write i users:delete.

Zahtjevi

• Straničenje: svaki spisak stranica koristi kursor. Pošaljite limit, pa vrijednost next_cursor iz page proslijedite kao cursor dok je has_more true (primjer u nastavku). Pomak (offset) ne postoji.
• Promjene od datuma: updated_since vraća izmjene nastale poslije određenog vremena. Uparite ga s include_deleted=true ili pročitajte /<resource>/deletions da biste saznali šta je uklonjeno.
• Vanjski identifikatori: većina resursa prihvata vaš external_id, a /<resource>/ext:{external_id} dohvaća ili upisuje resurs prema njemu, tako da sinhronizacija ne mora čuvati Quire identifikatore.
• Idempotentnost: zaglavlje Idempotency-Key šaljite uz POST, PATCH i DELETE. Ponovljeni zahtjev s istim ključem vraća prvi odgovor umjesto da radnju izvrši drugi put. Grupne krajnje tačke zahtijevaju ključ.
• Verzije: glavna verzija je u putanji (/v1). Unutar nje svaka nekompatibilna promjena ima reviziju s datumom, izabranu zaglavljem Quire-Version, npr. Quire-Version: 2026-09-20. Bez zaglavlja koristi se revizija važeća kada je pristupni podatak izdat.

Stranica rezultata liste:

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

Greške

Svaka greška je RFC 9457 dokument 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..."}

Provjeravajte stabilni code; detail je namijenjen korisnicima, sigurno ga je prikazati i može se mijenjati. Ako ne prepoznajete kod, grupišite prema category:

Kada se obraćate podršci, navedite request_id.

Webhookovi

Pretplatite se na /admin/webhooks ili putem API-ja na /webhook_subscriptions. Izaberite događaje po nazivu (enrolment.created), području (enrolment.*) ili sve (*). Quire prvo šalje webhook.ping; pretplata počinje kada joj vaša krajnja tačka odgovori.

Isporuke slijede specifikaciju Standard Webhooks:

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

Za provjeru isporuke:

1. Sastavite niz {webhook-id}.{webhook-timestamp}.{raw body} iz tačno primljenih bajtova, prije parsiranja JSON-a.
2. Izračunajte HMAC-SHA256 nad njim koristeći tajnu pretplate, a rezultat kodirajte u base64.
3. Poredi se sa svakom vrijednošću v1, u webhook-signature u konstantnom vremenu. Tokom rotacije tajne mogu postojati dvije; dovoljno je da se podudara jedna.
4. Odbacite vremensku oznaku koja odstupa više od pet minuta od vašeg sata.

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

Uklonite duplikate prema webhook-id: isporuka može stići više puta. Tijelo nosi identifikatore i kratak sažetak; dohvatite resurs da biste dobili njegovo trenutno stanje. Neuspjele isporuke ponavljaju se uz rastuće pauze do 72 sata, a mogu se ponovo poslati iz evidencije isporuka.

MCP

Quire MCP server nalazi se na /mcp na adresi organizacije i koristi streamable HTTP. MCP klijent otkriva OAuth server putem /.well-known/oauth-protected-resource, a korisnik se prijavljuje i daje saglasnost kao za bilo kojeg OAuth klijenta. Alati djeluju u njegovo ime, s njegovim dozvolama; destruktivni alati traže potvrdu. Administratori biraju dostupne alate na /admin/integrations/mcp.

Planovi i API

API ključevi, OAuth klijenti, webhookovi i MCP server pripadaju API pravu plana, koje uključuje svaki standardni plan. Bez tog prava kreiranje ključa, klijenta ili pretplate se odbija; odbijaju se i REST zapisi i MCP veze, ali REST čitanja i dalje rade, tako da se podaci mogu izvesti. Odbijanje je dokument problema s kodom commerce.plan_entitlement u kategoriji precondition.

Proširenja

Quireove vrste aktivnosti, blokovi, metode upisa i prijave, vrste pitanja, izvještaji, teme i integracije definisani su u istom registru proširenja kojem može dodavati i vlastita instalacija. Proširenja su kompajlirana u aplikaciju: nema dinamičkog učitavanja dodataka tokom rada, a hostovana organizacija ne može dodati svoje. Administratori uključuju ili isključuju proširenja za organizaciju na /admin/extensions (pogledajte vodič za administratore).

Za izradu počnite od primjera bloka i teme u packages/integration/extensions/src/sample.ts. Odaberite tačku proširenja i pročitajte njen ugovor u points.ts, zatim definišite proširenje ID-jem, verzijom, licencom, onim što pruža i zahtijeva te informacijom može li ga organizacija isključiti. Registrujte ga na mjestu gdje se sastavljaju web aplikacija i worker kako bi bili usklađeni. Registar provjerava pravila svake tačke pri izgradnji i pri svakom pozivu register; odbija nevažeći skup, uz navođenje svih problema, a sam registar ostaje nepromijenjen. Testovi proširenja treba da potvrde da je extensionContractProblems za njega prazan i da njegovo isključivanje mijenja ono na šta utiče.