ClimbingMetrics
CLIMBINGMETRICS

Public API

Документация для сторонних приложений и сервисов, которые подключаются к ClimbingMetrics.

БЫСТРЫЙ СТАРТ

Production API

https://climbingmetrics.ru

Базовый префикс API: https://climbingmetrics.ru/api/v1

СЦЕНАРИЙ ИНТЕГРАЦИИ

От подключения до плана

  1. Получите учётные данные интеграции в ClimbingMetrics.
  2. Выберите серверную интеграцию по client_id + client_secret или мобильный сценарий public installation с DPoP. Секрет сервиса нельзя помещать в мобильное приложение.
  3. Получите доступные методы тестирования и спецификацию полей выбранного алгоритма.
  4. Отправьте профиль спортсмена и замеры на расчёт. Сервис вернёт диагноз и сформированный план.
  5. Покажите спортсмену диагностику и план, затем отправляйте feedback по выполненным сессиям.

Для серверной интеграции секрет выдаёт администратор; храните его только на своём backend/BFF. Для мобильного клиента используйте установочный ключ и DPoP.

МАРШРУТЫ

Методы API: назначение и параметры

Все бизнес-методы ниже требуют токен из раздела «Аутентификация». Запросы с JSON-телом отправляются с Content-Type: application/json.

OpenAPI JSON — машинное описание методов и форматов данных

1. Зарегистрировать мобильную установку

POST /auth/public/installations

Создаёт или обновляет установку приложения и выдаёт одноразовый challenge. client_secret для этого сценария не нужен.

ПолеГдеЗначение
client_idJSONПубличный идентификатор интеграции, выданный ClimbingMetrics.
public_key_jwkJSONПубличный ключ установки в формате JWK; используйте EC P-256. Приватный ключ остаётся на устройстве.
platformJSONПлатформа приложения, например android или ios (1–20 символов).
app_versionJSONВерсия приложения (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

Возвращает спецификацию полей для выбранной версии алгоритма: названия, типы, обязательность и описание. Это справка о данных, которые передаются при диагностике.

ПараметрГдеЗначение
versionQuery, обязателенВерсия алгоритма, включённая для вашей интеграции, например 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_idPathСтабильный ID карточки, используемый вашей интеграцией. Для повторных отправок передавайте тот же ID.
algorithm_versionJSONВерсия алгоритма, например EK-LP.1.0.
athleteJSON objectПрофиль: id — тот же ID, что в пути; external_user_id — ваш стабильный ID спортсмена; service_id — ID интеграции, должен соответствовать выданному сервису; age — возраст в годах (0–120); height_cm — рост в сантиметрах; bodyweight — масса тела; first_name/last_name — необязательные имя и фамилия; sex — female, male или unspecified.
measurementsJSON objectРезультаты тестов. Обязательный минимум: Fmax и critical force для обеих рук, bodyweight, power-lift и RFD для обеих рук, pinch 40/60, а также TD для обеих рук (или соответствующие поля td_*_no_extrap). Единицы и остальные поля сверяйте через /algorithms/help.
optionalJSON objectНеобязательный контекст для рекомендаций: травмы и ограничения, основная цель, дисциплины и частота тренировок.

Ответ включает сохранённый результат диагностики и сформированный тренировочный план. Используйте его как источник данных для экрана спортсмена.

7. Получить версии плана спортсмена

GET /api/v1/training-plans/{athlete_id}?limit=20
ПараметрГдеЗначение
athlete_idPathВнутренний ID карточки или ваш external_user_id.
limitQuery, необязателенМаксимум версий в ответе; по умолчанию 20, фактический диапазон 1–100. Сначала идут новые версии.

8. Отправить отзыв о занятии по плану

POST /api/v1/training-plans/id/{plan_id}/feedback

Сохраняет обратную связь о выполненной сессии; она может повлиять на дальнейшие занятия.

ПолеГдеЗначение
plan_idPathID плана из ответа API.
session_idJSONID занятия из этого плана.
injuryJSON, необязательноИнформация о травме: active_injury, область body_region и сторона side.
commentJSON, необязательноТекстовый отзыв (до 2000 символов).
exercise_feedbackJSON 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.