AI ПаделДокументация API На сайт

API для партнёров: брони и матчи

Агрегатор, бот, сайт или CRM партнёра бронирует корты клуба и получает результаты сыгранных матчей по ключу, который выдаёт клуб. Для разработки есть песочница: тот же API на выдуманных данных, ничего не бронирует по-настоящему.

Что можно

Ключ и доступ

КлючНачалоДанные
Боевойaipp_Настоящие корты, брони и матчи клуба
Песочницаaipp_test_Выдуманный клуб, три корта, слоты и матчи; брони клуба не трогаются

Все примеры ниже написаны для адреса https://<адрес API>/api — его сообщает клуб вместе с ключом. Ответы — JSON, дни — ГГГГ-ММ-ДД, время — ЧЧ:ММ по местному времени клуба (часовой пояс — в GET /v1/partner/club).

Песочница

Ключ песочницы отвечает на те же методы теми же полями, но данные выдуманные и постоянные. Удобно начать с него, а боевой ключ подставить, когда интеграция готова.

Методы

МетодНазначение
GET /v1/partner/clubКлуб: название, адрес, часовой пояс, часы работы, длительность брони, глубина записи
GET /v1/partner/courtsКорты, открытые для онлайн-записи
GET /v1/partner/slotsСвободное время на день и цена
POST /v1/partner/bookingsСоздать бронь
GET /v1/partner/bookingsСвои брони за период
GET /v1/partner/bookings/{id}Одна своя бронь
POST /v1/partner/bookings/{id}/cancelОтменить свою бронь
GET /v1/partner/matchesСыгранные матчи клуба за период
GET /v1/partner/matches/{id}Результат одного матча

Клуб и корты

curl "https://<адрес API>/api/v1/partner/club" -H "X-Partner-Key: <ключ партнёра>"
# → {"id": "c1", "name": "Падел Клуб", "address": "…", "timeZone": "Europe/Moscow",
#    "openFrom": "08:00", "openTo": "23:00", "slotMinutes": 90, "bookingDepthDays": 14, "sandbox": false}

curl "https://<адрес API>/api/v1/partner/courts" -H "X-Partner-Key: <ключ партнёра>"
# → [{"id": "7d1e3b5a-…", "name": "Корт 1", "indoor": true, "sport": "padel"}, …]

bookingDepthDays — на сколько дней вперёд клуб открывает запись. sport — padel, tennis, pickleball, squash или badminton.

Свободное время

curl "https://<адрес API>/api/v1/partner/slots?day=2026-11-12" -H "X-Partner-Key: <ключ партнёра>"
# → {"day": "2026-11-12", "durationMin": 90, "items": [
#      {"time": "17:00", "freeCourtIds": ["7d1e3b5a-…", "c02f…"], "price": 4500},
#      {"time": "18:30", "freeCourtIds": ["c02f…"], "price": 4500}, …]}
ПараметрЧто это
dayДень; по умолчанию сегодня. От сегодняшнего дня до bookingDepthDays вперёд
court_idТолько этот корт

В списке — только время, где свободен хотя бы один корт; прошедшее время сегодняшнего дня не отдаётся. Цена — по сетке клуба в его валюте, как в приложении игрока.

Создать бронь

curl -X POST "https://<адрес API>/api/v1/partner/bookings" \
  -H "X-Partner-Key: <ключ партнёра>" -H "Content-Type: application/json" \
  -d '{"day": "2026-11-12", "time": "18:30", "courtId": "c02f…",
       "customerName": "Мария", "externalRef": "order-1042"}'
# → {"id": "b71c2e94-…", "courtId": "c02f…", "court": "Корт 2", "day": "2026-11-12", "start": "18:30",
#    "durationMin": 90, "status": "confirmed", "price": 4500, "payment": "at_club",
#    "customerName": "Мария", "externalRef": "order-1042", "duplicate": false, "sandbox": false}
ПолеЧто это
day, timeДень и начало — одно из времён из GET /v1/partner/slots
courtIdКорт; не указан — первый свободный
customerNameИмя гостя для администратора клуба, до 80 знаков. Телефон и почту API не принимает
externalRefНомер брони у партнёра: латиница, цифры, . _ : -, до 64 знаков. Повтор запроса с тем же номером не создаёт вторую бронь — вернётся первая с "duplicate": true

Свои брони

curl "https://<адрес API>/api/v1/partner/bookings?date_from=2026-11-11&date_to=2026-11-25" \
  -H "X-Partner-Key: <ключ партнёра>"
# → [{"id": "b71c2e94-…", "day": "2026-11-12", "start": "18:30", "status": "confirmed", …}, …]

curl "https://<адрес API>/api/v1/partner/bookings/b71c2e94-…" -H "X-Partner-Key: <ключ партнёра>"

Список — по дню игры, по умолчанию две недели с сегодняшнего дня, период не больше 92 дней. Видны только брони, созданные этим ключом; брони клуба из других источников не отдаются. Бронь, которую отменил клуб, приходит со статусом cancelled.

Отменить бронь

curl -X POST "https://<адрес API>/api/v1/partner/bookings/b71c2e94-…/cancel" \
  -H "X-Partner-Key: <ключ партнёра>"
# → {"id": "b71c2e94-…", "status": "cancelled", …}

Отменить можно свою бронь до начала игры; после начала — 409 already_started. Повтор отмены ничего не меняет и отвечает той же бронью. Денег бронь не брала, поэтому возврата нет. Корт сразу снова свободен.

Матчи и результат

curl "https://<адрес API>/api/v1/partner/matches?date_from=2026-11-01&date_to=2026-11-11&limit=50" \
  -H "X-Partner-Key: <ключ партнёра>"
# → [{"id": "5e0b…", "day": "2026-11-10", "start": "18:30", "courtId": "c02f…", "court": "Корт 2",
#     "sets": [{"team1": 6, "team2": 4}, {"team1": 3, "team2": 6}, {"team1": 7, "team2": 5}],
#     "winnerTeam": 1,
#     "players": [{"team": 1, "name": "Анна И."}, {"team": 1, "name": "Борис П."},
#                 {"team": 2, "name": "Вера"}, {"team": 2, "name": null}],
#     "bookingId": "b71c2e94-…"}, …]

curl "https://<адрес API>/api/v1/partner/matches/5e0b…" -H "X-Partner-Key: <ключ партнёра>"

Отказы

Код отказа — в поле detail ответа, например {"detail": "slot_taken"}.

КодdetailПричина
401no_partner_keyНет заголовка X-Partner-Key
401invalid_partner_keyКлюч неверный или отозван
403module_not_enabledУ клуба отключены интеграции; ключ песочницы при этом работает
403pay_at_club_disabledКлуб не принимает оплату в клубе — бронь через API невозможна
400bad_slot_timeТакого времени начала нет в сетке клуба
400slot_in_past, past_dayВремя или день уже прошли
404court_not_foundТакого корта у клуба нет или он закрыт для онлайн-записи
404booking_not_foundБрони нет или её создал другой ключ
404match_not_foundМатча нет, он скрыт игроком или отменён клубом
409slot_takenВремя уже занято
409too_far_aheadДень дальше, чем клуб открывает запись
409active_limitУ ключа уже 30 будущих броней
409already_startedИгра по брони уже началась
422bad_date_range или список ошибокПериод задан неверно или поле не прошло проверку
429rate_limitedПревышен лимит запросов в минуту; повторите через Retry-After секунд

Описание OpenAPI

Машиночитаемое описание только этих методов: скачать partner-openapi.json. То же описание отдаёт и сам API без ключа: GET /v1/partner/openapi.json, по-английски — с параметром ?lang=en. Файл подходит для Postman и генераторов клиентов.

Чего в версии 1 нет