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

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

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

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

<Stepper>

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

   Сообщите:

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

2. **Администратор заводит подключение и выпускает ключ**

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

3. **Получите ключ безопасным способом**

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

4. **Положите ключ в настройки сервера CRM**

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

</Stepper>

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

```
zb_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
```

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

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

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

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

## Права ключа

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

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

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

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

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

:::note{title="Ключ действует как менеджер вашего отдела"}

Всё, что делает ключ, система лагеря записывает в журнал как «через 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`.

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

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

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

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

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

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