Shifton Tapşırıqlar platformada işi avtomatlaşdırmağa və onu açıq API vasitəsilə xarici xidmətlərə qoşmağa imkan verir. API vasitəsilə bütün əsas obyektlər əlçatandır — tapşırıqlar, müştərilər, işçilər, çek-listlər, inventar, xidmət sahələri, maliyyə sənədləri və hesabatlar, — buna görə Shifton-u HR, əmək haqqının hesablanması və analitika sistemlərinizlə, həmçinin şirkətin daxili xidmətləri ilə əlaqələndirmək olar.
API sənədləşməsi
Sənədləşmə iki versiyada dərc olunub:
- 🚀 Yeni sənədləşmə — yenilənmiş strukturu və ən son metodları olan aktual məlumat kitabçası versiyası: 👉 https://api2.shifton.com/openapi/
- 📄 Köhnə sənədləşmə — əvvəlki versiya (mövcud inteqrasiyalar üçün hələ də dəstəklənir): 👉 https://api2.shifton.com/docs/
Hər iki versiyanı birbaşa tətbiqdən açmaq olar — Developer bölməsində, Ümumi baxış tabında, «Yeni sənədləşmə» və «Köhnə sənədləşmə» düymələri ilə.
Sənədləşmə iki dildə mövcuddur. Yeni sənədləşmə səhifəsinin sağ yuxarı küncündə EN / RU keçidi var — seçilmiş dil yadda saxlanılır.
API açarını necə almaq olar
API açarı tətbiqin özündə yaradılır:
- Developer bölməsini açın.
- API açarları («API açarları») tabına keçin.
- «API açarı yaradın» düyməsini basın.
Açar yaradarkən nə doldurmaq lazımdır
Aşağıdakı sahələri olan API açarı yaradın yan paneli açılacaq:
- Başlıq — açarın adı, mütləq sahə. Sonradan nəyi söndürmək lazım olduğu aydın olsun deyə təyinatına uyğun adlandırın: «1C-yə çıxarış», «Analitika üçün hesabatlar».
- Müddəti bitir saat — açarın bu tarixdən sonra qüvvədən düşdüyü tarix. Sahəni boş saxlasanız, qüvvədə olma müddəti məhdudlaşdırılmır.
- Giriş — açarın hüquqlarının həcmi:
- Full access (act as me) — açar sizin adınızdan və sizin hüquqlarınızla işləyir.
- Məhdud icazələr — özünüzün seçdiyiniz məhdud icazələr dəsti.
Açarı yaratmaq üçün Əlavə et, paneli bağlamaq üçün Ləğv et düyməsini basın.
📷 *Açar yaratma panelinin skrini — proddan çəkmək lazımdır*
Açar konkret şirkət üçün yaradılır və yalnız onun məlumatları ilə işləyir. Açarı istənilən anda ləğv etmək olar — ləğv dərhal qüvvəyə minir və bu açarla edilən bütün sonrakı sorğular 401 xətası qaytaracaq.
Vacibdir: yaradılmış açar yalnız bir dəfə göstərilir. Onu dərhal köçürün və etibarlı yerdə saxlayın — onu təkrar almaq mümkün deyil. Açar itirilibsə, yenisini yaradın, köhnəsini isə ləğv edin.
Avtorizasiya
API-yə bütün sorğular başlıqda açarla imzalanır:
Authorization: Bearer {your_API_key}API-nin baza adresi:
https://api2.shifton.com/work/1.0.0Qüvvədə olan açar olmadan sorğu 401 və {"message":"Unauthenticated."} gövdəsini qaytarır.
İlk sorğu
Məsələn, şirkətin işçilərinin siyahısını almaq üçün ({companyId} yerinə öz şirkət ID-nizi yazın):
GET https://api2.shifton.com/work/1.0.0/companies/{companyId}/employees
Authorization: Bearer {your_API_key}
Accept: application/jsonElə həmin şey curl vasitəsilə:
curl -H "Authorization: Bearer {your_API_key}" \
-H "Accept: application/json" \
https://api2.shifton.com/work/1.0.0/companies/{companyId}/employeesŞirkətin ID-si tətbiqin ünvan sətrində görünür: app.shifton.com/c/8397/... — /c/ sonrasındakı rəqəm.
API vasitəsilə nə əlçatandır
Məlumat kitabçası 360-dan çox metodu əhatə edir. Səyyar xidmət üçün əsas bölmələr:
- Tapşırıqlar —
/companies/{companyId}/tasks: yaradılma, dəyişdirilmə, statuslar, tapşırıq faylları. - İşlər siyahısı (To Do) —
/companies/{companyId}/todo. - Müştərilər —
/companies/{companyId}/clients, həmçinin müştərilərin ünvanları və istifadəçi sahələri. - Çek-listlər —
/companies/{companyId}/checklists. - Xidmət sahələri —
/companies/{companyId}/tasks/service-areas. - Bacarıqlar —
/companies/{companyId}/skills. - İşçilər —
/companies/{companyId}/employees: əlavə etmə, redaktə, işdən çıxarma və bərpa. - İnventar — predmetlər, kateqoriyalar, dəstlər və anbarlardakı qalıqlar.
- Maliyyə sənədləri — smetalar, iş sifarişləri, fakturalar, qəbzlər, sənəd sayğacları və loqo.
- Hesabatlar — iş və davamiyyət haqqında məlumatların çıxarışı.
Bundan başqa, cədvəllər və növbələr, məzuniyyətlər və işdən azad olma sorğuları, davamiyyət, billinq və SMS-billinq, bildirişlər və modullar əlçatandır.
Vebhuklar
API-yə müntəzəm sorğular yerinə hadisələri baş verdiyi anda almaq lazımdırsa, vebhuklardan istifadə edin — Developer bölməsində Webhooks tabı. Lazımi hadisə baş verdikdə Shifton sorğunu özü sizin ünvanınıza göndərəcək; dəstəklənən hadisələrin siyahısını ayrıca metod qaytarır.
Xəta kodları
Shifton API-si standart HTTP vəziyyət kodlarından istifadə edir:
- 200 — sorğu müvəffəqiyyətlə yerinə yetirildi.
- 201 — obyekt müvəffəqiyyətlə yaradıldı.
- 400 — sorğunun parametrləri yanlışdır.
- 401 — avtorizasiya xətası: açar göndərilməyib, qüvvədə deyil və ya ləğv edilib.
- 403 — giriş qadağandır.
- 404 — resurs tapılmadı (ən çox metodun ünvanında səhv yazılış).
- 500 — server xətası.
İstifadə üzrə məsləhətlər
- Yeni inteqrasiyalar üçün yeni sənədləşmədən istifadə edin — köhnəsi artıq işləyən inteqrasiyalar üçün saxlanılıb.
- Sorğuları yoxlamaq üçün Postman və ya curl rahatdır — onlar bir sətir də kod yazmadan cavabı görməyə imkan verir.
- Açarı kodda açıq şəkildə saxlamayın və üçüncü şəxslərə verməyin: açar şirkətin məlumatlarına giriş verir.
- Sorğuların tezliyinə dair məhdudiyyətlərə (rate limits) riayət edin — onların aşılması API-yə girişin müvəqqəti bloklanmasına səbəb ola bilər.
Tez-tez verilən suallar
Sual: API açarını haradan almaq olar? Cavab: Tətbiqdə: Developer bölməsi → API açarları tabı → «API açarı yaradın» düyməsi. Açar cari şirkət üçün verilir.
Sual: Pəncərəni bağladım və açarı köçürmədim. Onu harada görmək olar? Cavab: Heç yerdə — açar yalnız bir dəfə göstərilir və təkrar verilmir. Yeni açar yaradın, köhnəsini isə ləğv edin.
Sual: Açar lazımsız adamların əlinə keçibsə, onu necə ləğv etmək olar? Cavab: Onu API açarları tabında silin. Ləğv dərhal qüvvəyə minir: bu açarla edilən bütün sorğular dərhal 401 qaytarmağa başlayacaq.
Sual: «Full access» və «Restricted permissions» nə ilə fərqlənir? Cavab: Full access (act as me) açara sizdə olan hüquqların eynisini verir. Məhdud icazələr isə açara yalnız seçilmiş icazələr dəstini verməyə imkan verir — məlumatların yalnız bir hissəsinə girişi lazım olan inteqrasiya üçün bu daha təhlükəsizdir.
Sual: Açarın qüvvədə olma müddətini məhdudlaşdırmaq olarmı? Cavab: Bəli, yaradarkən Müddəti bitir saat sahəsi ilə. Onu doldurmasanız, açar müddətsiz olacaq.
Sual: Bir açar bir neçə şirkət üçün işləyirmi? Cavab: Xeyr. Açar yaradıldığı şirkətə bağlıdır və yalnız onun məlumatları ilə işləyir. Başqa şirkət üçün ayrıca açar yaradın.
Sual: API-nin baza adresi hansıdır? Cavab: https://api2.shifton.com/work/1.0.0. Sonra metodun yolu gəlir, məsələn /companies/{companyId}/tasks.
Sual: Sorğular üçün şirkətin ID-sini haradan almaq olar? Cavab: O, tətbiqin ünvan sətrində, birbaşa /c/ sonrasındadır — məsələn, app.shifton.com/c/8397/tasks ünvanında şirkətin identifikatoru 8397-dir.
Sual: Sənədləşmənin hansı versiyasından istifadə etmək lazımdır? Cavab: Yeni inteqrasiyalar üçün — yenisindən (api2.shifton.com/openapi). Köhnəsi (api2.shifton.com/docs) mövcud inteqrasiyalar üçün dəstəklənir.
Sual: Rus dilində sənədləşmə var? Cavab: Bəli. Yeni sənədləşmə səhifəsində sağ yuxarı küncdə EN / RU keçidi var.
Sual: API-yə sorğuları nə ilə test etmək olar? Cavab: Ən rahatı Postman və ya curl-dur — onlar kod yazmadan sorğu göndərməyə və cavablara baxmağa imkan verir.
Sual: Açarı köçürdüyüm halda nə üçün 401 gəlir? Cavab: Açarın Authorization başlığında, qarşısında Bearer sözü ilə göndərildiyini, açarın ləğv edilmədiyini və qüvvədə olma müddətinin bitmədiyini yoxlayın.
Sual: Nə üçün 404 gəlir? Cavab: Ən çox ünvan qarışdırılır: baza hissəsi https://api2.shifton.com/work/1.0.0 olmalıdır, metodun yolunda isə düzgün {companyId} olmalıdır.
Sual: API vasitəsilə nəyi avtomatlaşdırmaq olar? Cavab: Tapşırıqların yaradılmasını və dəyişdirilməsini, müştərilər və onların ünvanları ilə işi, çek-listləri, xidmət sahələrini, bacarıqları, işçiləri, inventarı, maliyyə sənədlərini və hesabatların çıxarışını, həmçinin cədvəlləri, növbələri və məzuniyyətləri.
Sual: Shifton-dan hadisələri almaq, API-ni sorğulamamaq olarmı? Cavab: Bəli, bunun üçün vebhuklar var — Developer bölməsində Webhooks tabı.
Sual: Şifrənin dəyişdirilməsi inteqrasiyanın işinə təsir edirmi? Cavab: Xeyr. İnteqrasiyalar hesabın şifrəsi ilə deyil, API açarı ilə işləyir.