Что такое API лагеря
Эта страница — для всех, кто будет связан с подключением: и для программиста, который пишет интеграцию, и для руководителя отдела продаж, который хочет понять, что получит отдел. Здесь нет кода — только что это, зачем и как устроено.
Коротко
Детский лагерь «Звёздный Бурабай» продаёт путёвки через несколько отделов продаж. У вашего отдела своя CRM (amoCRM, Bitrix24, 1С, самописная — неважно). API — это способ, которым ваша CRM сама, без менеджера лагеря и без ручного переноса данных, разговаривает с системой лагеря:
- узнаёт, какие смены продаются, сколько стоят и сколько мест осталось у вашего отдела;
- оформляет бронь на ребёнка — так же, как менеджер лагеря в его CRM;
- отправляет родителю счёт Kaspi на оплату путёвки;
- узнаёт, что родитель оплатил, что бронь снялась из-за неоплаты, что ребёнок заехал в лагерь;
- ведёт базу «своих» семей и детей.
Технически это обычное HTTPS API с запросами и ответами в формате JSON. С ним работает любой язык программирования и любая CRM, которая умеет отправлять HTTP-запросы.
Что можно делать через API
| Раздел | Что можно |
|---|---|
| Смены | Список смен, даты, цены, трансфер, минимальный платёж, срок полной оплаты, свободные места вашего отдела |
| Брони | Посчитать стоимость, проверить «можно ли оформить», оформить, изменить, отменить, восстановить, перенести на другую смену, «поселить вместе» |
| Счета Kaspi | Выставить родителю счёт (минимальный платёж, остаток или свою сумму), заменить, отменить, смотреть состояние |
| Платежи | Смотреть, что и когда оплачено (только чтение) |
| Возвраты | Подать заявку на возврат оплаты (одобряет лагерь) — в подготовке, см. Возвраты |
| Своя база | Семьи и дети вашего отдела, поиск по телефону и ФИО, свои номера записей и метки |
| Путёвки | Статус путёвки и PDF |
| Отчёты | Продажи и квоты по сменам, долги, снятые по неоплате, сверка броней |
| События | Узнавать обо всех изменениях: опросом, по веб-сокету или вебхуками |
Чего API не делает
Это так же важно знать заранее, чтобы не строить процессы на том, чего нет:
- Ваш отдел не принимает деньги. Платит родитель только счётом Kaspi, который уходит с Kaspi лагеря на телефон плательщика. Записать «родитель заплатил наличными» или «перевёл на карту» через API нельзя. Сделать бронь бесплатной тоже нельзя.
- Возврат денег сам по себе не делается. Вернуть деньги можно только заявкой, которую одобряет сотрудник лагеря (возможность в подготовке — см. Возвраты).
- Чужие брони и чужие дети не видны. Вы видите только брони, детей и семьи своего отдела. Корпоративные брони (группы от организаций) через API не видны вообще.
- Скидку выше разрешённой смены дать нельзя. Потолок —
max_discountсмены. Больше — только через администратора лагеря. - Обойти правила лагеря нельзя. Закрытые продажи, исчерпанная квота, ребёнок уже записан на эту смену, запрет на ребёнка — API откажет так же, как откажет CRM лагеря менеджеру.
- Отряды не назначаются через API. Номер отряда можно только прочитать, когда лагерь его назначит.
- Нет «тренировочного» адреса. Все запросы идут в боевую систему лагеря: оформленная бронь — настоящая бронь, счёт — настоящий счёт родителю.
Кто за что отвечает
| Кто | Что делает |
|---|---|
| Администратор лагеря | Выдаёт ключ доступа, задаёт права ключа, квоту отдела на смены, список разрешённых адресов |
| Руководитель вашего отдела | Решает, кто у вас отвечает за интеграцию, получает ключ, следит за квотой |
| Ваш программист | Подключает CRM к API по этому руководству |
| Ваши менеджеры | Работают в своей CRM как обычно — брони и оплаты уходят в лагерь сами |
| Лагерь | Выставляет счета через свой Kaspi, принимает деньги, назначает отряды, одобряет возвраты |
Как читать это руководство
Если вы руководитель — достаточно этой страницы и Словаря.
Если вы программист — идите по порядку:
- Словарь — что значат «смена», «квота», «удержание места» и другие слова.
- Ключ доступа и права — как получить ключ и что он позволяет.
- Первый запрос за 5 минут — проверить, что всё работает.
- Бронь и оплата по шагам — главный сценарий целиком.
- Счета Kaspi и оплата — частичная оплата, замена и отмена счёта, юрлица лагеря.
- Изменения брони — правка, отмена, перенос, несколько детей.
- События и Вебхуки — как узнавать об оплатах сразу.
- Ошибки, Повтор запроса, Лимиты, Форматы данных — чтобы интеграция не ломалась.
Все адреса API, поля и их типы — в справочнике API. Руководство объясняет, как и зачем ими пользоваться; справочник — что именно отправлять и что придёт в ответ.