Открытый API и вебхуки
Кто работает: администратор системы. Раздел есть, если подключён модуль «Открытый API и вебхуки».
Открытый API связывает систему с тем, что у вас уже есть:
- свой сайт или приложение - запись клиентов на вашем сайте со своим дизайном;
- 1С, своя аналитика, другие системы - выгрузка записей и клиентов, синхронизация изменений;
- вебхуки - ваш сервер сразу узнаёт, что в системе создали, перенесли или отменили запись, завели или изменили клиента.
API - инструмент для программиста: сам модуль ничего ни с чем не связывает. Интеграцию пишет ваш разработчик по документации API, а вы выпускаете ему ключ и настраиваете вебхуки.
Что понадобится
- модуль «Открытый API и вебхуки» в подписке;
- разработчик, который напишет интеграцию;
- роль для интеграции с нужными правами (см. Роли и права). Ключ видит и меняет ровно то, что разрешено его роли: например, роль с правом читать и создавать записи, но без доступа к клиентам. Заведите для интеграции отдельную роль - не давайте ключу роль с полным доступом.
Страница «API и вебхуки»
Откройте «Настройки» → «API и вебхуки» (рис. 1).

Рис. 1. API и вебхуки
В блоке «Подключение» - адрес API (кнопка «Скопировать») и ссылка на документацию - передайте их разработчику. Там же лимит: сколько запросов в минуту можно сделать одним ключом. Адрес строится от публичного адреса системы (см. Настройки системы).
Выпустить ключ
- В блоке «Ключи доступа» нажмите «Выпустить ключ» (рис. 2).
- Укажите «Название» - так действия ключа подписаны в журнале изменений: «API: Синхронизация с 1С». «Описание» - по желанию.
- Выберите «Роль». Если у роли полный доступ, окно предупредит.
- По желанию укажите «Действует до»: если ключ утечёт, после этой даты он перестанет работать сам. Пусто - бессрочно.
- Нажмите «Выпустить».

Рис. 2. Новый ключ API
Ключ показывается один раз (рис. 3): нажмите «Скопировать» и передайте его разработчику. Потом его не увидит никто, даже администратор, - можно только выпустить новый. Если закрыть окно, не скопировав ключ, система переспросит.

Рис. 3. Ключ выпущен
В списке ключей (рис. 4) видно роль, срок и когда и с какого адреса ключом пользовались последний раз. «Изменить» - сменить название, описание, роль или срок. «Отозвать» выключает ключ сразу: интеграции с ним перестают работать. Вернуть отозванный ключ нельзя - только выпустить новый.

Рис. 4. Ключи доступа
Где хранить ключ. Только на сервере интеграции. В коде сайта, который открывается в браузере, ключа быть не должно - его увидит любой посетитель. Поэтому из браузера API и не работает.
Документация для разработчика
Кнопка «Документация API» открывает описание всех запросов: что принимают и что возвращают (рис. 5). Там же разработчик может попробовать запрос со своим ключом.

Рис. 5. Документация API
Что важно разработчику (подробно - в документации): ключ передаётся в заголовке Authorization: Bearer stk_…; время - в UTC; создание записи и клиента можно безопасно повторить с заголовком Idempotency-Key - повтор не создаст вторую запись; записи создаются только в свободное время из расписания; запрос GET /api/v1/me показывает, какой ключ и роль используются.
Вебхуки
Вебхук - запрос на адрес вашего сервера, когда в системе что-то произошло.
- В блоке «Вебхуки» нажмите «Добавить подписку» (рис. 6).
- Укажите название и «Адрес» - полный адрес
https://…на вашем сервере. Адреса внутренней сети не принимаются. - Отметьте события, о которых сообщать.
- Нажмите «Сохранить». Подписка откроется сохранённой - с секретом подписи (рис. 7). Скопируйте его и передайте разработчику: по нему сервер проверяет, что запрос пришёл от системы и не изменён по дороге.

Рис. 6. Новая подписка

Рис. 7. Секрет подписи
| Событие | Когда приходит |
|---|---|
| Запись создана | Новая запись из любого источника |
| Запись подтверждена / отменена / перенесена | Смена статуса, другое время или специалист |
| Визит состоялся / Клиент не пришёл | Отметка о визите |
| Заявку не подтвердили в срок | Заявка сгорела |
| Клиент создан / изменён | Новая карточка; правка ФИО, телефонов, почты, тегов; удаление персональных данных |
Кнопка «Проверить» в строке подписки сразу отправляет проверочное событие и показывает, что ответил ваш сервер. «Сменить секрет» в подписке выдаёт новый секрет - старый перестаёт подходить сразу. Выключить подписку на время - переключатель «Подписка включена».
Журнал доставок
В журнале видно каждую доставку: событие, подписку, состояние, число попыток и ответ вашего сервера (рис. 8). Сверху можно выбрать подписку и состояние. Нажмите на строку - откроется, что именно было отправлено (рис. 9).

Рис. 8. Журнал доставок

Рис. 9. Доставка вебхука
- «Доставлено» - ваш сервер принял событие.
- «Ждёт отправки» - сервер не ответил или ответил ошибкой; система повторит отправку в «Следующая попытка», с нарастающей паузой - около суток.
- «Не доставлено» - все попытки исчерпаны. Когда сервер заработает, нажмите «Отправить ещё раз».
«Отправить ещё раз» работает и для доставленного события - если ваш сервер его потерял.
Частые вопросы
| Что видно | Причина и что делать |
|---|---|
| Интеграция получает ответ 401 | Ключ неверный, отозван или его срок вышел. Выпустите новый ключ. |
| Ответ 403 «Недостаточно прав» | У роли ключа нет права на этот раздел. Добавьте право роли или выберите в ключе другую роль. |
| Ответ 403 «Модуль не подключён» | Модуль «Открытый API и вебхуки» не входит в подписку. |
| Ответ 429 | Превышен лимит запросов в минуту на ключ. Интеграции нужно делать запросы реже. |
| Ответ 409 при создании записи | Время занято или его нет в расписании. Разработчику нужно заново запросить свободное время. |
| Адрес вебхука не сохраняется | Адрес должен начинаться с https:// и вести на сервер в интернете. |
| «Проверить» показывает «Не доставлено» | Ваш сервер недоступен или ответил ошибкой - причина видна в сообщении. |
| Ключ потерян | Выпустите новый и отзовите старый. |
См. также
Не нашли ответ? Напишите на alert.system@bk.ru или в «Поддержку» из системы.