YA-Planning API 文档

简介

该 API 是 REST 风格、基于 JSON、带版本管理的。所有业务资源均位于前缀 /api/v1/pub/v1 下。公共演示端点位于 /api/v1/public/api-demo 下。

• 基础 URL：https://votre-domaine/api/v1/pub/v1
• 格式：请求与响应采用 application/json（ICS/PDF 导出除外）。
• 版本管理：版本包含在路径中（/v1）；向后兼容的新增不会改变版本。
• CORS：公共 API 对第三方浏览器应用开放（不含 cookie）。

认证

每个请求都在以下两个请求头之一中携带 API 密钥：

X-API-Key: yap_live_xxxxxxxxxxxxxxxxxxxx
# ou
Authorization: Bearer yap_live_xxxxxxxxxxxxxxxxxxxx

一个密钥可被授权用于多所学校（企业密钥）。此时请通过请求头 X-Etablissement-Id 指定目标；如果仅有一所被授权的学校，则会自动推断。密钥在控制台中按权限范围创建。

环境与沙盒

两种环境，通过密钥前缀区分：

• yap_live_… — 生产环境：您的真实数据；生成会计入每周配额。
• yap_test_… — 沙盒：读取会返回一组演示数据（绝非您的真实数据），生成不计入配额，且配置写入会被拒绝（SANDBOX_READONLY）。非常适合无风险地开发。

权限范围

每个密钥携带权限范围的一个子集；如果缺少所需的权限范围，端点会拒绝（403 INSUFFICIENT_SCOPE）。

速率与配额

每个密钥都有速率限制（默认 60 次请求/分钟）。响应会携带：

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
X-RateLimit-Reset: 1783919311   # epoch (s) de réinitialisation

超出限制会返回 429 RATE_LIMITED 以及 Retry-After 请求头。课程表生成还额外受套餐每周配额的限制（可通过 /me 查看）。

API 的每个响应还会携带一个 X-Request-Id 请求头（关联标识）— 发生故障时请将其提供给支持团队。注意：速率计数目前按实例应用；在多实例部署中，实际限制可能是所显示值的若干倍。

错误

统一的错误封装，含用于支持团队的 requestId：

{ "error": "INSUFFICIENT_SCOPE", "message": "Scope requis : config:write.",
  "requestId": "6181762d-…", "requiredScope": "config:write" }

在线测试 — 无需注册

公共演示端点（无需密钥）。

Postman：« Import » → « Link » → 粘贴 /q/openapi?format=json。

参考 — 账户与内省

{
  "environment": "LIVE",
  "etablissementId": "61a9…8cb",
  "scopes": ["config:read", "timetables:write"],
  "entitlements": {
    "plan": "PRO",
    "generationsRestantes": -1,
    "resetLe": "2026-07-14T00:00:00Z",
    "maxClassesExport": -1
  }
}

{"id":"…","nom":"Groupe Scolaire Les Palmiers","slug":"gs-palmiers","sigle":"GSP","ville":"Abidjan","pays":"CI","type":"PRIVE","siteWeb":"https://…"}

{"apiKeyId":"…","days":30,"daily":[{"day":"2026-07-12","calls":128,"errors":3}]}

参考 — 账户 — 学校

账户级开通：在不带 X-Etablissement-Id 请求头的情况下创建您自己的学校（/account 路径不与某所学校绑定）。权限范围 establishments:manage。创建时，发起调用的密钥会自动获得对新学校的 ACTIVE 授权 — 之后请使用 X-Etablissement-Id 对其进行配置和生成。

{"nom":"Groupe Scolaire Les Palmiers","type":"PRIVE_LAIC","pays":"CI"}

{"id":"…","nom":"Groupe Scolaire Les Palmiers","slug":"gs-les-palmiers","pays":"CI","type":"PRIVE_LAIC"}

[{"id":"…","nom":"…","slug":"…","pays":"CI","type":"PRIVE_LAIC"}]

参考 — 配置

学校的教学结构。读取：权限范围 config:read。写入：权限范围 config:write（沙盒中禁止）。一所新创建的学校已包含一个«主学段»。

[{"id":"…","libelle":"Cycle principal","ordre":0}]

{"libelle":"Second cycle","ordre":1}

[{"id":"…","libelle":"6ème 1","cycleId":"…","effectif":42,"ordre":1}]

{"libelle":"6ème 3","cycleId":"<uuid-cycle>","effectif":40,"ordre":3}

[{"id":"…","libelle":"Mathématiques","code":"MATH","couleur":"#6C5CE7","ordre":1}]

{"libelle":"Physique-Chimie","code":"PC","couleur":"#00B894","ordre":5}

[{"id":"…","nom":"Koné","prenoms":"Awa","matricule":"P-0142","email":"…","telephone":"…","nombreHeureAutorise":18,"statut":"TITULAIRE","actif":true}]

{"nom":"Diarra","prenoms":"Sékou","matricule":"P-0210","email":"s.diarra@ecole.ci","nombreHeureAutorise":18,"statut":"VACATAIRE","actif":true}

[{"id":"…","jour":"MONDAY","heureDebut":"08:00","heureFin":"09:00","estPause":false,"libelle":null}]

{"jour":"MONDAY","heureDebut":"08:00","heureFin":"09:00","estPause":false,"libelle":"M1"}

[{"id":"…","cycleId":"…","disciplineId":"…","nombreHeuresObligatoire":4,"minHeuresConsecutives":1,"maxHeuresConsecutives":2}]

{"cycleId":"<uuid>","disciplineId":"<uuid>","nombreHeuresObligatoire":4,"minHeuresConsecutives":1,"maxHeuresConsecutives":2}

参考 — 课程表

异步生成（求解器在后台运行 — 请轮询状态）、发布与查询。在沙盒中，生成使用一组演示数据，且不计入配额。

{"durationMinutes": 5}

{"jobId":"…","status":"SOLVING_SCHEDULED"}

{"items":[{"jobId":"…","name":"…","status":"SOLVING_ENDED","workflowStatus":"BROUILLON","feasible":true,"hardScore":0,"softScore":-42,"createdAt":"…"}],"total":7,"page":0,"size":25}

{"jobId":"…","status":"SOLVING_ENDED","feasible":true,"lessons":[{"id":"1","matiere":"Maths","niveau":"6ème 1","professeur":"M. Koné","jour":"MONDAY","debut":"08:00:00","fin":"09:00:00","couleur":"#6C5CE7","niveauOrdre":1,"verrouille":false}]}

{"classes":["6ème 1","6ème 2","5ème 1"]}

参考 — Webhooks

接收已签名的事件。权限范围 webhooks:manage。密钥仅在创建时（或轮换后）返回。事件：timetable.job.completed、timetable.job.failed、timetable.published、webhook.test。每次投递都经过签名（HMAC-SHA256），失败时最多重放 5 次。URL 会经过反 SSRF 校验（拒绝内部/私有目标）。

{"url":"https://exemple.com/webhooks/yap","events":["timetable.published","timetable.job.completed"]}

{"endpoint":{"id":"…","url":"…","events":["timetable.published"],"active":true},"secret":"whsec_…"}

{"endpoint":{"id":"…","url":"…"},"secret":"whsec_…"}

参考 — 演示（公共，无需密钥）

无需认证的公共端点，用于了解响应的形态。

Webhooks — 验证签名

每次投递都是一个 JSON POST，带有请求头 X-Webhook-Event、X-Webhook-Timestamp 和 X-Webhook-Signature = HMAC-SHA256(timestamp + "." + body, secret)。请验证签名并核对时间戳的新鲜度（小于 5 分钟）以防止重放。事件：timetable.published、timetable.job.completed、timetable.job.failed、webhook.test。

POST https://votre-app/webhook
X-Webhook-Event: timetable.published
X-Webhook-Timestamp: 1712345678
X-Webhook-Signature: 9f86d081…

{ "event":"timetable.published", "jobId":"…", "etablissementId":"…", "occurredAt":"…" }

import crypto from "crypto";

// Express — vérifier la signature d'un webhook YA-Planning
app.post("/webhooks/yap", express.raw({ type: "*/*" }), (req, res) => {
  const ts  = req.header("X-Webhook-Timestamp");
  const sig = req.header("X-Webhook-Signature");
  const body = req.body.toString("utf8");

  const expected = crypto.createHmac("sha256", process.env.YAP_WEBHOOK_SECRET)
    .update(`${ts}.${body}`).digest("hex");

  // fraîcheur (anti-rejeu) : < 5 min
  const fresh = Math.abs(Date.now()/1000 - Number(ts)) < 300;
  if (!fresh || !crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected)))
    return res.sendStatus(400);

  const event = JSON.parse(body); // { event, jobId, etablissementId, occurredAt }
  res.sendStatus(200);
});

代码示例

# Vérifier ses droits
curl https://votre-domaine/api/v1/pub/v1/me \
  -H "X-API-Key: yap_live_xxxxxxxxxxxx"

# Générer un EDT puis suivre le job
JOB=$(curl -s -X POST .../api/v1/pub/v1/timetables/generate \
  -H "X-API-Key: yap_live_xxxx" -H "Content-Type: application/json" \
  -d '{"durationMinutes":5}' | jq -r .jobId)

curl .../api/v1/pub/v1/timetables/jobs/$JOB \
  -H "X-API-Key: yap_live_xxxx"

版本与弃用

该 API 在路径中带版本（/api/v1/pub/v1/…）。我们以向后兼容的方式新增字段和端点；这些新增不构成破坏性变更，因此请以宽容的方式编码（忽略未知字段）。任何破坏性变更都将产生一个新的主版本，并至少提前 90 天通过响应头 Deprecation 及下方的变更日志发出预告。