API AISOLUS Падел

Базовый адрес

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

https://адрес-вашего-сервера/api

Пути в справочнике начинаются с версии: например, полный адрес списка клубов — https://адрес-вашего-сервера/api/v1/clubs. Обмен — HTTPS и JSON в кодировке UTF-8; даты — YYYY-MM-DD, время — HH:MM, моменты времени — ISO 8601, суммы — целые рубли.

Проверка доступности: GET https://адрес-вашего-сервера/api/v1/health отвечает {"status": "ok", "service": "padel-api", …}.

Виды доступа

У каждого метода в справочнике облака указан вид доступа. Их пять; шестой — ключ интеграции — действует на сервере корта.

Токен игрока: вход по SMS

Игрок входит по номеру телефона. Облако присылает код в SMS, код меняется на пару токенов: короткий токен доступа и долгий токен обновления.

# 1. Запросить код (российский номер: +7…, 8… или 10 цифр)
curl -X POST "https://адрес-вашего-сервера/api/v1/auth/phone" \
  -H "Content-Type: application/json" \
  -d '{"phone": "+79000000001"}'
# → {"ok": true, "ttl_min": 5}

# 2. Обменять код из SMS на токены
curl -X POST "https://адрес-вашего-сервера/api/v1/auth/verify" \
  -H "Content-Type: application/json" \
  -d '{"phone": "+79000000001", "code": "<код из SMS>"}'
# → {"access_token": "…", "refresh_token": "…", "token_type": "bearer",
#    "expires_in": 900, "is_new": false, "user_id": "…"}

# 3. Обновить токен доступа, когда он истёк (старый refresh_token гасится)
curl -X POST "https://адрес-вашего-сервера/api/v1/auth/refresh" \
  -H "Content-Type: application/json" \
  -d '{"refresh_token": "<токен обновления>"}'

• Токен доступа — JWT с подписью RS256; срок жизни приходит в expires_in (в секундах, по умолчанию 900 — 15 минут). Токен обновления по умолчанию живёт 30 дней и при каждом обновлении заменяется новым.
• Код из SMS действует 5 минут; на один код — не больше 5 попыток ввода; на один номер — не больше 5 SMS в час. Превышение — ответ 429 too_many_requests или too_many_attempts.
• Ошибки входа: 400 bad_phone, 400 wrong_code, 400 code_expired, 401 invalid_refresh.
• Выход с устройства: POST /v1/auth/logout с тем же телом, что у обновления, — токен обновления гасится.

Учётка панели клуба

Логин и пароль панели выдаёт клуб или владелец сети. Вход — POST /v1/admin/login с полями login, password и, если у учётки включён второй фактор, code из приложения-аутентификатора; в ответе токен на смену (12 часов). Методы панели клуба в открытый справочник не входят; из опубликованных учётка персонала нужна для POST /v1/matches/{match_id}/score-correction.

Клубный токен сервера корта

Выдаётся на клуб при подключении кортов AISOLUS и показывается один раз: в облаке хранится только его хеш. Повторная выдача заменяет прежний токен. Токен передаётся в заголовке X-Club-Token (имена заголовков не зависят от регистра). Подробно — в руководстве «Сервер корта и облако».

Токен 1С

Один токен на интеграцию, передаётся в заголовке X-1C-Token. Пока токен в облаке не задан, интеграция выключена и все методы отвечают 401 bad_1c_token. Подробно — в руководстве «Интеграция с 1С».

Как получить доступ

Клубный токен, токен 1С и учётки персонала выдаёт менеджер AISOLUS. Обратитесь к администратору вашей платформы: название клуба или компании, что хотите подключить (сервер корта, 1С, сайт или приложение, онлайн-оплату), контакт технического специалиста. Публичные методы и вход игрока по SMS отдельного доступа не требуют.

Формат ответов и ошибок

Успешный ответ — код 200 и JSON. Ошибка — код 4xx или 5xx и JSON с полем detail:

{"detail": "bad_club_token"}
{"detail": {"error": "insufficient_funds", "balance": 1200, "price": 3500}}
{"detail": [{"loc": ["body", "players"], "msg": "…", "type": "…"}]}   // 422 — ошибка проверки тела

• detail — строка-код (bad_club_token, match_not_found) или объект с полем error и подробностями. Ориентируйтесь на код, а не на текст.
• 401 — нет токена или он неверен; 403 — нет прав; 404 — объект не найден или чужой; 409 — конфликт (слот занят, игра завершена); 402 — не хватает денег на кошельке; 422 — тело или параметры не прошли проверку; 429 — слишком часто.
• 500 с {"detail": "internal_error"} — сбой на стороне облака; повторите запрос позже.

Ограничения

• Вызовы из браузера. Облако разрешает запросы из браузера только с собственных доменов AISOLUS. Сайт партнёра должен ходить в API со своего сервера.
• Время жизни токенов. Токен игрока — по умолчанию 15 минут (точное значение — в expires_in), токен обновления — по умолчанию 30 дней, токен учётки панели — 12 часов.
• Размеры пачек. Платежи 1С — до 500 за запрос; траектория розыгрыша — до 400 точек, ударов — до 500; тепловая карта — до 8000 клеток; сетка движения — до 4000 клеток на игрока; уровни игроков — до 16 идентификаторов и 16 телефонов.
• Живой счёт хранится 180 секунд без обновлений.
• Ссылки на видео в карточке матча подписываются на каждый запрос и живут минуты (по умолчанию 15) — не сохраняйте их, а запрашивайте карточку снова.
• Телефоны — только российские номера (+7, 11 цифр).

Карта разделов

Руководства — сценарии интеграции с примерами:

• Интеграция с 1С
• Сервер корта и облако
• Локальный API сервера корта
• Онлайн-оплата через ЮKassa
• Клубы, корты, слоты и брони
• Трансляции и повторы
• Заявки и рейтинг
• Планируемые интеграции

Справочник — 64 методов по разделам:

Статусы интеграций