CRM Стэкум

Открытый API и вебхуки

Кто работает: администратор системы. Раздел есть, если подключён модуль «Открытый API и вебхуки».

Открытый API связывает систему с тем, что у вас уже есть:

  • свой сайт или приложение - запись клиентов на вашем сайте со своим дизайном;
  • 1С, своя аналитика, другие системы - выгрузка записей и клиентов, синхронизация изменений;
  • вебхуки - ваш сервер сразу узнаёт, что в системе создали, перенесли или отменили запись, завели или изменили клиента.

API - инструмент для программиста: сам модуль ничего ни с чем не связывает. Интеграцию пишет ваш разработчик по документации API, а вы выпускаете ему ключ и настраиваете вебхуки.

Что понадобится

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

Страница «API и вебхуки»

Откройте «Настройки» → «API и вебхуки» (рис. 1).

Рис. 1. API и вебхуки

Рис. 1. API и вебхуки

В блоке «Подключение» - адрес API (кнопка «Скопировать») и ссылка на документацию - передайте их разработчику. Там же лимит: сколько запросов в минуту можно сделать одним ключом. Адрес строится от публичного адреса системы (см. Настройки системы).

Выпустить ключ

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

Рис. 2. Новый ключ API

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

Рис. 3. Ключ выпущен

Рис. 3. Ключ выпущен

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

Рис. 4. Ключи доступа

Рис. 4. Ключи доступа

Где хранить ключ. Только на сервере интеграции. В коде сайта, который открывается в браузере, ключа быть не должно - его увидит любой посетитель. Поэтому из браузера API и не работает.

Документация для разработчика

Кнопка «Документация API» открывает описание всех запросов: что принимают и что возвращают (рис. 5). Там же разработчик может попробовать запрос со своим ключом.

Рис. 5. Документация API

Рис. 5. Документация API

Что важно разработчику (подробно - в документации): ключ передаётся в заголовке Authorization: Bearer stk_…; время - в UTC; создание записи и клиента можно безопасно повторить с заголовком Idempotency-Key - повтор не создаст вторую запись; записи создаются только в свободное время из расписания; запрос GET /api/v1/me показывает, какой ключ и роль используются.

Вебхуки

Вебхук - запрос на адрес вашего сервера, когда в системе что-то произошло.

  1. В блоке «Вебхуки» нажмите «Добавить подписку» (рис. 6).
  2. Укажите название и «Адрес» - полный адрес https://… на вашем сервере. Адреса внутренней сети не принимаются.
  3. Отметьте события, о которых сообщать.
  4. Нажмите «Сохранить». Подписка откроется сохранённой - с секретом подписи (рис. 7). Скопируйте его и передайте разработчику: по нему сервер проверяет, что запрос пришёл от системы и не изменён по дороге.
Рис. 6. Новая подписка

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

Рис. 7. Секрет подписи

Рис. 7. Секрет подписи

СобытиеКогда приходит
Запись созданаНовая запись из любого источника
Запись подтверждена / отменена / перенесенаСмена статуса, другое время или специалист
Визит состоялся / Клиент не пришёлОтметка о визите
Заявку не подтвердили в срокЗаявка сгорела
Клиент создан / изменёнНовая карточка; правка ФИО, телефонов, почты, тегов; удаление персональных данных

Кнопка «Проверить» в строке подписки сразу отправляет проверочное событие и показывает, что ответил ваш сервер. «Сменить секрет» в подписке выдаёт новый секрет - старый перестаёт подходить сразу. Выключить подписку на время - переключатель «Подписка включена».

Журнал доставок

В журнале видно каждую доставку: событие, подписку, состояние, число попыток и ответ вашего сервера (рис. 8). Сверху можно выбрать подписку и состояние. Нажмите на строку - откроется, что именно было отправлено (рис. 9).

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

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

Рис. 9. Доставка вебхука

Рис. 9. Доставка вебхука

  • «Доставлено» - ваш сервер принял событие.
  • «Ждёт отправки» - сервер не ответил или ответил ошибкой; система повторит отправку в «Следующая попытка», с нарастающей паузой - около суток.
  • «Не доставлено» - все попытки исчерпаны. Когда сервер заработает, нажмите «Отправить ещё раз».

«Отправить ещё раз» работает и для доставленного события - если ваш сервер его потерял.

Частые вопросы

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

См. также

Не нашли ответ? Напишите на alert.system@bk.ru или в «Поддержку» из системы.