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."} денесін қайтарады.

Бірінші сұрау

Мысалы, компания қызметкерлерінің тізімін алу үшін ({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-ға тұрақты сұраулар жасаудың орнына оқиғаларды олар туындаған кезде алу қажет болса, вебхуктарды пайдаланыңыз — Developer бөліміндегі Webhooks қойындысы. Қажетті оқиға болғанда Shifton сіздің мекенжайыңызға сұрауды өзі жібереді; қолданылатын оқиғалардың тізімін жеке әдіс қайтарады.

Қате кодтары

Shifton API стандартты 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 арқылы нені автоматтандыруға болады? Жауап: Тапсырмаларды жасау және өзгерту, клиенттермен және олардың мекенжайларымен жұмыс, тексеру парақтары, қызмет көрсету аймақтары, дағдылар, қызметкерлер, түгендеу, Қаржылық құжаттар құжаттары және есептерді жүктеп алу, сонымен қатар кестелер, ауысымдар және демалыстар.

Сұрақ: API-ды сұрастырудың орнына Shifton-нан оқиғалар алуға бола ма? Жауап: Иә, бұл үшін вебхуктар бар — Developer бөліміндегі Webhooks қойындысы.

Сұрақ: Құпиясөзді ауыстыру интеграцияның жұмысына әсер ете ме? Жауап: Жоқ. Интеграциялар аккаунт құпиясөзі бойынша емес, API кілті бойынша жұмыс істейді.