Документация по API

Shifton Задачи позволява да автоматизирате работата с платформата и да я свързвате с външни услуги чрез отворен API. През API са достъпни всички ключови обекти — задачи, клиенти, служители, чеклисти, инвентар, зони за обслужване, документи Финансови документи и отчети — затова Shifton може да бъде свързан с вашите системи за HR, изчисляване на работната заплата и анализ, както и с вътрешните услуги на компанията.

Документация по API

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

• 🚀 Нова документация — актуалната версия на справочника с обновена структура и най-новите методи: 👉 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."}.

Първа заявка

Например, за да получите списъка със служителите на компанията (заменете {companyId} с ID на вашата компания):

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“? Отговор: 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 ключ, а не с паролата на акаунта.