Jagorar mai haɓakawa

Yi amfani da adireshin API na ƙungiyarka da shaidar shiga mai iyakantaccen izini. Fara da buƙatar karatu, duba amsar, kuma adana sirrika a wajen sarrafa tushen lamba da misalan takardun bayani.

Quire yana da API na jama’a guda ɗaya: REST a kan HTTPS, an bayyana shi ta takardar OpenAPI 3.1, tare da webhooks masu sa hannu ga abubuwan da suka faru da uwar garken MCP ga mataimakan AI. Jagorar API tana lissafa kowace hanyar API da taron.

Adiresoshi

Kowace ƙungiya tana da nata adireshin, API kuma yana ƙarƙashinsa:

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

Shaidar shiga ce ke zaɓar ƙungiya. Ana ƙin maɓallin wata ƙungiya idan an yi amfani da shi a adireshin wata.

Ana samar da takardar OpenAPI a /api/v1/openapi.json a adireshin kowace ƙungiya, don haka janareta na abokan ciniki kullum suna ganin sigar da kake kira.

Tabbatar da shiga

Maɓallan API na rubutun kwamfuta da haɗin kai tsakanin uwar garke da uwar garke ne. Mai gudanarwa yana ƙirƙira ɗaya a /admin/integrations/api-keys, ya zaɓi izini, sannan ya gan shi sau ɗaya. Aika shi a matsayin alamar bearer:

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

Maɓallai suna farawa da qk_live_ ko qk_test_. Ka ba kowane haɗin kai nasa maɓalli.

OAuth 2.1 na manhajojin da ke aiki a matsayin mutumin da ya shiga ne. Yi rajistar abokin aiki a /admin/integrations/oauth-clients, sannan amfani da hanyar lambar izini tare da PKCE (/oauth/authorize, /oauth/token), ko shaidar abokin ga manhajar kwamfuta. Ana gano sabar a /.well-known/oauth-authorization-server. Izini yana rage abin da alama za ta iya yi; ba zai taɓa ba ta ikon da mutumin da kansa ba shi da ba.

Izini su ne resource:read, resource:write da resource:delete, misali courses:read ko enrolments:write. Hudu suna da gata kuma ana nuna gargaɗi a shafin amincewa: audit:read, roles:write, tenants:write da users:delete.

Buƙatu

• Shafuka: ana raba dukkan jerin bayanai zuwa shafuka da cursor. Aika limit, sannan next_cursor daga page a matsayin cursor muddin has_more gaskiya ne (misali a ƙasa). Babu offset.
• Canje-canje tun daga: updated_since yana dawo da abin da ya canza bayan wani lokaci. Haɗa shi da include_deleted=true, ko karanta /<resource>/deletions, domin sanin abin da aka cire.
• Masu ganewa na waje: yawancin albarkatu suna karɓar external_id naka; /<resource>/ext:{external_id} kuma yana karantawa ko rubutawa bisa wannan ID, don haka daidaitawa ba ya buƙatar adana ID na Quire.
• Rashin maimaita aiki: aika header Idempotency-Key tare da POST, PATCH da DELETE. Sake gwaji da maɓalli iri ɗaya yana dawo da amsar farko maimakon yin aikin sau biyu. Hanyoyin API na yawan abubuwa suna buƙatarsa.
• Sigogi: babban siga yana cikin hanya (/v1). A cikinta, kowane canjin da zai karya dacewa yana da sabuntawa mai kwanan wata, ana zaɓarsa da header Quire-Version, misali Quire-Version: 2026-09-20. Idan babu header, za ka samu sabuntawar da ke aiki lokacin da aka bayar da shaidar shiga.

Shafin jerin abubuwa:

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

Kurakurai

Kowane kuskure takardar matsalar RFC 9457 ce:

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

Yi rarrabewa bisa code, wanda ba ya canzawa; an rubuta detail domin mutane, ana iya nuna musu, kuma zai iya canzawa. Idan ba ka san lambar ba, ware ta bisa category:

Kawo request_id idan ka tuntuɓi taimako.

Webhooks

Yi rajista a /admin/webhooks, ko ta API a /webhook_subscriptions. Zaɓi tarurrukan bisa suna (enrolment.created), yanki (enrolment.*) ko duka (*). Da farko Quire yana aika webhook.ping; rajistar tana farawa bayan adireshinka ya amsa.

Aika saƙonni yana bin ƙa’idar Standard Webhooks:

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

Domin tantance aika:

1. Gina zaren {webhook-id}.{webhook-timestamp}.{raw body} daga ainihin bytes da aka karɓa, kafin kowane fassarar JSON.
2. Lissafa HMAC-SHA256 a kansa da sirrin rajistarka, sannan sauya zuwa base64.
3. Kwatanta shi da kowace ƙima ta v1, a webhook-signature ba tare da bayani kan lokacin kwatanta ba. A lokacin juya sirri za a iya samun biyu; duk wanda ya dace yana aiki.
4. Ƙi timestamp da ya fi minti biyar bambanci da agogonka.

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

Kada a maimaita aiki bisa webhook-id: aika na iya zuwa fiye da sau ɗaya. Jikin saƙon yana ɗauke da masu ganewa da taƙaitaccen bayani; nemi albarkatun domin samun matsayinsa na yanzu. Ana sake gwada aikawa da ta gaza tare da tazarar lokaci har tsawon awa 72, kuma ana iya sake aikawa daga rajistar isarwa.

MCP

Uwar garken MCP ta Quire tana /mcp a adireshin ƙungiya, ta streamable HTTP. Abokin MCP yana gano uwar garken OAuth daga /.well-known/oauth-protected-resource, kuma mutum yana shiga ya amince kamar kowane abokin OAuth. Kayan aiki yana aiki a matsayin mutumin tare da izininsa, kayan aikin da ke da illa kuma suna neman tabbaci. Masu gudanarwa suna zaɓar kayan aikin da ake da su a /admin/integrations/mcp.

Tsari da API

Maɓallan API, abokan OAuth, webhooks da uwar garken MCP suna ƙarƙashin izinin API na tsarin, kuma kowane tsari na yau da kullum yana haɗa shi. A tsari marar wannan, ana ƙin ƙirƙirar maɓalli, abokin aiki ko rajista; ana kuma ƙin rubutun REST da haɗin MCP, amma karatun REST yana ci gaba domin a iya fitar da bayanai. Ƙin yana zuwa a takardar matsala mai lambar commerce.plan_entitlement, rukuni precondition.

Ƙarin fasaloli

Ana ayyana nau’o’in aiki, tubalan shafi, hanyoyin shigarwa da hanyoyin shiga na Quire, nau’o’in tambaya, rahotanni, jigogi da haɗin kai ta rajistar ƙarin fasaloli iri ɗaya da shigarwar da kake sarrafawa za ta iya ƙara wa. Ana gina ƙarin fasaloli cikin Quire: babu mai loda plugin yayin aiki, kuma ƙungiyar masaukin girgije ba za ta iya ƙara ɗaya ba. Masu gudanarwa suna kunna ko kashe kowane fasali ga ƙungiyarsu a /admin/extensions (duba jagorar mai gudanarwa).

Domin rubuta ɗaya, fara da tubali da jigo na misali a packages/integration/extensions/src/sample.ts. Zaɓi wurin faɗaɗa ka karanta yarjejeniyarsa a points.ts, sannan bayyana ƙarin fasalin da ID, siga, lasisi, abin da yake bayarwa da abin da yake buƙata, da ko ƙungiya za ta iya kashe shi. Yi rajista da shi inda ake haɗa manhajar yanar gizo da mai aiki, domin su yarda. Rajistar tana gwada dokokin kowane wuri idan an gina ta da duk lokacin da aka kira register; tana ƙin saitin da ba zai yi aiki ba tare da bayyana kowace matsala, kuma ba ta canza rajistar idan ta ƙi. Gwajin ƙarin fasalin ya kamata ya tabbatar da cewa extensionContractProblems babu komai a gare shi, kuma kashe shi yana canza abin da yake shafa.