Phau ntawv qhia tsim kho

Siv chaw nyob API ntawm koj lub koom haum thiab ntaub ntawv nkag uas muaj scope tsim nyog. Pib thov nyeem, xyuas lus teb, thiab khaws cov lus zais kom deb ntawm source control thiab cov piv txwv hauv ntaub ntawv qhia.

Quire muaj ib lub API pej xeem: REST hla HTTPS, piav los ntawm OpenAPI 3.1 document; muaj webhook kos npe rau xwm txheej thiab MCP server rau AI assistant. API reference teev txhua endpoint thiab xwm txheej.

Chaw nyob

Txhua lub koom haum muaj nws tus kheej chaw nyob, thiab API nyob hauv qab qhov chaw ntawd:

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

Cov ntaub ntawv nkag txiav txim lub koom haum. Yog siv key ntawm ib lub koom haum rau chaw nyob ntawm lwm lub, yuav raug tsis kam.

OpenAPI document qhib ntawm /api/v1/openapi.json ntawm chaw nyob koom haum twg los tau, kom cov cuab yeej tsim client pom version uas koj tab tom hu.

Kev txheeb xyuas tus neeg

API key siv rau script thiab kev txuas server-rau-server. Tus thawj coj tsim ntawm /admin/integrations/api-keys, xaiv cov scope, thiab pom key ib zaug xwb. Xa nws ua bearer token:

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

Key pib nrog qk_live_ lossis qk_test_. Muab nws tus kheej key rau txhua qhov kev txuas.

OAuth 2.1 yog rau app uas ua haujlwm sawv cev rau tus neeg nkag lawm. Tso npe client ntawm /admin/integrations/oauth-clients, ces siv authorization code flow nrog PKCE (/oauth/authorize, /oauth/token), lossis client credentials rau tshuab client. Nrhiav discovery ntawm /.well-known/oauth-authorization-server. Scope txo tau yam uas token ua tau; nws yeej tsis tso cai ua ntau dua tus neeg ntawd.

Scope yog resource:read, resource:write thiab resource:delete, piv txwv courses:read lossis enrolments:write. Plaub scope muaj cai siab thiab qhia lus ceeb toom ntawm nplooj pom zoo: audit:read, roles:write, tenants:write thiab users:delete.

Kev thov

• Nplooj ntawv: txhua daim npe muab faib ua nplooj siv cursor. Xa limit, ces muab next_cursor ntawm page ua cursor thaum has_more tseem yog true (piv txwv hauv qab). Tsis muaj offset.
• Hloov txij lub sijhawm: updated_since rov qhia yam hloov tom qab lub sijhawm. Siv ua ke nrog include_deleted=true, lossis nyeem /<resource>/deletions, kom paub yam raug rho tawm.
• Cim qhia sab nraud: feem ntau resource txais koj tus kheej external_id, thiab /<resource>/ext:{external_id} nyeem lossis tsim kho raws tus cim ntawd, kom sync tsis tas khaws Quire tus ID.
• Ua ib zaug xwb: xa Idempotency-Key header rau POST, PATCH thiab DELETE. Rov thov nrog tib key yuav rov muab thawj qhov lus teb es tsis ua haujlwm dua. Endpoint ntau yam yuav tsum muaj.
• Version: version loj nyob hauv path (/v1). Hauv version ntawd, txhua qhov hloov rhuav kev sib raug yog revision muaj hnub, xaiv nrog Quire-Version header, piv txwv Quire-Version: 2026-09-20. Tsis muaj header ces txais revision tam sim no thaum muab ntaub ntawv nkag.

Ib nplooj ntawm daim npe:

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

Yuam kev

Txhua qhov yuam kev yog RFC 9457 problem document:

{"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..."}

Txiav txim raws code, uas ruaj; detail sau rau neeg nyeem, qhia tau rau tus siv, thiab hloov tau. Yog tsis paub ib code, faib raws category:

Thaum tiv tauj kev pab, qhia request_id.

Webhook

Sau npe ntawm /admin/webhooks, lossis siv API ntawm /webhook_subscriptions. Xaiv xwm txheej raws npe (enrolment.created), pawg (enrolment.*) lossis txhua yam (*). Quire xub xa webhook.ping; subscription pib thaum koj endpoint teb nws.

Kev xa ua raws Standard Webhooks specification:

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

Xyuas kev xa:

1. Tsim cov ntawv {webhook-id}.{webhook-timestamp}.{raw body} ntawm cov byte uas tau txais kiag, ua ntej parse JSON.
2. Xam HMAC-SHA256 rau nws nrog secret ntawm subscription, ces base64.
3. Piv nrog txhua tus nqi v1, hauv webhook-signature siv constant time. Thaum hloov secret, muaj tau ob qho; phim ib qho twg yeej siv tau.
4. Tsis txais timestamp uas txawv koj lub moos tshaj tsib feeb.

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

Tsis txhob ua dua raws webhook-id: tej zaum ib qho kev xa yuav tuaj ntau zaug. Lub cev muaj ID thiab ntsiab lus luv; thov resource kom tau xwm txheej tam sim no. Kev xa tsis tiav rov sim nrog kev ncua zuj zus ntev txog 72 teev, thiab xa dua tau ntawm daim ntawv teev kev xa.

MCP

MCP server ntawm Quire nyob ntawm /mcp ntawm chaw nyob koom haum, siv streamable HTTP. MCP client nrhiav OAuth server ntawm /.well-known/oauth-protected-resource, ces tus neeg nkag thiab pom zoo ib yam li OAuth client. Cov cuab yeej ua haujlwm raws tus neeg ntawd thiab nws cov kev tso cai; cov cuab yeej rhuav tshem nug kom lees paub. Tus thawj coj xaiv cov cuab yeej muaj ntawm /admin/integrations/mcp.

Phiaj xwm thiab API

API key, OAuth client, webhook thiab MCP server yog ib feem ntawm entitlement API hauv phiaj xwm; txhua phiaj xwm qauv muaj qhov ntawd. Yog phiaj xwm tsis muaj, tsim key, client lossis subscription raug tsis kam, REST kev sau thiab kev txuas MCP raug tsis kam, tiam sis REST kev nyeem tseem ua haujlwm kom export tau ntaub ntawv. Qhov tsis kam yog problem document muaj code commerce.plan_entitlement, hauv pawg precondition.

Extensions

Hom haujlwm, blocks, txoj kev tso npe, txoj kev nkag, hom lus nug, ntaub ntawv qhia, themes thiab kev txuas ntxiv ntawm Quire tau tshaj tawm los ntawm tib extension registry uas qhov kev nruab self-hosted ntxiv tau. Extensions muab compile nrog app: tsis muaj runtime plugin loader, thiab lub koom haum hosting tsis ntxiv tau. Tus thawj coj qhib lossis kaw extension rau nws lub koom haum ntawm /admin/extensions (saib phau ntawv thawj coj).

Yuav sau ib qho, pib ntawm sample block thiab theme hauv packages/integration/extensions/src/sample.ts. Xaiv extension point thiab nyeem daim cog lus hauv points.ts, ces tshaj tawm extension nrog ID, version, licence, yam uas nws muab thiab xav tau, thiab seb lub koom haum kaw tau los tsis tau. Tso npe rau qhov chaw uas web application thiab worker muab sib dhos, kom ob sab pom zoo ib yam. Registry xyuas txhua point cov cai thaum tsim thiab txhua zaus hu register, tsis txais ib pawg uas siv tsis tau thiab qhia txhua qhov teeb meem, ces cia registry nyob qub. Kev xeem rau extension yuav tsum xyuas tias extensionContractProblems tsis muaj teeb meem rau nws thiab tias tua extension hloov yam uas nws cuam tshuam.