# Что такое API лагеря

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

## Коротко

Детский лагерь «Звёздный Бурабай» продаёт путёвки через несколько отделов продаж. У вашего отдела
своя CRM (amoCRM, Bitrix24, 1С, самописная — неважно). **API** — это способ, которым ваша CRM сама,
без менеджера лагеря и без ручного переноса данных, разговаривает с системой лагеря:

- узнаёт, какие смены продаются, сколько стоят и сколько мест осталось **у вашего отдела**;
- оформляет бронь на ребёнка — так же, как менеджер лагеря в его CRM;
- отправляет родителю счёт Kaspi на оплату путёвки;
- узнаёт, что родитель оплатил, что бронь снялась из-за неоплаты, что ребёнок заехал в лагерь;
- ведёт базу «своих» семей и детей.

Технически это обычное HTTPS API с запросами и ответами в формате JSON. С ним работает любой язык
программирования и любая CRM, которая умеет отправлять HTTP-запросы.

## Что можно делать через API

| Раздел         | Что можно                                                                                           |
| -------------- | --------------------------------------------------------------------------------------------------- |
| Смены          | Список смен, даты, цены, трансфер, минимальный платёж, срок полной оплаты, свободные места вашего отдела |
| Брони          | Посчитать стоимость, проверить «можно ли оформить», оформить, изменить, отменить, восстановить, перенести на другую смену, «поселить вместе» |
| Счета Kaspi    | Выставить родителю счёт (минимальный платёж, остаток или свою сумму), заменить, отменить, смотреть состояние |
| Платежи        | Смотреть, что и когда оплачено (только чтение)                                                      |
| Возвраты       | Подать заявку на возврат оплаты (одобряет лагерь) — **в подготовке**, см. [Возвраты](/partners/refunds) |
| Своя база      | Семьи и дети вашего отдела, поиск по телефону и ФИО, свои номера записей и метки                     |
| Путёвки        | Статус путёвки и PDF                                                                                |
| Отчёты         | Продажи и квоты по сменам, долги, снятые по неоплате, сверка броней                                 |
| События        | Узнавать обо всех изменениях: опросом, по веб-сокету или вебхуками                                  |

## Чего API не делает

Это так же важно знать заранее, чтобы не строить процессы на том, чего нет:

- **Ваш отдел не принимает деньги.** Платит родитель только счётом Kaspi, который уходит с Kaspi
  лагеря на телефон плательщика. Записать «родитель заплатил наличными» или «перевёл на карту» через
  API нельзя. Сделать бронь бесплатной тоже нельзя.
- **Возврат денег сам по себе не делается.** Вернуть деньги можно только заявкой, которую одобряет
  сотрудник лагеря (возможность в подготовке — см. [Возвраты](/partners/refunds)).
- **Чужие брони и чужие дети не видны.** Вы видите только брони, детей и семьи своего отдела.
  Корпоративные брони (группы от организаций) через API не видны вообще.
- **Скидку выше разрешённой смены дать нельзя.** Потолок — `max_discount` смены. Больше —
  только через администратора лагеря.
- **Обойти правила лагеря нельзя.** Закрытые продажи, исчерпанная квота, ребёнок уже записан на эту
  смену, запрет на ребёнка — API откажет так же, как откажет CRM лагеря менеджеру.
- **Отряды не назначаются через API.** Номер отряда можно только прочитать, когда лагерь его
  назначит.
- **Нет «тренировочного» адреса.** Все запросы идут в боевую систему лагеря: оформленная бронь —
  настоящая бронь, счёт — настоящий счёт родителю.

## Кто за что отвечает

| Кто                     | Что делает                                                                                 |
| ----------------------- | ------------------------------------------------------------------------------------------ |
| Администратор лагеря    | Выдаёт ключ доступа, задаёт права ключа, квоту отдела на смены, список разрешённых адресов |
| Руководитель вашего отдела | Решает, кто у вас отвечает за интеграцию, получает ключ, следит за квотой                |
| Ваш программист         | Подключает CRM к API по этому руководству                                                  |
| Ваши менеджеры          | Работают в своей CRM как обычно — брони и оплаты уходят в лагерь сами                      |
| Лагерь                  | Выставляет счета через свой Kaspi, принимает деньги, назначает отряды, одобряет возвраты   |

## Как читать это руководство

Если вы руководитель — достаточно этой страницы и [Словаря](/partners/glossary).

Если вы программист — идите по порядку:

1. [Словарь](/partners/glossary) — что значат «смена», «квота», «удержание места» и другие слова.
2. [Ключ доступа и права](/partners/access) — как получить ключ и что он позволяет.
3. [Первый запрос за 5 минут](/partners/quickstart) — проверить, что всё работает.
4. [Бронь и оплата по шагам](/partners/booking-and-payment) — главный сценарий целиком.
5. [Счета Kaspi и оплата](/partners/kaspi-invoices) — частичная оплата, замена и отмена счёта,
   юрлица лагеря.
6. [Изменения брони](/partners/booking-changes) — правка, отмена, перенос, несколько детей.
7. [События](/partners/events) и [Вебхуки](/partners/webhooks) — как узнавать об оплатах сразу.
8. [Ошибки](/partners/errors), [Повтор запроса](/partners/idempotency),
   [Лимиты](/partners/limits), [Форматы данных](/partners/formats) — чтобы интеграция не ломалась.

Все адреса API, поля и их типы — в [справочнике API](/api). Руководство объясняет, **как и зачем**
ими пользоваться; справочник — **что именно** отправлять и что придёт в ответ.