Документация по 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С», «Отчёты для аналитики».
Истекает — дата, после которой ключ перестанет действовать. Если оставить поле пустым, срок действия не ограничен.
Доступ — объём прав ключа:
Полный доступ (от моего имени) — ключ работает от вашего имени и с вашими правами.
Ограниченные права — ограниченный набор разрешений, который вы выбираете сами.

Нажмите Добавить, чтобы создать ключ, или Отменить, чтобы закрыть панель.

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

Ключ создаётся для конкретной компании и работает только с её данными. Отозвать ключ можно в любой момент — отзыв действует немедленно, и все последующие запросы с этим ключом вернут ошибку 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» и «Restricted permissions»?
О: Полный доступ (от моего имени) даёт ключу те же права, что есть у вас. Ограниченные права позволяет выдать ключу только выбранный набор разрешений — так безопаснее для интеграции, которой нужен доступ лишь к части данных.

В: Можно ли ограничить срок действия ключа?
О: Да, поле Истекает при создании. Если его не заполнять, ключ будет бессрочным.

В: Работает ли один ключ для нескольких компаний?
О: Нет. Ключ привязан к компании, в которой он создан, и работает только с её данными. Для другой компании создайте отдельный ключ.

В: Какой базовый адрес у 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-ключу, а не по паролю аккаунта.