API для партнёров: брони и матчи
Агрегатор, бот, сайт или CRM партнёра бронирует корты клуба и получает результаты сыгранных матчей по ключу, который выдаёт клуб. Для разработки есть песочница: тот же API на выдуманных данных, ничего не бронирует по-настоящему.
Что можно
- Узнать клуб, его корты и часы работы.
- Получить свободное время на день: какие корты свободны и цену по сетке клуба.
- Создать бронь и отменить её до начала игры. Бронь оплачивается в клубе: API денег не принимает и не возвращает.
- Видеть свои брони — созданные этим ключом.
- Получать сыгранные матчи клуба: счёт по сетам, победителя и игроков.
Ключ и доступ
- Ключ партнёра выпускает клуб в своей панели управления: раздел «Интеграции», карточка «Ключи партнёров». Ключ показывается один раз — сохраните его сразу. Потеряли — клуб отзовёт его и выпустит новый.
- Ключ передаётся в каждом запросе в заголовке
X-Partner-Key. В адресе запроса ключ не принимается. - Ключ открывает данные только того клуба, который его выдал. Номера клуба в запросах нет: клуб определяется ключом.
- Лимит — число запросов в минуту на ключ; его задаёт клуб, от 10 до 600, по умолчанию 60. Сверх лимита —
429и заголовокRetry-After. - Клуб видит журнал обращений ключа: время, метод, путь, код ответа. Отзыв ключа действует сразу; брони, созданные ключом, остаются у клуба.
| Ключ | Начало | Данные |
|---|---|---|
| Боевой | aipp_ | Настоящие корты, брони и матчи клуба |
| Песочница | aipp_test_ | Выдуманный клуб, три корта, слоты и матчи; брони клуба не трогаются |
Все примеры ниже написаны для адреса https://<адрес API>/api — его сообщает клуб вместе с ключом. Ответы — JSON, дни — ГГГГ-ММ-ДД, время — ЧЧ:ММ по местному времени клуба (часовой пояс — в GET /v1/partner/club).
Песочница
Ключ песочницы отвечает на те же методы теми же полями, но данные выдуманные и постоянные. Удобно начать с него, а боевой ключ подставить, когда интеграция готова.
- Клуб
Sandbox Club, кортыsbx-court-1,sbx-court-2,sbx-court-3, брони по 90 минут с 08:00 до 23:00. - Занятость слотов не меняется: один и тот же корт в одно и то же время всегда занят или всегда свободен. Бронь занятого корта даёт
409 slot_taken— так проверяется обработка отказа. - Бронь в песочнице ничего не занимает и не запоминается: её номер вида
sbx-20261112-1830-1-4f2a9cсодержит день, время и корт. Карточка брони по такому номеру отвечает действующей бронью, отмена — отменённой. - Список своих броней — две примерные брони на завтра и послезавтра, матчи — шесть примерных матчей за прошлую неделю.
- Лимит запросов и журнал обращений работают так же, как у боевого ключа.
Методы
| Метод | Назначение |
|---|---|
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 |
- Бронь сразу действует (
confirmed) и оплачивается гостем в клубе (payment: "at_club"). Цена — по сетке клуба на это время. - Если клуб не принимает оплату в клубе, бронь не создаётся:
403 pay_at_club_disabled. - Будущих неотменённых броней на один ключ — не больше 30:
409 active_limit. - Передавайте
externalRefвсегда: после обрыва связи запрос можно просто повторить.
Свои брони
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: <ключ партнёра>"- По умолчанию — две недели по сегодняшний день, период не больше 92 дней, новые первыми;
limit— от 1 до 500, по умолчанию 100. - Игроки — имя и первая буква фамилии. Телефонов, почты и полных имён API не отдаёт;
name: null— имени нет. - Матч, который скрыл хотя бы один из игроков, не отдаётся вовсе, а по номеру отвечает
404 match_not_found— так же, как отменённый клубом и несуществующий. bookingIdзаполнен, только если матч сыгран по брони этого ключа: так бронь партнёра связывается с результатом.
Отказы
Код отказа — в поле detail ответа, например {"detail": "slot_taken"}.
| Код | detail | Причина |
|---|---|---|
| 401 | no_partner_key | Нет заголовка X-Partner-Key |
| 401 | invalid_partner_key | Ключ неверный или отозван |
| 403 | module_not_enabled | У клуба отключены интеграции; ключ песочницы при этом работает |
| 403 | pay_at_club_disabled | Клуб не принимает оплату в клубе — бронь через API невозможна |
| 400 | bad_slot_time | Такого времени начала нет в сетке клуба |
| 400 | slot_in_past, past_day | Время или день уже прошли |
| 404 | court_not_found | Такого корта у клуба нет или он закрыт для онлайн-записи |
| 404 | booking_not_found | Брони нет или её создал другой ключ |
| 404 | match_not_found | Матча нет, он скрыт игроком или отменён клубом |
| 409 | slot_taken | Время уже занято |
| 409 | too_far_ahead | День дальше, чем клуб открывает запись |
| 409 | active_limit | У ключа уже 30 будущих броней |
| 409 | already_started | Игра по брони уже началась |
| 422 | bad_date_range или список ошибок | Период задан неверно или поле не прошло проверку |
| 429 | rate_limited | Превышен лимит запросов в минуту; повторите через Retry-After секунд |
Описание OpenAPI
Машиночитаемое описание только этих методов: скачать partner-openapi.json. То же описание отдаёт и сам API без ключа: GET /v1/partner/openapi.json, по-английски — с параметром ?lang=en. Файл подходит для Postman и генераторов клиентов.
Чего в версии 1 нет
- Оплаты онлайн: бронь оплачивается в клубе.
- Переноса брони: отмените и создайте новую.
- Отправки событий на адрес партнёра: о новых матчах и отменах партнёр узнаёт запросом.
- Контактов игроков и гостей: ни телефонов, ни почты.