Документация

API и интеграции

Единая точка входа для внешних LMS, тренинг-хабов и панели тестирования: привязка участников, события обучения, результаты тестов, синхронизация фреймворка и публичные endpoints.

Base URLhttps://kompetometr.ru
ФорматJSON · UTF-8
ФреймворкBT360 v2.0.0 · 2026-11-16
Каталог204 теста · 183 used

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.

HMAC
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/authKeycloak authorization endpoint

Поток входа

01Старт

Кабинет ведёт на sso/start; создаются state, nonce и PKCE S256.

02Keycloak

Пользователь входит или регистрируется у IdP; пароль не попадает в «Компетометр».

03Callback

API сверяет state, code, issuer и подпись id_token; email должен быть подтверждён.

04Сессия

Пользователь связывается по 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/…&register=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 внешней системы к пользователю по email201 / 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 → source course
  • learning.training.completed → source training
  • learning.test.completed → источник test, нужен learning.test_code и result.score 0–100

Идемпотентность

Повтор с тем же id не создаёт дубль: 200 {"ok":true,"duplicate":true}. Evidence пишется в транзакции вместе с событием; при ошибке откатывается всё.

Evidence принимается только для кодов текущего опубликованного фреймворка. Уровень — 0–5. После события профиль пересчитывается, а источник отображается в кабинете как «курс» или «тренинг».

4. Механизм внешней синхронизации

01Привязка

LMS/панель присылает external_id + email.

02Событие

Курс, тренинг или тест завершён с HMAC-подписью.

03Evidence

Коды компетенций проверяются по published-версии фреймворка.

04Профиль

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/healthHealth-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/webhookLegacy webhook панели, HMAC

7. API кабинета

Требуется cookie-сессия; изменяющие запросы — X-CSRF-Token. Компанейские разделы требуют company-аккаунт и роль.

Пользователь и фреймворк

  • GET /api/v1/auth/me
  • GET /api/v1/framework
  • GET /api/v1/framework/competencies/{code}
  • GET /api/v1/framework/tests
  • GET /api/v1/me/profile
  • GET /api/v1/me/timeline
  • GET /api/v1/users/{id}/profile
  • PATCH /api/v1/me/name

Диагностика и планы

  • GET /api/v1/assessments
  • GET /api/v1/assessments/{id}
  • POST /api/v1/assessments/self
  • POST /api/v1/assessments/{id}/launch
  • POST /api/v1/assessments/{id}/mock-complete
  • GET/POST /api/v1/me/plans
  • GET/PATCH /api/v1/me/plans/{id}
  • POST/PATCH/DELETE /api/v1/me/plans/{id}/items/{itemId}

Публичные ссылки и данные

  • GET/POST /api/v1/me/shares
  • DELETE /api/v1/me/shares/{id}
  • GET /api/v1/me/sessions
  • DELETE /api/v1/me/sessions/{id}
  • POST /api/v1/me/sessions/revoke-others
  • GET /api/v1/me/export
  • GET/POST /api/v1/me/consents
  • GET/POST/DELETE /api/v1/me/deletion-request

Компания

  • GET /api/v1/org/members
  • GET /api/v1/org/overview
  • GET/POST /api/v1/org/invitations
  • GET/POST /api/v1/org/assignments
  • GET /api/v1/org/plans
  • GET /api/v1/org/reports/team.csv
  • GET /api/v1/org/reports/assignments.csv
  • GET /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 и профиль.

LMS

Внешние события курсов/тренингов идут через /learning-events; панель — через /panel-events.

9. Лимиты и ошибки

Rate limits

  • Интеграционные события — 120/мин на IP
  • Panel webhook — 120/мин на IP
  • Публичный каталог — 60/мин на IP
  • Экспорт профиля — 5/10 минут на пользователя
  • Логин — 10/мин на IP + email

Коды ошибок

  • 401 invalid_signature — HMAC/timestamp
  • 404 participant_not_linked
  • 409 participant_conflict
  • 422 validation / invalid_evidence
  • 429 + retry_after
  • 503 integration_not_configured

Формат ошибок: {"error":"code","message":"..."}. Не логируйте секреты, токены и содержимое тел в своих системах; используйте X-Request-Id для корреляции.