Започнете бесплатно
Закажете демо
Управување со задачиGPS следењеДигитални работни формулариМобилен пристапИзвештаиИнтеграцииПогледнете ги сите карактеристики
ЧистењеГреење и ладењеВодоводЕлектрикаХортикултураКонтрола на штетнициГрадежништвоЗдравствоIT услугиУправување со имотиВидете ги сите 20+ индустрии
БлогСпоредбиЗа насЧППЦентар за помошРецензии
Цени
Започнете бесплатноЗакажете демоНајава
Изберете јазик
English Español Português Deutsch Français Italiano 日本語 中文 हिन्दी עברית العربية 한국어 Nederlands Polski Türkçe Українська Русский Magyar Română Български Čeština Ελληνικά Svenska Dansk Norsk Suomi Bahasa Indonesia Tiếng Việt Tagalog ไทย Latviešu Lietuvių Eesti Slovenčina Slovenščina Hrvatski Македонски Қазақша Azərbaycan Afrikaans বাংলা

Документација за API

Daria Oleshko

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-клуч, а не преку лозинката на сметката.