API и MCP-сервер

easygym предлагает REST API для сайтов, приложений и скриптов и MCP-сервер для AI-ассистента, который поддерживает Model Context Protocol. Оба живут по адресу админки: REST API — под /v1, MCP-сервер — на /mcp. Полные адреса вашей установки показывает вкладка «API» в «Настройках».

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

1. 1Откройте «Настройки» → «API». Создавать ключи могут владелец клуба, администраторы и свои роли с полным доступом к «Настройкам».
2. 2В блоке «Создать ключ» укажите «Название» — например, для какой интеграции он — и отметьте нужные «Области доступа».
3. 3Нажмите «Создать ключ» и сразу скопируйте ключ: он показывается один раз. easygym хранит только его хеш.
4. 4Передавайте его в каждом запросе заголовком Authorization: Bearer, за которым следует ключ.

Список «Ключи доступа» показывает название ключа, его видимое начало (ec_sk_live_ и несколько символов), области и «Последнее использование». «Отозвать» выключает ключ сразу — даже когда админка только для чтения. Сами ключи не истекают, поэтому отзывайте те, что больше не нужны. Поддержка easygym не может выдавать ключи даже в режиме поддержки.

Область имеет вид ресурс:действие, и право на запись включает чтение того же ресурса. «Области доступа» в форме ключа предлагают ровно те области, которые проверяют REST API и MCP-сервер:

• contacts:read — список контактов, а через MCP — поиск участника и сводка по нему.
• classes:read — расписание со свободными местами.
• bookings:read — список записей.
• bookings:write — запись участника на занятие.
• analytics:read — показатели клуба через MCP.

У ключа, созданного раньше, в списке могут быть и другие области. Ни один эндпоинт и ни один инструмент их не требует, а с областями выше ключ продолжает работать.

• GET /v1/contacts (contacts:read): контакты не из архива — id, uuid, имя и фамилия, почта, телефон, тип и дата регистрации.
• GET /v1/classes (classes:read): занятия — id, uuid, название, начало и конец, вместимость, цена без налога, зона, филиал, число записей и свободные места. Необязательные параметры from и to ограничивают время начала.
• GET /v1/bookings (bookings:read): записи — id, uuid, uuid участника, название занятия, начало и конец, статус, состояние оплаты и цена.
• POST /v1/bookings (bookings:write): записывает участника на занятие; в JSON-теле — contactUuid и classUuid.

Списки отдаются страницами. Параметр limit задаёт размер страницы — по умолчанию 25, максимум 100. В ответе есть data и nextCursor; передайте nextCursor обратно параметром cursor, чтобы получить следующую страницу, пока он не станет null. Даты — строки ISO 8601.

POST /v1/bookings работает по той же логике записи, что и личный кабинет, и ключ не может обойти правила записи. Если занятие покрывает абонемент участника, используется он; если ни один не покрывает, запись создаётся неоплаченной по цене занятия. Заполненное занятие ставит участника в лист ожидания, если лист ожидания у занятия не выключен. Участника, который уже записан на занятие или стоит в его листе ожидания, второй раз не записывают, поэтому повтор запроса не создаёт дубль.

• 201 с data.status booked и data.bookingId либо waitlisted и data.waitlistEntryId.
• 409 already_booked: участник уже записан на это занятие или стоит в его листе ожидания.
• 409 class_full: занятие заполнено, а лист ожидания у него выключен.
• 409 class_closed: занятие отменено или уже прошло.
• 409 policy_blocked: запись не разрешают правила — например, окно записи закрыто или у участника нет доступа к онлайн-филиалу.
• 404 contact_not_found или class_not_found: такого uuid в этом клубе нет.
• 400 invalid_body или missing_fields: тело не JSON или в нём нет contactUuid или classUuid.

MCP-сервер говорит на JSON-RPC 2.0 поверх HTTP POST: один запрос — один JSON-ответ, версия протокола 2025-06-18. initialize и tools/list работают без ключа; для tools/call нужен ключ в заголовке Authorization с областью инструмента. Результат приходит текстом и в structuredContent; неудачная проверка ключа возвращает ошибку JSON-RPC с кодом -32001. Запись, в которой book_class отказывает, возвращается ошибкой инструмента (isError) с тем же кодом, что и в REST API, — например, already_booked или class_full.

• list_classes (classes:read): ближайшие занятия с числом записей; limit до 50, по умолчанию 10.
• find_member (contacts:read): поиск по имени, телефону, почте или коду чекина.
• member_summary (contacts:read): по contactUuid — абонементы участника, записи на сегодня и сумма долга.
• club_metrics (analytics:read): последние 30 дней, как на экране «Аналитика»: активная база, новые и ушедшие участники, отток, quick ratio и индекс посещаемости.
• book_class (bookings:write): запись участника на занятие по той же логике, что у POST /v1/bookings.

• До 100 запросов в минуту на клуб: запросы REST и вызовы инструментов MCP по всем его ключам считаются вместе. Счёт начинается заново в начале каждой минуты; сверх лимита API отвечает 429 rate_limited с заголовком Retry-After — сколько секунд осталось до следующей минуты.
• Ошибки приходят в JSON с error.code и error.message: 401 с unauthorized, malformed, unknown, revoked или expired при проблемах с ключом и 403 scope, если у ключа нет нужной области.
• Когда админка только для чтения из-за неоплаченного счёта easygym, чтение работает, а запись отвечает 403 read_only.