Ученики, балансы и абонементы через API

Поиск карточек учеников своей компании для привязки оплаты. Право students:search директор выдаёт отдельно.

Запрос

GET /api/v2/students/search?phone=%2B79130000000
GET /api/v2/students/search?email=parent%40example.com

Укажите полный телефон или email. Поиск учитывает контакты ученика и доверенных лиц. Если переданы оба параметра, возвращаются совпадения по любому из них. Телефон и email служат для поиска, а оплата всегда направляется на конкретный student_id.

Ответ содержит только id и name. При раздельном балансе дополнительно возвращается groups: gos_id, group_id, name. Контакты, баланс, комментарии и данные входа не возвращаются.

Пример ответа

Пример для денежного общего баланса. Имена и идентификаторы во всех примерах вымышлены.

{
  "data": [
    {"id": 12345, "name": "Анна Примерова"},
    {"id": 12346, "name": "Иван Примеров"}
  ],
  "meta": {
    "current_page": 1,
    "last_page": 1,
    "per_page": 20,
    "total": 2
  }
}

Общий телефон родителя может соответствовать нескольким детям. Предложите выбрать ребёнка, сохраните соответствие на своём сервере и передавайте выбранный id как student_id при оплате. Не выбирайте автоматически первую карточку из списка. Если результат занимает несколько страниц, используйте meta.last_page и параметр page.

Если ничего не найдено, сначала создайте карточку обычным способом в AXKED. Этот метод карточек не создаёт.

Пагинация: page, per_page от 1 до 50, по умолчанию 20; ответ содержит data и meta. Лимит поиска - 30 запросов в минуту на IP.

Связанные инструкции

Получение доступа · Регистрация и проверка оплаты

Чтение данных учеников

Для выгрузки карточек директор отдельно включает students:read. Получите токен с этим правом. Этот доступ позволяет читать персональные данные учеников и доверенных лиц; выдавайте его только доверенному серверу.

GET /api/v2/students?per_page=50
GET /api/v2/students?archived=0&branch_id=10
GET /api/v2/students?group_id=20&after_id=12345
GET /api/v2/students?student_id=12345

Фильтры: student_id, branch_id, group_id, status, archived (0 или 1). Без фильтра архива возвращаются обе категории карточек. Статусы: 0 - новый, 1 - на пробном, 2 - постоянно, 3 - неактивен, 4 - заявка, 5 - в архиве. Признак archived передаётся отдельно от сохранённого статуса.

Карточка содержит id, полное name, first_name, surname, middlename, birthday, branch_id, status, archived, started_at, archived_at, archive_reason, phone, phone2, phone3, email, created_at, updated_at. Даты и причины возвращаются только в сохранённом виде; незаполненные значения не восстанавливаются автоматически.

Контакты и группы ученика

GET /api/v2/students/12345/contacts
GET /api/v2/students/12345/groups
GET /api/v2/students/12345/group-history

Эти методы требуют students:read и используют отдельные страницы. Контакты доверенных лиц: id, confidant_id, name, relationship, phone, phone2, email. Паспортные данные не возвращаются.

Текущие связи с группами: id связи, group_id, branch_id, name группы, status связи (1 - пробное, 2 - активный, 4 - бронирование), start, stop. Удалённые связи ищите в истории, а не в текущем списке.

История содержит id, group_id, type (0 - удаление, 1 - добавление, 2 - бронирование), schedule, date, created_at. При schedule=true запись относится к расписанию, а не ко всей группе. Это сохранённые события; API не достраивает отсутствующие даты зачисления и отчисления.

Балансы и начисления

Требуется отдельно выданное право balances:read.

GET /api/v2/students/12345/balance
GET /api/v2/students/12345/balance-history?date_from=2026-10-01&date_to=2026-10-31

Для общего баланса data содержит student_id, balance_mod, currency, separate_by_group=false, balance, debt, stored_balance, shared_balance, unlimited, valid_until. Если включён единый баланс связанных аккаунтов, balance учитывает связанные карточки этой компании; stored_balance - остаток самой карточки.

При раздельном балансе data - страница остатков по группам: id связи, group_id, balance, debt, unlimited, valid_until. В meta дополнительно передаются student_id, balance_mod, currency, separate_by_group=true и итоговые balance, debt по всем текущим группам ученика, независимо от страницы.

balance_mod: 0 - деньги, 1 - занятия, 2 - часы, 3 - единицы баланса. Остатки возвращаются числами; часы - десятичным числом, например 1.5 означает 1 час 30 минут. debt - величина отрицательного сохранённого остатка (при раздельном балансе - сумма отрицательных остатков). Это не прогноз оплаты будущих занятий. Признаки безлимита и сроки учитывайте отдельно. Запросы не проводят занятия и не пересчитывают начисления.

История баланса требует обе даты, период - до 31 календарного дня включительно. Каждая запись содержит id, date, name, before, change, after, type, target, branch_id, group_id, visit_id, finance_id, abon_of_student_id. change сохраняет знак операции. target: 0 - основной баланс, 1 - бонусный счёт; type: 0 - единицы баланса, 1 - бонусы, 2 - индивидуальные тренировки. Не складывайте разные виды остатков как денежные суммы.

Купленные абонементы и пакеты

Требуется право subscriptions:read.

GET /api/v2/students/12345/subscriptions
GET /api/v2/students/12345/balance-packages

Абонементы возвращаются постранично, включая истёкшие, но без удалённых. Общие абонементы, явно предоставленные этому ученику, тоже включаются; student_id указывает владельца покупки. Поля: id, student_id, abon_id, name, group_id, start, stop, remaining, count, unit (lessons или hours), unlimited, sum, created_at. При безлимите не трактуйте числовой остаток как ограничение.

Оформленные покупки пакетов баланса возвращают id, balance_package_id, name, start, stop, active, cost, created_at. У такого пакета нет счётчика занятий: он задаёт тарифы на свой срок. В список входят и покупки с разделённой оплатой; наличие записи не подтверждает полную оплату. Для определения действия пакета проверяйте и active, и даты.

Страницы выгрузки и ограничения

Все новые списки используют per_page от 1 до 50 (по умолчанию 20) и after_id. Начните без after_id; пока meta.has_more=true, передавайте meta.next_after_id в следующий запрос с теми же фильтрами. Пример формы ответа:

{"data": [], "meta": {"per_page": 20, "has_more": false, "next_after_id": null}}

after_id используется для перехода к следующей странице, а не для отслеживания изменений. Для повторной полной выгрузки начинайте без него. Страницы отражают текущее состояние на момент отдельных запросов, а не единый неизменяемый снимок. Удалённые записи не выдаются; их учёт и сравнение выгрузок выполняет ваша система.

Все новые методы чтения вместе ограничены 30 запросами в минуту на подключение и 60 запросами в минуту на компанию. Запрашивайте страницы последовательно: одновременно выполняется одна такая выгрузка компании. При 429 дождитесь времени из Retry-After и повторите запрос; не запускайте немедленные повторы. Общий лимит API также продолжает действовать. Лимиты относятся к новым методам; прежний поиск для оплаты сохраняет свой контракт.