API dokumentacija

Shifton Užduotys leidžia automatizuoti darbą su platforma ir prijungti ją prie išorinių paslaugų per atvirą API. Per API prieinami visi pagrindiniai objektai — užduotys, klientai, darbuotojai, kontroliniai sąrašai, inventorius, paslaugų zonos, Finansinių dokumentų modulio dokumentai ir ataskaitos, — todėl Shifton galima susieti su jūsų HR, darbo užmokesčio apskaičiavimo ir analitikos sistemomis, taip pat su vidinėmis įmonės paslaugomis.

Dokumentacija paskelbta dviem versijomis:

🚀 Nauja dokumentacija — aktuali žinyno versija su atnaujinta struktūra ir naujausiais metodais: 👉 https://api2.shifton.com/openapi/
📄 Sena dokumentacija — ankstesnė versija (esamoms integracijoms vis dar palaikoma): 👉 https://api2.shifton.com/docs/

Abi versijas galima atidaryti tiesiai iš programos — skyriuje Developer, kortelėje Apžvalga, mygtukais „Nauja dokumentacija“ ir „Sena dokumentacija“.

Dokumentacija prieinama dviem kalbomis. Naujos dokumentacijos puslapio viršutiniame dešiniajame kampe yra perjungiklis EN / RU — pasirinkta kalba įsimenama.

Kaip gauti API raktą

API raktas kuriamas pačioje programoje:

Atidarykite skyrių Developer.
Pereikite į kortelę API raktai („API raktai“).
Spustelėkite „Sukurti API raktą“.

Ką užpildyti kuriant raktą

Atsidarys šoninis skydelis Sukurti API raktą su laukais:

Pavadinimas — rakto pavadinimas, privalomas laukas. Vadinkite pagal paskirtį, kad vėliau būtų aišku, ką išjungti: „Eksportas į 1C“, „Ataskaitos analitikai“.
Baigiasi — data, po kurios raktas nustos veikti. Jei lauką paliksite tuščią, galiojimo laikas nebus ribojamas.
Prieiga — rakto teisių apimtis:
Full access (act as me) — raktas veikia jūsų vardu ir su jūsų teisėmis.
Apriboti leidimai — apribotas leidimų rinkinys, kurį pasirenkate patys.

Spustelėkite Pridėti, kad sukurtumėte raktą, arba Atšaukti, kad uždarytumėte skydelį.

📷 *Rakto kūrimo skydelio ekrano nuotrauka — nufotografuoti prode*

Raktas kuriamas konkrečiai įmonei ir veikia tik su jos duomenimis. Raktą galima atšaukti bet kada — atšaukimas įsigalioja nedelsiant, ir visos vėlesnės užklausos su tuo raktu grąžins klaidą 401.

Svarbu: sukurtas raktas parodomas tik vieną kartą. Nukopijuokite jį iš karto ir saugokite patikimoje vietoje — pakartotinai jo gauti neįmanoma. Jei raktas pamestas, sukurkite naują, o senąjį atšaukite.

Autorizacija

Visos užklausos į API pasirašomos raktu antraštėje:

Authorization: Bearer {your_API_key}

Bazinis API adresas:

https://api2.shifton.com/work/1.0.0

Užklausa be veikiančio rakto grąžina 401 ir kūną {"message":"Unauthenticated."}.

Pirmoji užklausa

Pavyzdžiui, kad gautumėte įmonės darbuotojų sąrašą (vietoje {companyId} įrašykite savo įmonės ID):

GET https://api2.shifton.com/work/1.0.0/companies/{companyId}/employees
Authorization: Bearer {your_API_key}
Accept: application/json

Tas pats per curl:

curl -H "Authorization: Bearer {your_API_key}" \
     -H "Accept: application/json" \
     https://api2.shifton.com/work/1.0.0/companies/{companyId}/employees

Įmonės ID matomas programos adreso juostoje: app.shifton.com/c/8397/... — skaičius po /c/.

Kas prieinama per API

Žinyne aprašyta daugiau nei 360 metodų. Pagrindiniai išvažiuojamojo aptarnavimo skyriai:

Užduotys — /companies/{companyId}/tasks: kūrimas, keitimas, statusai, užduočių failai.
Darbų sąrašas (To Do) — /companies/{companyId}/todo.
Klientai — /companies/{companyId}/clients, taip pat klientų adresai ir pasirinktiniai laukai.
Kontroliniai sąrašai — /companies/{companyId}/checklists.
Paslaugų zonos — /companies/{companyId}/tasks/service-areas.
Įgūdžiai — /companies/{companyId}/skills.
Darbuotojai — /companies/{companyId}/employees: pridėjimas, redagavimas, atleidimas ir atkūrimas.
Inventorius — prekės, kategorijos, komplektai ir likučiai sandėliuose.
Finansiniai dokumentai — sąmatos, darbų užsakymai, sąskaitos, kvitai, dokumentų skaitikliai ir logotipas.
Ataskaitos — darbo ir lankomumo duomenų eksportas.

Be to, prieinami tvarkaraščiai ir pamainos, atostogos ir laisvų dienų užklausos, lankomumas, atsiskaitymas ir SMS atsiskaitymas, pranešimai ir moduliai.

Webhook’ai

Jei užuot reguliariai kreipęsi į API norite gauti įvykius jų atsiradimo momentu, naudokite webhook’us — kortelė Webhooks skyriuje Developer. Shifton pats išsiųs užklausą jūsų adresu, kai įvyks reikiamas įvykis; palaikomų įvykių sąrašą grąžina atskiras metodas.

Klaidų kodai

Shifton API naudoja standartinius HTTP būsenos kodus:

200 — užklausa įvykdyta sėkmingai.
201 — objektas sėkmingai sukurtas.
400 — neteisingi užklausos parametrai.
401 — autorizacijos klaida: raktas neperduotas, negalioja arba atšauktas.
403 — prieiga uždrausta.
404 — išteklius nerastas (dažniausiai metodo adrese yra rašybos klaida).
500 — serverio klaida.

Naudojimo patarimai

Naujoms integracijoms naudokite naują dokumentaciją — senoji palikta jau veikiančioms integracijoms.
Užklausoms patikrinti patogu naudoti Postman arba curl — jie leidžia pamatyti atsakymą neparašius nė vienos kodo eilutės.
Nesaugokite rakto atviru tekstu kode ir neperduokite jo tretiesiems asmenims: raktas atveria prieigą prie įmonės duomenų.
Laikykitės užklausų dažnumo ribojimų (rate limits) — juos pažeidus prieiga prie API gali būti laikinai užblokuota.

Dažnai užduodami klausimai

Klausimas: Kur gauti API raktą? Atsakymas: Programoje: skyrius Developer → kortelė API raktai → mygtukas „Sukurti API raktą“. Raktas išduodamas esamai įmonei.

Klausimas: Uždariau langą ir nenukopijavau rakto. Kur jį pamatyti? Atsakymas: Niekur — raktas parodomas tik vieną kartą ir pakartotinai neišduodamas. Sukurkite naują raktą, o senąjį atšaukite.

Klausimas: Kaip atšaukti raktą, jei jis pateko ne į tas rankas? Atsakymas: Ištrinkite jį kortelėje API raktai. Atšaukimas įsigalioja nedelsiant: visos užklausos su tuo raktu iš karto pradės grąžinti 401.

Klausimas: Kuo skiriasi „Full access“ ir „Restricted permissions“? Atsakymas: Full access (act as me) duoda raktui tokias pačias teises, kokias turite jūs. Apriboti leidimai leidžia raktui suteikti tik pasirinktą leidimų rinkinį — taip saugiau integracijai, kuriai reikia prieigos tik prie dalies duomenų.

Klausimas: Ar galima apriboti rakto galiojimo laiką? Atsakymas: Taip, kuriant yra laukas Baigiasi. Jei jo nepildysite, raktas bus neterminuotas.

Klausimas: Ar vienas raktas veikia kelioms įmonėms? Atsakymas: Ne. Raktas susietas su ta įmone, kurioje jis sukurtas, ir veikia tik su jos duomenimis. Kitai įmonei sukurkite atskirą raktą.

Klausimas: Koks yra bazinis API adresas? Atsakymas: https://api2.shifton.com/work/1.0.0. Toliau eina metodo kelias, pavyzdžiui, /companies/{companyId}/tasks.

Klausimas: Kur gauti įmonės ID užklausoms? Atsakymas: Jis yra programos adreso juostoje iškart po /c/ — pavyzdžiui, adrese app.shifton.com/c/8397/tasks įmonės identifikatorius yra 8397.

Klausimas: Kuria dokumentacijos versija naudotis? Atsakymas: Naujoms integracijoms — naująja (api2.shifton.com/openapi). Senoji (api2.shifton.com/docs) palaikoma esamoms integracijoms.

Klausimas: Ar yra dokumentacija rusų kalba? Atsakymas: Taip. Naujos dokumentacijos puslapio viršutiniame dešiniajame kampe yra perjungiklis EN / RU.

Klausimas: Kuo testuoti užklausas į API? Atsakymas: Patogiausia naudoti Postman arba curl — jie leidžia siųsti užklausas ir matyti atsakymus nerašant kodo.

Klausimas: Kodėl gaunu 401, nors raktą nukopijavau? Atsakymas: Patikrinkite, ar raktas perduodamas antraštėje Authorization su žodžiu Bearer prieš jį, ar raktas nėra atšauktas ir ar nepasibaigė jo galiojimo laikas.

Klausimas: Kodėl gaunu 404? Atsakymas: Dažniausiai supainiotas adresas: bazinė dalis turi būti https://api2.shifton.com/work/1.0.0, o metodo kelyje — teisingas {companyId}.

Klausimas: Ką galima automatizuoti per API? Atsakymas: Užduočių kūrimą ir keitimą, darbą su klientais ir jų adresais, kontrolinius sąrašus, paslaugų zonas, įgūdžius, darbuotojus, inventorių, Finansinių dokumentų modulio dokumentus ir ataskaitų eksportą, taip pat tvarkaraščius, pamainas ir atostogas.

Klausimas: Ar galima gauti įvykius iš Shifton, užuot apklausus API? Atsakymas: Taip, tam yra webhook’ai — kortelė Webhooks skyriuje Developer.

Klausimas: Ar slaptažodžio pakeitimas turi įtakos integracijos darbui? Atsakymas: Ne. Integracijos veikia pagal API raktą, o ne pagal paskyros slaptažodį.