Начало работы

Ключ доступа и права

Чтобы ваша CRM могла работать с API, нужен ключ — секретная строка, по которой лагерь узнаёт ваш отдел. Без ключа API не ответит ни на один запрос.

Как получить ключ

Ключ выдаёт администратор лагеря. Сами завести ключ через API или на сайте нельзя.

Руководитель вашего отдела пишет администратору лагеря

Сообщите:
- какой отдел подключается;
- электронную почту для служебных писем — на неё придёт письмо, если ключ будет отозван или вебхук отключится из-за ошибок. Лучше общий ящик, а не личный адрес сотрудника;
- какие права нужны ключу (см. таблицу ниже). Если CRM будет только смотреть брони — хватит read;
- по желанию — адреса серверов (IP), с которых будет работать CRM. Тогда ключ не сработает ни с какого другого адреса, даже если его украдут.
Администратор заводит подключение и выпускает ключ

Ключ показывается один раз в момент выпуска. Лагерь хранит только его отпечаток и восстановить ключ не может. Потеряли — администратор выпустит новый.
Получите ключ безопасным способом

Не по открытой почте и не в общем чате. Ключ — это пароль от вашего отдела: с ним можно оформлять брони и выставлять счета родителям.
Положите ключ в настройки сервера CRM

В переменную окружения или хранилище секретов. Не в код программы, не в репозиторий, не на сайт.

Ключ выглядит так (здесь вымышленный):

Code
zb_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

zb_live_ и ещё 40 латинских букв и цифр. В списке ключей у администратора виден только начальный кусок (zb_live_XXXX) — по нему вы вместе можете понять, о каком ключе речь.

Как передавать ключ

В каждом запросе — в заголовке Authorization после слова Bearer и пробела:

Code
GET /ext/v1/me HTTP/1.1
Host: partners.zvezdnyy-burabai.edu.kz
Authorization: Bearer zb_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Права ключа

Права (scopes) задаёт администратор лагеря при подключении. Их видно в ответе GET /me. Права общие для всех ключей одного подключения.

Право	Что разрешает
`read`	Читать всё своё: смены, брони, историю брони, семьи, детей, счета, платежи, путёвки (и PDF), отчёты, сверку, ленту событий и веб-сокет. Расчёт стоимости `POST /quote`
`bookings`	Оформлять брони (одну и несколько детей семьи), проверять «можно ли оформить» (`POST /bookings/check`), править, отменять, восстанавливать, переносить, «поселить вместе»; править свои номера и метки семьи и ребёнка, контакты семьи
`invoices`	Выставлять, заменять и отменять счета Kaspi
`webhooks`	Заводить вебхуки, менять, отключать, проверять, смотреть журнал доставок, отправлять события заново

Обычный набор для CRM, которая оформляет брони и выставляет счета: read, bookings, invoices, webhooks.

Нет нужного права — ответ 403 с кодом scope_missing:

Code
{
  "code": "scope_missing",
  "message": "У ключа нет права «invoices». Права выдаёт администратор лагеря",
  "request_id": "r8KfQ2mZx7LpT0aVn3Wd"
}

Ключ действует как менеджер вашего отдела

Всё, что делает ключ, система лагеря записывает в журнал как «через API, подключение такое-то». Ключ может ровно то же, что менеджер вашего отдела в CRM лагеря, и не больше: не видит чужих отделов, не даёт скидку выше потолка смены, не оформляет бронь вопреки запрету. Путёвку выпустить и отметить отправленной ключ не может (это делает руководитель отдела или лагерь), а прочитать её и скачать PDF — может.

Безопасность: что приводит к отзыву ключа

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

Что произошло	Ответ API	Что будет с ключом
Запрос отправлен по `http://` вместо `https://`	`403 https_required`	Отозван: ушёл по сети открытым текстом
Ключ передан в адресе запроса (`?key=zb_live_…`, `?token=…`)	`400 key_in_url`	Отозван: адреса оседают в журналах прокси и истории

После отзыва все запросы с этим ключом получают 401 unauthorized. Попросите у администратора новый ключ и исправьте ошибку в CRM, иначе отзовётся и новый.

Другие правила:

Только с сервера. Запросы из браузера (из кода сайта или страницы CRM, которая открыта у менеджера) закрыты. Ключ не должен попадать на компьютер менеджера — запросы делает сервер вашей CRM.
Список разрешённых адресов. Если администратор задал список IP, запрос с другого адреса получает 403 ip_not_allowed. Поменяли сервер — сообщите лагерю новый адрес заранее.
Подбор ключа. 20 запросов с неверным ключом с одного адреса за 15 минут — адрес блокируется на 15 минут: все запросы с него получают 429 rate_limited, даже с верным ключом.
Срок жизни. Администратор может выпустить ключ со сроком действия. После срока — 401.

Смена ключа без остановки работы

У подключения может быть два действующих ключа одновременно. Так ключ меняют без простоя:

Попросите администратора выпустить второй ключ.
Переключите CRM на новый ключ и проверьте, что запросы идут (GET /me).
Попросите администратора отозвать старый ключ.

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

Если ключ утёк

Сразу сообщите администратору лагеря — он отзовёт ключ за минуту. Пока ключ не отозван, с ним можно оформлять брони вашего отдела и выставлять счета вашим семьям.

Править страницу

Last modified on November 5, 2026

Словарь Первый запрос за 5 минут