API и интеграции
Единая точка входа для внешних LMS, тренинг-хабов и панели тестирования: привязка участников, события обучения, результаты тестов, синхронизация фреймворка и публичные endpoints.
1. Аутентификация
Сессия + CSRF
Cookie kompetometr_session (HttpOnly) и заголовок X-CSRF-Token для изменяющих запросов. Используется SPA-кабинетом.
HMAC-SHA256
Для внешних систем: X-Kompetometr-Signature: t=...,v1=.... Подписывается timestamp + "." + raw_body.
X-BT360-Signature
Панель использует тот же формат подписи. Legacy X-Panel-Signature поддерживается на старом URL.
canonical = timestamp + "." + raw_body signature = HMAC_SHA256(LEARNING_WEBHOOK_SECRET, canonical) X-Kompetometr-Signature: t=1763300000,v1=<hex>
Секреты задаются только в env: LEARNING_WEBHOOK_SECRET, LEARNING_WEBHOOK_SECRET_PREV, PANEL_WEBHOOK_SECRET. Окно timestamp — 300 секунд. Секреты и тела запросов не логируются.
2. SSO
Вход и регистрация идут через Keycloak по OIDC Authorization Code + PKCE. Кабинет не хранит пароль пользователя: пароль и MFA остаются у IdP. Публичные SSO-endpoint'ы не требуют cookie-сессии и не принимают CSRF-токен.
| Метод | Endpoint | Назначение |
|---|---|---|
| GET | /api/v1/auth/sso/status | Публичный статус: enabled, provider_name, button_label; без issuer/client_id/секретов |
| GET | /api/v1/auth/sso/start?return_to=/app/… | Создаёт state/nonce/PKCE, ставит HttpOnly state-cookie, 302 на IdP |
| GET | /api/v1/auth/sso/callback?code&state | Проверяет state, обменивает code, валидирует id_token, создаёт сессию и 302 в кабинет |
| GET | /sso/realms/kompetometr/protocol/openid-connect/auth | Keycloak authorization endpoint |
Поток входа
Кабинет ведёт на sso/start; создаются state, nonce и PKCE S256.
Пользователь входит или регистрируется у IdP; пароль не попадает в «Компетометр».
API сверяет state, code, issuer и подпись id_token; email должен быть подтверждён.
Пользователь связывается по email; выдаётся HttpOnly-сессия и CSRF-токен.
Регистрация
Основной путь — Keycloak self-registration. start?register=1 или prompt=register добавляет kc_action=register. После SSO пользователь может создать компанию через POST /api/v1/org/create.
Приглашения
Гость проходит SSO с return_to=/app/invite/…®ister=1, затем принимает приглашение через POST /api/v1/org/invitations/{token}/accept. Email сессии должен совпасть с email приглашения.
Конфигурация
OIDC_ENABLED=true OIDC_ISSUER=https://kompetometr.ru/sso/realms/kompetometr OIDC_CLIENT_ID=kompetometr-lumen OIDC_REDIRECT_URI=https://kompetometr.ru/api/v1/auth/sso/callback OIDC_SCOPES="openid email profile" OIDC_AUTO_PROVISION=false OIDC_REQUIRE_EMAIL_VERIFIED=true
Секрет OIDC_CLIENT_SECRET хранится только в env. issuer сравнивается с claim iss точно; state живёт 10 минут; cookie — HttpOnly, Secure, SameSite=Lax. Ошибки возвращаются редиректом на /app/login?sso_error=<code>, без раскрытия деталей IdP.
Основные ошибки: sso_disabled, invalid_state, invalid_callback, email_unverified, user_not_found, sso_unavailable. Коды start/callback при выключенном SSO возвращают 503.
3. Внешняя интеграция
Базовый путь: /api/v1/integration/v1. Все запросы — POST, Content-Type: application/json, HMAC-подпись, идемпотентность по id события.
| Метод | Endpoint | Назначение | Ответ |
|---|---|---|---|
| POST | /participants | Привязать external_id внешней системы к пользователю по email | 201 / 200, 409 при конфликте |
| POST | /learning-events | Курс, тренинг или тест завершён; evidence и пересчёт профиля | 201; 200 duplicate |
| POST | /panel-events | Новый URL панели, payload и подпись прежние | как panel webhook |
Привязка участника
POST /api/v1/integration/v1/participants
{
"external_id": "lms-user-1",
"email": "user@example.com"
}Один внешний ID — один пользователь. Повторная привязка того же пользователя к другому ID возвращает 409 participant_conflict. Для панели дополнительно работает существующая связь panel_accounts.external_id.
Событие обучения
POST /api/v1/integration/v1/learning-events
{
"id": "evt-2026-0001",
"type": "learning.course.completed",
"occurred_at": "2026-11-16T10:00:00Z",
"participant": {"external_id": "lms-user-1"},
"learning": {
"title": "Курс обратной связи",
"provider": "LMS",
"external_id": "course-42",
"url": "https://lms.example/courses/42"
},
"evidence": [
{"competency_code": "PER-01", "level": 3, "confidence": "medium"}
]
}Типы событий
learning.course.completed→ sourcecourselearning.training.completed→ sourcetraininglearning.test.completed→ источникtest, нуженlearning.test_codeиresult.score0–100
Идемпотентность
Повтор с тем же id не создаёт дубль: 200 {"ok":true,"duplicate":true}. Evidence пишется в транзакции вместе с событием; при ошибке откатывается всё.
Evidence принимается только для кодов текущего опубликованного фреймворка. Уровень — 0–5. После события профиль пересчитывается, а источник отображается в кабинете как «курс» или «тренинг».
4. Механизм внешней синхронизации
LMS/панель присылает external_id + email.
Курс, тренинг или тест завершён с HMAC-подписью.
Коды компетенций проверяются по published-версии фреймворка.
CompetencyScorer пересчитывает уровни и делает snapshot.
Ошибки: 401 invalid_signature, 404 participant_not_linked, 422 validation, 409 participant_conflict. Повторные сетевые доставки безопасны.
5. Панель тестирования
| Механизм | Endpoint / команда | Назначение |
|---|---|---|
| Исходящие назначения | POST /api/integration/v1/participants POST /api/integration/v1/assignments | Панель: участники и назначения; инициирует платформа |
| Запуск | POST /api/integration/v1/launch-ticket | Одноразовый launch ticket; сессия панели |
| Новый приёмник | POST /api/v1/integration/v1/panel-events | Предпочтительный URL; payload и X-BT360-Signature прежние |
| Legacy приёмник | POST /api/v1/integration/panel/webhook | Обратная совместимость |
| Сверка | php artisan panel:reconcile | Дозагрузка потерянных результатов и failed-сессий |
События панели: assessment.session.completed, assessment.session.rescored, assessment.session.failed, session.completed, session.failed. Подпись: X-BT360-Signature: t=...,v1=...; legacy X-Panel-Signature + timestamp.
Панель — только test engine. Организации, роли, компетенции и профили остаются в «Компетометре». Результат теста не равен уровню: уровень подтверждается поведением.
6. Публичные endpoints
| Метод | Endpoint | Назначение |
|---|---|---|
| GET | /api/v1/health | Health-check, версия и ревизия фреймворка |
| GET | /api/v1/plans | Публичный каталог тарифов и entitlements |
| POST | /api/v1/auth/login | Вход, cookie-сессия, CSRF |
| POST | /api/v1/auth/register-individual /api/v1/auth/register | Legacy-регистрация; основной вход — SSO |
| POST | /api/v1/auth/accept-invite /api/v1/auth/forgot-password /api/v1/auth/reset-password | Приглашение и восстановление доступа |
| GET | /api/v1/auth/sso/status /api/v1/auth/sso/start /api/v1/auth/sso/callback | OIDC SSO (Keycloak) |
| GET | /api/v1/public/participants | Каталог «Участники»: только opt-in, без email и токенов |
| GET | /api/v1/public/profiles/{token} | JSON публичного профиля по share-токену |
| GET | /p/{token} | HTML публичного профиля, noindex/no-referrer |
| GET | /participants/ | SSR-страница каталога «Участники» |
| POST | /api/v1/integration/panel/webhook | Legacy webhook панели, HMAC |
7. API кабинета
Требуется cookie-сессия; изменяющие запросы — X-CSRF-Token. Компанейские разделы требуют company-аккаунт и роль.
Пользователь и фреймворк
GET /api/v1/auth/meGET /api/v1/frameworkGET /api/v1/framework/competencies/{code}GET /api/v1/framework/testsGET /api/v1/me/profileGET /api/v1/me/timelineGET /api/v1/users/{id}/profilePATCH /api/v1/me/name
Диагностика и планы
GET /api/v1/assessmentsGET /api/v1/assessments/{id}POST /api/v1/assessments/selfPOST /api/v1/assessments/{id}/launchPOST /api/v1/assessments/{id}/mock-completeGET/POST /api/v1/me/plansGET/PATCH /api/v1/me/plans/{id}POST/PATCH/DELETE /api/v1/me/plans/{id}/items/{itemId}
Публичные ссылки и данные
GET/POST /api/v1/me/sharesDELETE /api/v1/me/shares/{id}GET /api/v1/me/sessionsDELETE /api/v1/me/sessions/{id}POST /api/v1/me/sessions/revoke-othersGET /api/v1/me/exportGET/POST /api/v1/me/consentsGET/POST/DELETE /api/v1/me/deletion-request
Компания
GET /api/v1/org/membersGET /api/v1/org/overviewGET/POST /api/v1/org/invitationsGET/POST /api/v1/org/assignmentsGET /api/v1/org/plansGET /api/v1/org/reports/team.csvGET /api/v1/org/reports/assignments.csvGET /api/v1/org/audit-events
8. Синхронизация фреймворка
FRAMEWORK_API=https://competency-tree.ru/api/v1 php api/scripts/sync_framework.php # cron production: 04:17 UTC flock -n /tmp/kompetometr-framework-sync.lock php scripts/sync_framework.php
Sync загружает manifest.json и framework.json, проверяет counts и создаёт новую framework_versions со статусом published. Повтор с тем же revision/hash идемпотентен. Старые версии сохраняются для воспроизводимости.
GET /api/v1/framework — текущая published-версия; /framework/tests — 204 теста, слои и кластеры.
Внешние назначения, launch ticket, входящие результаты, nightly reconcile. Результаты обновляют evidence и профиль.
Внешние события курсов/тренингов идут через /learning-events; панель — через /panel-events.
9. Лимиты и ошибки
Rate limits
- Интеграционные события — 120/мин на IP
- Panel webhook — 120/мин на IP
- Публичный каталог — 60/мин на IP
- Экспорт профиля — 5/10 минут на пользователя
- Логин — 10/мин на IP + email
Коды ошибок
401 invalid_signature— HMAC/timestamp404 participant_not_linked409 participant_conflict422 validation/invalid_evidence429+retry_after503 integration_not_configured
Формат ошибок: {"error":"code","message":"..."}. Не логируйте секреты, токены и содержимое тел в своих системах; используйте X-Request-Id для корреляции.