Ключ до 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 ключем: так подія не розкриває нічого зайвого.