Документация API YA-Planning

Введение

API построен на REST, использует JSON и версионируется. Все бизнес-ресурсы находятся под префиксом /api/v1/pub/v1. Публичные демонстрационные конечные точки — под /api/v1/public/api-demo.

• Base 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_… — production: ваши реальные данные; генерация расходует недельную квоту.
• yap_test_… — sandbox: чтения возвращают набор демонстрационных данных (никогда ваши реальные данные), генерация не расходует квоту, а запись настроек запрещена (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 (запрещена в sandbox). Только что созданное учреждение уже содержит «Основной цикл».

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

Справочник — Расписания

Асинхронная генерация (решатель работает в фоновом режиме — опрашивайте статус), публикация и просмотр. В sandbox генерация использует демонстрационный набор и не расходует квоту.

{"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). Проверяйте подпись и свежесть timestamp (менее 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 и журнал изменений ниже.