Public API
Документация для сторонних приложений и сервисов, которые подключаются к ClimbingMetrics.
Production API
https://climbingmetrics.ru
Базовый префикс API: https://climbingmetrics.ru/api/v1
От подключения до плана
- Получите учётные данные интеграции в ClimbingMetrics.
- Выберите серверную интеграцию по
client_id + client_secretили мобильный сценарий public installation с DPoP. Секрет сервиса нельзя помещать в мобильное приложение. - Получите доступные методы тестирования и спецификацию полей выбранного алгоритма.
- Отправьте профиль спортсмена и замеры на расчёт. Сервис вернёт диагноз и сформированный план.
- Покажите спортсмену диагностику и план, затем отправляйте feedback по выполненным сессиям.
Для серверной интеграции секрет выдаёт администратор; храните его только на своём backend/BFF. Для мобильного клиента используйте установочный ключ и DPoP.
Методы API: назначение и параметры
Все бизнес-методы ниже требуют токен из раздела «Аутентификация». Запросы с JSON-телом отправляются с Content-Type: application/json.
OpenAPI JSON — машинное описание методов и форматов данных
1. Зарегистрировать мобильную установку
POST /auth/public/installations
Создаёт или обновляет установку приложения и выдаёт одноразовый challenge. client_secret для этого сценария не нужен.
| Поле | Где | Значение |
|---|---|---|
client_id | JSON | Публичный идентификатор интеграции, выданный ClimbingMetrics. |
public_key_jwk | JSON | Публичный ключ установки в формате JWK; используйте EC P-256. Приватный ключ остаётся на устройстве. |
platform | JSON | Платформа приложения, например android или ios (1–20 символов). |
app_version | JSON | Версия приложения (1–40 символов). |
Ответ содержит installation_id, challenge_id, одноразовый challenge и expires_in — срок действия challenge в секундах (300).
2. Получить или обновить токен
POST /auth/token
Один endpoint обслуживает три сценария. Для серверной интеграции передайте только client_id и client_secret, не указывая grant_type. Для первого мобильного входа передайте challenge-поля и подпишите challenge заголовком DPoP; для обновления — grant_type=refresh_token и действующий refresh token.
| Поле | Когда передавать | Значение |
|---|---|---|
client_id | Всегда | Идентификатор интеграции. |
client_secret | Серверный вход | Секрет интеграции. Никогда не встраивайте его в мобильное приложение. |
grant_type | Мобильный сценарий | urn:climbest:params:oauth:grant-type:installation_challenge для первого входа; refresh_token для обновления. |
installation_id | Мобильный сценарий | Идентификатор установки из регистрации. |
challenge_id | Первый мобильный вход | ID challenge из регистрации. Сам challenge подписывается в заголовке DPoP. |
refresh_token | Обновление | Текущий refresh token; после успешного обмена сохраните новый, так как токен ротируется. |
Успешный ответ возвращает access_token, token_type, expires_in и service_name; в мобильном сценарии также installation_id и refresh_token.
3. Узнать поля алгоритма
GET /api/v1/algorithms/help?version=EK-LP.1.0
Возвращает спецификацию полей для выбранной версии алгоритма: названия, типы, обязательность и описание. Это справка о данных, которые передаются при диагностике.
| Параметр | Где | Значение |
|---|---|---|
version | Query, обязателен | Версия алгоритма, включённая для вашей интеграции, например EK-LP.1.0 (1–40 символов). |
4. Получить каталог raw-тестов
GET /api/v1/algorithms/test-methods
Возвращает доступные методики расчёта, требования к числу попыток и длительности, единицы и версии контракта. Параметров запроса и тела нет.
В ответе methods перечисляет методики, а schema_version задаёт формат raw-данных для следующего метода.
5. Рассчитать результат raw-теста
POST /api/v1/algorithms/calculate-test
Проверяет и рассчитывает один необработанный захват датчика. Тело строго проверяется: неизвестные поля и неверные единицы отклоняются.
| Поле | Значение |
|---|---|
schema_version | Формат захвата; сейчас raw-measurements-v2. |
session_id | Идентификатор тестовой сессии на стороне клиента. |
test_key, calculation_method | Ключ теста и методика из каталога test-methods. |
side | Сторона измерения: left или right. |
force_unit | Единица силы; сейчас допустимо только kg. |
context | Контекст замера: measured_at (дата-время с часовым поясом), необязательный bodyweight_kg, а также setup. |
context.setup | Настройка теста: edge_mm — ширина зацепа (14/20 мм либо null); pinch_width_mm — ширина щипка (40/60 мм либо null); grip — тип хвата (half_crimp, open_hand, pinch); position — положение тела/датчика; device_id — ID устройства. |
attempts[] | Попытки (от 1 до 24): attempt — номер попытки; started_at_us и ended_at_us — начало и конец интервала в микросекундах; samples — её отсчёты датчика. |
samples[] | Отсчёт датчика: seq — возрастающий номер отсчёта; t_us — время в микросекундах; force_kg — измеренная сила в килограммах. |
sensor_metadata, quality, derived | Метаданные датчика, показатели качества и необязательные клиентские вычисления. Первые два могут быть пустыми; derived может быть null. |
Ответ содержит рассчитанные значения и результат проверки захвата. Точный JSON-формат полей доступен в OpenAPI и каталоге методик.
6. Передать профиль и замеры, получить диагностику и план
POST /api/v1/recommendations/{athlete_id}/enter-tests
Создаёт или обновляет карточку спортсмена по данным вашей интеграции, сохраняет замеры и запускает выбранный алгоритм.
| Поле | Где | Значение |
|---|---|---|
athlete_id | Path | Стабильный ID карточки, используемый вашей интеграцией. Для повторных отправок передавайте тот же ID. |
algorithm_version | JSON | Версия алгоритма, например EK-LP.1.0. |
athlete | JSON object | Профиль: id — тот же ID, что в пути; external_user_id — ваш стабильный ID спортсмена; service_id — ID интеграции, должен соответствовать выданному сервису; age — возраст в годах (0–120); height_cm — рост в сантиметрах; bodyweight — масса тела; first_name/last_name — необязательные имя и фамилия; sex — female, male или unspecified. |
measurements | JSON object | Результаты тестов. Обязательный минимум: Fmax и critical force для обеих рук, bodyweight, power-lift и RFD для обеих рук, pinch 40/60, а также TD для обеих рук (или соответствующие поля td_*_no_extrap). Единицы и остальные поля сверяйте через /algorithms/help. |
optional | JSON object | Необязательный контекст для рекомендаций: травмы и ограничения, основная цель, дисциплины и частота тренировок. |
Ответ включает сохранённый результат диагностики и сформированный тренировочный план. Используйте его как источник данных для экрана спортсмена.
7. Получить версии плана спортсмена
GET /api/v1/training-plans/{athlete_id}?limit=20
| Параметр | Где | Значение |
|---|---|---|
athlete_id | Path | Внутренний ID карточки или ваш external_user_id. |
limit | Query, необязателен | Максимум версий в ответе; по умолчанию 20, фактический диапазон 1–100. Сначала идут новые версии. |
8. Отправить отзыв о занятии по плану
POST /api/v1/training-plans/id/{plan_id}/feedback
Сохраняет обратную связь о выполненной сессии; она может повлиять на дальнейшие занятия.
| Поле | Где | Значение |
|---|---|---|
plan_id | Path | ID плана из ответа API. |
session_id | JSON | ID занятия из этого плана. |
injury | JSON, необязательно | Информация о травме: active_injury, область body_region и сторона side. |
comment | JSON, необязательно | Текстовый отзыв (до 2000 символов). |
exercise_feedback | JSON array, необязательно | Оценки упражнений: exercise_id, сложность difficulty от 1 до 11 и необязательный комментарий. |
Аутентификация
Серверный сценарий: отправьте client_id и client_secret на POST /auth/token, затем передавайте полученный токен как Authorization: Bearer ….
Мобильный сценарий: создайте ECDSA P-256 ключ в защищённом хранилище устройства, зарегистрируйте public key на POST /auth/public/installations, подпишите одноразовый challenge и обменяйте его на токены через POST /auth/token. Каждый business-запрос отправляется с Authorization: DPoP … и отдельным заголовком DPoP, подписанным для точных метода и URL запроса. Access token обновляется через refresh grant; refresh token ротируется при обмене.
Service JWT и установка имеют tenant scope: сервис может читать и менять только свои данные. Каждая анкета идентифицируется стабильным external_user_id; не используйте имя спортсмена как идентификатор.
Ответы бизнес-методов используют envelope {"data": ..., "error": ...}. Ошибки HTTP-валидации могут иметь FastAPI-формат detail. Лимиты действуют и по IP, и по интеграции; при HTTP 429 учитывайте Retry-After.