Документація з API

Shifton Завдання дозволяє автоматизувати роботу з платформою та підключати її до зовнішніх сервісів через відкритий API. Через API доступні всі ключові сутності — завдання, клієнти, співробітники, чек-листи, інвентар, зони обслуговування, фінансові документи та звіти, — тому Shifton можна зв’язати з вашими системами HR, розрахунку заробітної плати та аналітики, а також із внутрішніми сервісами компанії.

Документація опублікована у двох версіях:

🚀 Нова документація — актуальна версія довідника з обновленою структурою та останніми методами: 👉 https://api2.shifton.com/openapi/
📄 Стара документація — попередня версія (як і раніше підтримується для наявних інтеграцій): 👉 https://api2.shifton.com/docs/

Відкрити обидві версії можна просто з додатка — у розділі Developer, на вкладці Огляд, кнопками «Нова документація» і «Стара документація».

Документація доступна двома мовами. У правому верхньому куті сторінки нової документації є переключувач EN / RU — вибрана мова запам’ятовується.

Як отримати ключ API

Ключ API створюється в самому додатку:

Відкрийте розділ Developer.
Перейдіть на вкладку Ключі API («Ключі API»).
Натисніть «Створити ключ API».

Що заповнити при створенні ключа

Відкриється бічна панель Створити ключ API з полями:

Назва — назва ключа, обов’язкове поле. Називайте за призначенням, щоб потім було зрозуміло, що відключати: «Вивантаження в 1С», «Звіти для аналітики».
Закінчується о — дата, після якої ключ перестане діяти. Якщо залишити поле порожнім, строк дії не обмежений.
Доступ — обсяг прав ключа:
Full access (act as me) — ключ працює від вашого імені та з вашими правами.
Обмежені дозволи — обмежений набір дозволів, який ви вибираєте самі.

Натисніть Додати, щоб створити ключ, або Скасувати, щоб закрити панель.

📷 *Скрін панелі створення ключа — зняти на проді*

Ключ створюється для конкретної компанії і працює лише з її даними. Відкликати ключ можна будь-коли — відкликання діє негайно, і всі наступні запити з цим ключем повернуть помилку 401.

Важливо: створений ключ показується лише один раз. Скопіюйте його відразу й зберігайте в надійному місці — отримати його повторно не можна. Якщо ключ втрачено, створіть новий, а старий відкличте.

Авторизація

Усі запити до API підписуються ключем у заголовку:

Authorization: Bearer {your_API_key}

Базова адреса API:

https://api2.shifton.com/work/1.0.0

Запит без діючого ключа повертає 401 і тіло {"message":"Unauthenticated."}.

Перший запит

Наприклад, щоб отримати список співробітників компанії (підставте свій ID компанії замість {companyId}):

GET https://api2.shifton.com/work/1.0.0/companies/{companyId}/employees
Authorization: Bearer {your_API_key}
Accept: application/json

Те саме через curl:

curl -H "Authorization: Bearer {your_API_key}" \
     -H "Accept: application/json" \
     https://api2.shifton.com/work/1.0.0/companies/{companyId}/employees

ID компанії видно в адресному рядку додатка: app.shifton.com/c/8397/... — число після /c/.

Що доступно через API

Довідник охоплює більше 360 методів. Основні розділи для виїзного обслуговування:

Завдання — /companies/{companyId}/tasks: створення, зміна, статуси, файли завдань.
Список справ (To Do) — /companies/{companyId}/todo.
Клієнти — /companies/{companyId}/clients, а також адреси та користувацькі поля клієнтів.
Чек-листи — /companies/{companyId}/checklists.
Зони обслуговування — /companies/{companyId}/tasks/service-areas.
Навички — /companies/{companyId}/skills.
Співробітники — /companies/{companyId}/employees: додавання, редагування, звільнення та відновлення.
Інвентар — предмети, категорії, комплекти та залишки на складах.
Фінансові документи — кошториси, замовлення на роботи, рахунки, квитанції, лічильники документів і логотип.
Звіти — вивантаження даних про роботу та відвідуваність.

Крім того, доступні розписи та зміни, відпустки й запити на відгул, відвідуваність, білінг і SMS-білінг, сповіщення та модулі.

Вебхуки

Якщо замість регулярних запитів до API вам потрібно отримувати події в момент їх виникнення, використовуйте вебхуки — вкладка Webhooks у розділі Developer. Shifton сам надішле запит на вашу адресу, коли відбудеться потрібна подія; список підтримуваних подій повертає окремий метод.

Коди помилок

API Shifton використовує стандартні коди стану HTTP:

200 — запит виконано успішно.
201 — об’єкт успішно створено.
400 — неправильні параметри запиту.
401 — помилка авторизації: ключ не передано, недійсний або відкликаний.
403 — доступ заборонено.
404 — ресурс не знайдено (найчастіше помилка в адресі методу).
500 — помилка сервера.

Порада щодо використання

Для нових інтеграцій використовуйте нову документацію — стару залишено для вже працюючих інтеграцій.
Для перевірки запитів зручні Postman або curl — вони дозволяють побачити відповідь, не написавши жодного рядка коду.
Не зберігайте ключ у відкритому вигляді в коді й не передавайте його третім особам: ключ дає доступ до даних компанії.
Дотримуйтеся обмежень на частоту запитів (rate limits) — їх перевищення може призвести до тимчасового блокування доступу до API.

Часті запитання

Питання: Де взяти ключ API? Відповідь: У додатку: розділ Developer → вкладка Ключі API → кнопка «Створити ключ API». Ключ видається для поточної компанії.

Питання: Я закрив вікно й не скопіював ключ. Де його подивитися? Відповідь: Ніде — ключ показується лише один раз і повторно не видається. Створіть новий ключ, а старий відкличте.

Питання: Як відкликати ключ, якщо він потрапив не в ті руки? Відповідь: Видаліть його на вкладці Ключі API. Відкликання діє негайно: всі запити з цим ключем відразу почнуть повертати 401.

Питання: Чим відрізняються «Повний доступ» і «Обмежені дозволи»? Відповідь: Full access (act as me) дає ключу ті самі права, що є у вас. Обмежені дозволи дозволяє видати ключу лише вибраний набір дозволів — так безпечніше для інтеграції, якій потрібен доступ лише до частини даних.

Питання: Чи можна обмежити строк дії ключа? Відповідь: Так, поле Закінчується о при створенні. Якщо його не заповнювати, ключ буде безстроковим.

Питання: Чи працює один ключ для кількох компаній? Відповідь: Ні. Ключ прив’язаний до компанії, в якій він створений, і працює лише з її даними. Для іншої компанії створіть окремий ключ.

Питання: Яка базова адреса в API? Відповідь: https://api2.shifton.com/work/1.0.0. Далі йде шлях методу, наприклад /companies/{companyId}/tasks.

Питання: Де взяти ID компанії для запитів? Відповідь: Він є в адресному рядку додатка відразу після /c/ — наприклад, у app.shifton.com/c/8397/tasks ідентифікатор компанії дорівнює 8397.

Питання: Якою версією документації користуватися? Відповідь: Для нових інтеграцій — новою (api2.shifton.com/openapi). Стара (api2.shifton.com/docs) підтримується для наявних інтеграцій.

Питання: Чи є документація російською мовою? Відповідь: Так. На сторінці нової документації в правому верхньому куті переключувач EN / RU.

Питання: Чим тестувати запити до API? Відповідь: Найзручніше Postman або curl — вони дозволяють надсилати запити й дивитися відповіді без написання коду.

Питання: Чому приходить 401, хоча ключ я скопіював? Відповідь: Перевірте, що ключ передається в заголовку Authorization зі словом Bearer перед ним, що ключ не відкликаний і не закінчився строк його дії.

Питання: Чому приходить 404? Відповідь: Найчастіше переплутано адресу: базова частина має бути https://api2.shifton.com/work/1.0.0, а в шляху методу — правильний {companyId}.

Питання: Що можна автоматизувати через API? Відповідь: Створення та зміну завдань, роботу з клієнтами та їхніми адресами, чек-листи, зони обслуговування, навички, співробітників, інвентар, фінансові документи та вивантаження звітів, а також розписи, зміни та відпустки.

Питання: Чи можна отримувати події з Shifton, а не опитувати API? Відповідь: Так, для цього є вебхуки — вкладка Webhooks у розділі Developer.

Питання: Чи впливає зміна пароля на роботу інтеграції? Відповідь: Ні. Інтеграції працюють за ключем API, а не за паролем акаунта.