---
title: "Garatzailearen gida"
description: "Quire-ren REST APIa, OAuth, webhooks, MCP zerbitzaria eta luzapenak."
image: "https://docs.quirelms.com/og.png"
---

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

# Garatzailearen gida

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

Erabili zure erakundearen API helbidea eta irismen mugatuko kredentzial bat. Hasi irakurketa-eskaera batekin, egiaztatu erantzuna eta gorde sekretuak iturburu-kodetik eta dokumentazio-adibideetatik kanpo.

Quire-k API publiko bat du: REST HTTPS bidez, OpenAPI 3.1 dokumentu batean deskribatua, gertaeretarako sinatutako webhookekin eta IA-laguntzaileentzako MCP zerbitzariarekin. [APIaren erreferentziak](https://docs.quirelms.com/api/) endpoint eta gertaera guztiak zerrendatzen ditu.

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

Erakunde bakoitzak helbide propioa du, eta APIa haren azpian dago:

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

Kredentzialak zehazten du erakundea. Erakunde bateko gakoa beste baten helbidean erabiltzen bada, eskaera ukatu egiten da.

OpenAPI dokumentua edozein erakunderen helbidean dago eskuragarri `/api/v1/openapi.json` helbidean; beraz, bezero-sorgailuek deitzen ari zaren bertsioa ikusten dute beti.

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

**API gakoak** script eta zerbitzaritik zerbitzarirako integrazioetarako dira. Administratzaile batek `/admin/integrations/api-keys` helbidean sortzen du, haren irismenak aukeratzen ditu eta behin bakarrik ikusten du. Bidali bearer token gisa:

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

Gakoak `qk_live_` edo `qk_test_` aurrizkiarekin hasten dira. Eman integrazio bakoitzari gako propioa.

**OAuth 2.1** saioa hasita duen pertsona baten moduan jarduten duten aplikazioetarako da. Erregistratu bezero bat `/admin/integrations/oauth-clients` helbidean; gero, erabili PKCE duen baimen-kodearen fluxua (`/oauth/authorize`, `/oauth/token`) edo bezero-kredentzialak makina-bezero baterako. Aurkikuntza `/.well-known/oauth-authorization-server` helbidean dago. Irismen batek tokenak egin dezakeena mugatzen du; ez dio pertsonak baino gehiago egiten uzten.

Irismenak `resource:read`, `resource:write` eta `resource:delete` dira; esaterako, `courses:read` edo `enrolments:write`. Lau pribilegiatuak dira eta abisu batekin erakusten dira baimen-pantailan: `audit:read`, `roles:write`, `tenants:write` eta `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>

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

- **Orrialdekatzea**: zerrenda guztiak kurtsoreen bidez orrialdekatzen dira. Bidali `limit`; hartu `next_cursor` `page`-tik eta erabili `cursor` gisa `has_more` true den bitartean (beheko adibidea). Ez dago offsetik.
- **Aldaketak data batetik aurrera**: `updated_since` aukerak une batetik aurrera aldatutakoak ematen ditu. Erabili `include_deleted=true` parametroarekin batera edo irakurri `/<resource>/deletions`, zer kendu den jakiteko.
- **Kanpoko identifikatzaileak**: baliabide gehienek zure `external_id` propioa onartzen dute; `/<resource>/ext:{external_id}` bideak horren bidez irakurtzen edo eguneratzen/sortzen du, sinkronizazioak Quire-ren identifikatzaileak gorde behar izan ez ditzan.
- **Idempotentzia**: bidali `Idempotency-Key` goiburua `POST`, `PATCH` eta `DELETE` eskaeretan. Gako bera duen berriro saiakerak lehen erantzuna itzultzen du, lana bi aldiz egin beharrean. Multzoko endpointek derrigor behar dute.
- **Bertsioak**: bertsio nagusia bidean dago (`/v1`). Haren barruan, aldaketa bateraezin bakoitzak data duen berrikuspen bat du, `Quire-Version` goiburuaren bidez hautatzen dena, esaterako `Quire-Version: 2026-09-20`. Goibururik gabe, kredentziala jaulki zeneko berrikuspena jasotzen duzu.

Zerrenda baten orrialde bat:

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

## Erroreak <!--quire:errors-->

Errore guztiak RFC 9457 arauko arazo-dokumentuak dira:

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

Erabakia hartzeko, erabili egonkorra den `code`; `detail` pertsonentzat idatzita dago, erakusteko segurua da eta alda daiteke. Kodea ezagutzen ez baduzu, sailkatu errorea `category`-ren arabera:

| Kategoria | Egoera | Berriz saiatu |
| --- | --- | --- |
| `validation` | 422, eremuen xehetasunak `errors`-en | Ez |
| `authentication` | 401 | Ez |
| `authorization` | 403 | Ez |
| `not_found` | 404 | Ez |
| `conflict` | 409 | Batzuetan |
| `precondition` | 412 | Ez |
| `quota` | 402 planarentzat, 413 tamainarentzat | Ez |
| `rate_limit` | 429, `Retry-After` goiburuarekin | Bai |
| `upstream` | 502 edo 504 | Bai |
| `internal` | 500 | Bai |

Jarri `request_id` laguntzarekin harremanetan jartzean.

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

Harpidetu `/admin/webhooks` helbidean edo APIaren bidez, `/webhook_subscriptions` helbidean. Aukeratu gertaerak izenaren arabera (`enrolment.created`), eremuaren arabera (`enrolment.*`) edo guztiak (`*`). Quire-k lehenik `webhook.ping` bidaltzen du; zure endpointak erantzuten dionean hasten da harpidetza.

Bidalketek Standard Webhooks zehaztapena jarraitzen dute:

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

Bidalketa egiaztatzeko:

1. Eraiki `{webhook-id}.{webhook-timestamp}.{raw body}` katea jasotako byte zehatzekin, JSONa aztertu aurretik.
2. Kalkulatu HMAC-SHA256 haren gainean, harpidetzaren sekretua erabiliz, eta kodetu base64 formatuan.
3. Konparatu denbora konstantean `v1,` balio bakoitza `webhook-signature` goiburuan. Sekretua biratzen ari bada, bi egon daitezke; bat datorren edozein balio da zuzena.
4. Baztertu zure erlojutik bost minutu baino gehiagora dagoen denbora-zigilua.

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

Saihestu bikoizketak `webhook-id` erabiliz: bidalketa bat behin baino gehiagotan hel daiteke. Gorputzak identifikatzaileak eta laburpen bat ditu; eskuratu baliabidea haren uneko egoera ikusteko. Huts egindako bidalketak berriz saiatzen dira, gero eta tarte handiagoekin, 72 orduz gehienez; bidalketa-erregistrotik berriro erreproduzi daitezke.

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

Quire-ren MCP zerbitzaria `/mcp` helbidean dago erakundearen helbidean, HTTP streaming bidez. MCP bezero batek OAuth zerbitzaria aurkitzen du `/.well-known/oauth-protected-resource` helbidean; pertsonak saioa hasi eta baimena ematen du OAuth bezero guztietan bezala. Tresnek pertsona horren baimenekin jarduten dute, eta ekintza suntsitzaileek berrespena eskatzen dute. Administratzaileek `/admin/integrations/mcp` helbidean aukeratzen dute zer tresna dauden erabilgarri.

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

## Planak eta APIa <!--quire:plans-and-the-api-->

API gakoak, OAuth bezeroak, webhooks eta MCP zerbitzaria planaren API-eskubidearen barruan daude, eta plan estandar guztiek dute eskubide hori. Eskubidea barne hartzen ez duen plan batean, gakoa, bezeroa edo harpidetza sortzea ukatzen da; REST idazketak eta MCP konexioak ere ukatzen dira. REST irakurketek funtzionatzen jarraitzen dute datuak esportatu ahal izateko. Uko egitea arazo-dokumentu bat da, `commerce.plan_entitlement` kodearekin eta `precondition` kategorian.

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

Quire-ren jarduera-motak, blokeak, matrikulazio- eta saio-hasiera metodoak, galdera-motak, txostenak, gaiak eta integrazioak luzapen-erregistro berean deklaratzen dira; autoostatatutako instalazio batek ere gehi ditzake. Luzapenak aplikazioan konpilatzen dira: ez dago exekuzioan pluginak kargatzeko mekanismorik, eta ostatatutako erakunde batek ezin du halakorik gehitu. Administratzaileek luzapen bakoitza erakunderako aktibatu edo desaktibatzen dute `/admin/extensions` helbidean (ikus [administratzailearen gida](/eu/admin/extensions/)).

Luzapen bat idazteko, hasi `packages/integration/extensions/src/sample.ts`-ko bloke eta gai laginekin. Aukeratu luzapen-puntua eta irakurri haren kontratua `points.ts` fitxategian; gero, deklaratu luzapena ID, bertsio eta lizentzia batekin, zer eskaintzen eta behar duen zehaztuta eta erakunde batek desaktiba dezakeen adierazita. Erregistratu web-aplikazioa eta worker-a elkartzen diren lekuan, biak ados egon daitezen. Erregistroak puntu bakoitzaren arauak egiaztatzen ditu eraikitzean eta `register` deitzen duzun bakoitzean; baliogabea den multzoa ukatu eta arazo guztiak izendatzen ditu, eta erregistroa aldatu gabe uzten du. Luzapenaren probek egiaztatu behar dute `extensionContractProblems` hutsik dagoela eta desaktibatzeak eragiten duen gauza aldatzen duela.

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