---
title: "Gwida tal-iżviluppatur"
description: "Ir-REST API ta' Quire, OAuth, webhooks, is-server MCP u estensjonijiet."
image: "https://docs.quirelms.com/og.png"
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.quirelms.com/mt/llms.txt
> Use this file to discover all available pages before exploring further.

# Gwida tal-iżviluppatur

<span id="developer-guide"></span>

Uża l-indirizz API tal-organizzazzjoni tiegħek u kredenzjali bi skop limitat. Ibda b'talba ta' qari, iċċekkja r-risposta, u żomm is-sigrieti barra mill-kontroll tas-sors u l-eżempji tad-dokumentazzjoni.

Quire għandha API pubblika waħda: REST fuq HTTPS, deskritta b'dokument
OpenAPI 3.1, b'webhooks iffirmati għall-avvenimenti u server MCP għal assistenti
tal-AI. Ir-[referenza tal-API](https://docs.quirelms.com/api/) telenka kull endpoint u avveniment.

## Indirizzi <!--quire:addresses-->

Kull organizzazzjoni għandha l-indirizz tagħha, u l-API tgħix taħtu:

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

Il-kredenzjali tiddeċiedi l-organizzazzjoni. Ċavetta għal organizzazzjoni waħda użata fl-
indirizz ta' oħra tiġi rifjutata.

Id-dokument OpenAPI jingħata f'`/api/v1/openapi.json` fuq kwalunkwe
indirizz ta' organizzazzjoni, biex il-ġeneraturi tal-klijenti dejjem jaraw il-verżjoni li inti
qed issejjaħ.

## Awtentikazzjoni <!--quire:authentication-->

**Ċwievet tal-API** huma għal skripts u integrazzjonijiet server-to-server. Amministratur
joħloq waħda f'`/admin/integrations/api-keys`, jagħżel l-
iskops tagħha, u jaraha darba. Ibgħatha bħala bearer token:

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

Iċ-ċwievet jibdew `qk_live_` jew `qk_test_`. Agħti lil kull integrazzjoni ċ-ċavetta tagħha.

**OAuth 2.1** huwa għal applikazzjonijiet li jaġixxu bħala persuna mdaħħla. Irreġistra
klijent f'`/admin/integrations/oauth-clients`, imbagħad uża l-fluss tal-kodiċi tal-awtorizzazzjoni
b'PKCE (`/oauth/authorize`, `/oauth/token`), jew kredenzjali tal-klijent
għal klijent ta' magna. L-iskoperta tinsab f'
`/.well-known/oauth-authorization-server`. Skop jiddejjaq x'token jista'
jagħmel; qatt ma jħallih jagħmel aktar milli setgħet il-persuna.

L-iskops huma `resource:read`, `resource:write` u `resource:delete`, pereżempju
`courses:read` jew `enrolments:write`. Erbgħa huma privileġġjati u jintwerew
bi twissija fuq l-iskrin tal-kunsens: `audit:read`, `roles:write`,
`tenants:write` u `users:delete`.

<figure class="quire-shot" lang="en" dir="ltr"><img src="/screenshots/admin-api-keys.webp" alt="The API keys page with one key, the person it acts as, its scopes and its status, and a form to create another." width="944" height="700" loading="lazy" decoding="async"><figcaption>API keys list who each key acts as and what it may reach.</figcaption></figure>

## Talbiet <!--quire:requests-->

- **Paġinazzjoni**: kull lista hija paġinata b'cursor. Għaddi `limit`, imbagħad il-
  `next_cursor` minn `page` bħala `cursor` sakemm `has_more` ikun true (eżempju
  hawn taħt). M'hemm l-ebda offset.
- **Bidliet minn meta**: `updated_since` jirritorna x'inbidel wara ħin.
  Qabbilha ma' `include_deleted=true`, jew aqra `/<resource>/deletions`, biex
  titgħallem x'tneħħa.
- **Identifikaturi esterni**: ħafna riżorsi jaċċettaw l-`external_id` tiegħek,
  u `/<resource>/ext:{external_id}` jaqra jew jagħmel upsert bih, biex sync qatt ma
  jeħtieġ jaħżen l-identifikaturi ta' Quire.
- **Idempotenza**: ibgħat header `Idempotency-Key` fuq `POST`, `PATCH` u
  `DELETE`. Retry bl-istess ċavetta jirritorna l-ewwel risposta minflok ma
  jagħmel ix-xogħol darbtejn. Endpoints bulk jeħtieġuha.
- **Verżjonijiet**: il-verżjoni maġġuri tinsab fil-mogħdija (`/v1`). Fiha, kull
  bidla li tkisser hija reviżjoni datata, magħżula bl-header `Quire-Version`,
  pereżempju `Quire-Version: 2026-09-20`. Mingħajr l-header tieħu
  ir-reviżjoni attwali meta nħarġet il-kredenzjali tiegħek.

Paġna ta' lista:

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

## Żbalji <!--quire:errors-->

Kull żball huwa dokument ta' problema RFC 9457:

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

Fergħa fuq `code`, li huwa stabbli; `detail` jinkiteb għan-nies, sigur biex
turihom, u jista' jinbidel. Meta ma tagħrafx kodiċi, iġbor fuq
`category`:

| Category | Status | Retry |
| --- | --- | --- |
| `validation` | 422, b'dettall tal-qasam f'`errors` | Le |
| `authentication` | 401 | Le |
| `authorization` | 403 | Le |
| `not_found` | 404 | Le |
| `conflict` | 409 | Xi kultant |
| `precondition` | 412 | Le |
| `quota` | 402 għall-pjan, 413 għad-daqs | Le |
| `rate_limit` | 429, b'`Retry-After` | Iva |
| `upstream` | 502 jew 504 | Iva |
| `internal` | 500 | Iva |

Ikkwota `request_id` meta tikkuntattja l-appoġġ.

## Webhooks <!--quire:webhooks-->

Abbona f'`/admin/webhooks`, jew permezz tal-API f'
`/webhook_subscriptions`. Agħżel l-avvenimenti bl-isem (`enrolment.created`),
biż-żona (`enrolment.*`) jew kollha (`*`). Quire l-ewwel tibgħat `webhook.ping`; l-
abbonament jibda ladarba l-endpoint tiegħek iwieġeb.

Il-kunsinni jsegwu l-ispeċifikazzjoni Standard Webhooks:

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

Biex tivverifika kunsinna:

1. Ibni s-sekwenza `{webhook-id}.{webhook-timestamp}.{raw body}` mill-
   bytes eżatti riċevuti, qabel kwalunkwe parsing JSON.
2. Ikkalkula HMAC-SHA256 fuqha bis-sigriet tal-abbonament tiegħek, u għamilha base64.
3. Qabbel ma' kull valur `v1,` f'`webhook-signature` f'ħin kostanti.
   Jista' jkun hemm tnejn waqt rotazzjoni ta' sigriet; kull tqabbila hija valida.
4. Irretja timestamp aktar minn ħames minuti mill-arloġġ tiegħek.

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

Idduplika fuq `webhook-id`: kunsinna tista' tasal aktar minn darba. Il-body
iġorr identifikaturi u sommarju qasir; iġbed ir-riżorsa għall-istat attwali
tagħha. Kunsinni falluti jerġgħu jiġu ppruvati b'backoff sa 72 siegħa, u
jistgħu jerġgħu jintlagħbu mil-log tal-kunsinna.

## MCP <!--quire:mcp-->

Is-server MCP ta' Quire jinsab f'`/mcp` fuq l-indirizz tal-organizzazzjoni, fuq
HTTP streamabbli. Klijent MCP jiskopri s-server OAuth minn
`/.well-known/oauth-protected-resource`, u l-persuna tidħol u
tikkunsenti bħal ma' kwalunkwe klijent OAuth. L-għodod jaġixxu bħal dik il-persuna, bil-permessi
tagħhom, u għodod distruttivi jitolbu konferma. L-amministraturi
jagħżlu liema għodod huma disponibbli f'`/admin/integrations/mcp`.

<figure class="quire-shot" lang="en" dir="ltr"><img src="/screenshots/admin-mcp.webp" alt="The AI assistants page with the server address to give an assistant and a table of the tools it can use." width="944" height="700" loading="lazy" decoding="async"><figcaption>AI assistants (MCP): the server address, and the tools an assistant may call.</figcaption></figure>

## Pjanijiet u l-API <!--quire:plans-and-the-api-->

Ċwievet tal-API, klijenti OAuth, webhooks u s-server MCP huma tal-intitolament API tal-pjan,
u kull pjan standard jinkludih. Fuq pjan mingħajru, il-ħolqien ta'
ċavetta, klijent jew abbonament jiġi rifjutat, kitbiet REST u konnessjonijiet MCP huma
rifjutati, u qari REST ikompli jaħdem biex id-data tibqa' esportabbli. Ir-rifjut huwa dokument ta' problema bil-
kodiċi `commerce.plan_entitlement`, fil-kategorija `precondition`.

## Estensjonijiet <!--quire:extensions-->

It-tipi ta' attività ta' Quire stess, blokki, metodi ta' reġistrazzjoni, metodi ta' dħul, tipi ta' mistoqsijiet,
rapporti, temi u integrazzjonijiet huma ddikjarati permezz tal-istess reġistru ta' estensjonijiet
li installazzjoni self-hosted tista' żżid miegħu. L-estensjonijiet huma kkompilati ġewwa:
m'hemm l-ebda loader ta' plugins f'ħin it-tħaddim, u organizzazzjoni hosted ma tistax iżżid waħda.
L-amministraturi jixgħelu jew jitfu kull estensjoni għall-organizzazzjoni tagħhom f'
`/admin/extensions` (ara l-[gwida tal-amministratur](/mt/admin/extensions/)).

Biex tikteb waħda, ibda mill-blokka kampjun u t-tema f'
`packages/integration/extensions/src/sample.ts`. Agħżel il-punt tal-estensjoni u
aqra l-kuntratt tiegħu f'`points.ts`, imbagħad iddikjara l-estensjoni b'id, verżjoni,
liċenzja, x'tipprovdi u teħtieġ, u jekk organizzazzjoni tistax titfiha.
Irreġistraha fejn l-applikazzjoni web u l-worker huma komposti, biex it-tnejn
jaqblu. Ir-reġistru jiċċekkja r-regoli ta' kull punt meta jinbena u kull meta
tissejjaħ `register`, jirrifjuta sett li jkun invalidu b'kull problema msemmija, u
jħalli r-reġistru mhux mibdul meta jagħmel hekk. It-testijiet tal-estensjoni għandhom jasserixxu
li `extensionContractProblems` huwa vojt għaliha u li t-tifi tagħha jbiddel
dak li taffettwa.

Source: https://docs.quirelms.com/mt/developer/index.mdx