Ключ к API даёт чужой системе читать или менять ваши данные: бухгалтерии, BI, собственному приложению. Вебхук работает наоборот: как только что-то изменилось, InShift сам стучится в вашу систему. Вместе это одно подключение: в событии только тип и идентификатор, а за самими данными ваша система идёт в API с ключом. Документация для разработчиков на inshift.app/api.
Ключ виден один раз при создании, дальше хранится только его отпечаток. У ключа есть права: что именно читать, можно ли менять, открыты ли персональные данные и зарплата, и ограничен ли он точками.
Создавать ключи и вебхуки могут только владелец и совладельцы организации.
Где найти
«Настройки» → вкладка «Интеграции» → карточка «Ключи API и вебхуки» с подписью «Собственная интеграция» и состоянием «Не настроено», «Работает» или «Не доходит». На странице два блока: «Ключи к API» с кнопкой «Создать ключ» и «Вебхуки» с кнопкой «Добавить адрес».
Каждый ключ и каждый адрес открываются отдельной страницей с фактами: «Ключ», «Создан», «Последний раз», «Точки», «Права».
Шаг за шагом: создать ключ
- Нажмите «Создать ключ». В окне впишите «Название», например «1С бухгалтерия»: «Чтобы через год было понятно, чей это ключ и что случится, если его забрать».
Окно создания ключа: название и список прав с кодами company:read, locations:read, shifts:read и другими - Отметьте «Права». Группы: «Справочники» («Данные организации: название, часовой пояс, включённые модули», «Точки», «Должности», «Люди: имена, должности, точки, даты приёма и увольнения»), «График и часы» («Смены в графике», «Отпуска, больничные, отгулы», «Отметки прихода и ухода с планшета», «Табель: часы по дням, план и факт»), «Синхронизация» («Лента изменений, чтобы не выгружать всё каждый раз»). Отдельно права менять: «Создавать, править и снимать смены (черновики)», «Публиковать смены, то есть показывать их команде», «Заводить и обновлять карточки людей». И чувствительное: «Телефоны, почта, даты рождения, табельные номера» и «Зарплата: начисленное с раскладкой по надбавкам, выплаты, долг, ведомости, условия оплаты».
- Читайте предупреждения. Персональные данные: «Включайте только если интеграция без них действительно не работает: кадры, рассылки. Для сверки людей с чужой системой хватает внешнего идентификатора». Зарплата: только чтение, изменить через API ничего нельзя. Право менять: «Ключ с ним создаёт и правит смены в вашем графике так же, как человек в приложении», публикацию спрашиваем отдельно, без неё внешняя система кладёт только черновики.
- Нажмите «Создать». Окно «Ключ создан»: «Скопируйте его сейчас и передайте интегратору». Нажмите «Скопировать», потом «Готово». «Это единственный раз, когда ключ виден. Мы храним только его отпечаток и не можем показать повторно. Потеряли ключ? Сделайте ротацию».
Окно «Ключ создан» с ключом, кнопками «Скопировать» и «Готово», за ним страница ключа с правами - На странице ключа факты: «Ключ» с началом и звёздочками вместо остального, «Создан», «Последний раз» и «Точки»: «Вся организация» или «только 2 точки», если ключ ограничен точками.
Ротация и отзыв
«Ротация» на странице ключа выдаёт новый ключ, а старый работает ещё несколько дней: «Старый ключ проработает ещё 7 дней, чтобы интегратор успел переключиться». Состояние ключа в это время «Ротация».
«Отозвать» останавливает ключ сразу и навсегда: «Отозвать ключ?», «1С бухгалтерия» перестанет работать сразу и навсегда. Интеграция, которая им пользуется, остановится». Отозванный ключ остаётся в списке с состоянием «Отозван»; «Убрать из списка» прячет строку, запись в журнале остаётся.
Ключи и вебхуки принадлежат организации и работают дальше, когда создавшего их человека снимают с совладельцев или увольняют; в окне подтверждения можно выбрать «Отозвать» для всего, что этот человек создал.
В списке возле ключа пометки «изменяет данные», «персональные данные», «зарплата», «только 2 точки» и «Последний раз» с временем последнего запроса или «ни разу».
Шаг за шагом: добавить вебхук
- В блоке «Вебхуки» нажмите «Добавить адрес». Впишите «Адрес»: «Только https и только адрес, достижимый из интернета. Локальные и внутренние адреса мы не принимаем». И «Название», например «Сценарий в Make».
Окно добавления вебхука: адрес, название и события «Смены в графике», «Отпуска, больничные, отгулы», «Люди», «Точки», «Должности» с вариантами «добавлено», «изменено», «удалено» - Выберите «На что подписаться»: целые группы «Смены в графике», «Отпуска, больничные, отгулы», «Отметки прихода и ухода», «Люди», «Точки», «Должности» или «Отдельные события»: «добавлено», «изменено», «удалено» для каждой.
- Нажмите «Создать». Окно «Адрес добавлен» покажет секрет подписи: «Это секрет подписи. Им ваша система проверит, что запрос действительно от нас». Скопируйте его сейчас.
- Нажмите «Проверить» на странице адреса: пробное событие пойдёт тем же путём, что и настоящее. Ответ «Дошло, сервер ответил 200» или «Не дошло: …».
Как работают вебхуки
«Как только что-то изменилось, мы отправляем на ваш адрес POST. В теле только тип события и идентификатор объекта; самих данных там нет, за ними ваша система идёт в API с ключом».
«Каждый запрос подписан вашим секретом в заголовке. Проверяйте подпись, прежде чем верить запросу: адрес может знать кто-то ещё, секрет нет».
«Не ответили или ответили ошибкой? Повторим шесть раз: через минуту, пять минут, полчаса, два часа, шесть часов и сутки».
«Десять доставок подряд, которые так и не дошли, выключают адрес». Выключенный адрес виден с состоянием «Выключено», кнопка «Включить» возвращает его: «Адрес включён, события снова идут».
Адресов можно иметь до пяти. Журнал «Доставки» на странице адреса показывает каждую попытку: «в очереди», «доставлено», «не удалось», и «Последний раз дошло».
Почему действия нет
Нет карточки «Ключи API и вебхуки»: вкладку «Интеграции» видят только владелец и совладельцы.
Не вижу ключ повторно: он показывается один раз. Сделайте «Ротация» и передайте новый.
Адрес не принимается: нужен https и публичный адрес, локальные и внутренние не принимаются.
Состояние «Не доходит»: последняя доставка не дошла, «Повторяем по расписанию; если не дойдёт десять раз подряд, адрес выключится сам». Проверьте сервер и нажмите «Проверить».
Не могу добавить шестой адрес: лимит пять.
Ключ получает 403 на запрос: у него нет нужного права. Права видны на странице ключа.
Вопросы и ответы
Где документация API?
На inshift.app/api: описание методов и файл openapi.json для генерации клиента.
Можно ли дать ключ на одну точку?
Панель создаёт ключ на всю организацию. Ключ, ограниченный точками, в списке помечен «только 2 точки»: если такое ограничение нужно, напишите в поддержку. Лента изменений и для такого ключа приходит по всей организации, но в событии только идентификатор, данные других точек остаются закрытыми.
Видит ли ключ зарплату?
Только если отмечено право «Зарплата». Оно только на чтение, с предупреждением «Деньги».
Что такое «Лента изменений»?
Список событий с идентификаторами, чтобы ваша система забирала только то, что изменилось, а не выгружала всё каждый раз.
Отправляет ли вебхук сами данные?
Нет, только тип события и идентификатор. Данные ваша система забирает из API ключом: так событие не раскрывает ничего лишнего.