API dokumentācija

Shifton Uzdevumi ļauj automatizēt darbu ar platformu un pieslēgt to ārējiem servisiem, izmantojot atklātu API. Caur API ir pieejamas visas galvenās vienības — uzdevumi, klienti, darbinieki, kontrolsaraksti, inventārs, apkalpošanas zonas, moduļa Finanšu dokumenti dokumenti un pārskati, — tāpēc Shifton var sasaistīt ar jūsu HR, darba algas aprēķina un analītikas sistēmām, kā arī ar uzņēmuma iekšējiem servisiem.

Dokumentācija ir publicēta divās versijās:

🚀 Jauna dokumentācija — aktuālā rokasgrāmatas versija ar atjauninātu struktūru un jaunākajām metodēm: 👉 https://api2.shifton.com/openapi/
📄 Vecā dokumentācija — iepriekšējā versija (joprojām tiek atbalstīta esošajām integrācijām): 👉 https://api2.shifton.com/docs/

Abas versijas var atvērt tieši no lietotnes — sadaļā Developer, cilnē Pārskats, ar pogām „Jauna dokumentācija“ un „Vecā dokumentācija“.

Dokumentācija ir pieejama divās valodās. Jaunās dokumentācijas lapas augšējā labajā stūrī ir pārslēdzējs EN / RU — izvēlētā valoda tiek atcerēta.

Kā iegūt API atslēgu

API atslēga tiek izveidota pašā lietotnē:

Atveriet sadaļu Developer.
Pārejiet uz cilni API atslēgas („API atslēgas“).
Nospiediet „Izveidot API atslēgu“.

Ko aizpildīt, izveidojot atslēgu

Atvērsies sānu panelis Izveidot API atslēgu ar laukiem:

Nosaukums — atslēgas nosaukums, obligāts lauks. Nosauciet pēc pielietojuma, lai vēlāk būtu saprotams, ko atslēgt: „Eksports uz 1C“, „Pārskati analītikai“.
Beidzas plkst. — datums, pēc kura atslēga pārstās darboties. Ja lauku atstāj tukšu, darbības termiņš nav ierobežots.
Piekļuve — atslēgas tiesību apjoms:
Full access (act as me) — atslēga darbojas jūsu vārdā un ar jūsu tiesībām.
Ierobežotas atļaujas — ierobežota atļauju kopa, kuru jūs izvēlaties pats.

Nospiediet Pievienot, lai izveidotu atslēgu, vai Atcelt, lai aizvērtu paneli.

📷 *Atslēgas izveides paneļa ekrānuzņēmums — uzņemt uz prod*

Atslēga tiek izveidota konkrētam uzņēmumam un darbojas tikai ar tā datiem. Atsaukt atslēgu var jebkurā brīdī — atsaukums darbojas nekavējoties, un visi turpmākie pieprasījumi ar šo atslēgu atgriezīs kļūdu 401.

Svarīgi: izveidotā atslēga tiek parādīta tikai vienu reizi. Nokopējiet to uzreiz un glabājiet drošā vietā — atkārtoti to iegūt nav iespējams. Ja atslēga ir pazaudēta, izveidojiet jaunu, bet veco atsauciet.

Autorizācija

Visi pieprasījumi uz API tiek parakstīti ar atslēgu galvenē:

Authorization: Bearer {your_API_key}

API bāzes adrese:

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

Pieprasījums bez derīgas atslēgas atgriež 401 un ķermeni {"message":"Unauthenticated."}.

Pirmais pieprasījums

Piemēram, lai iegūtu uzņēmuma darbinieku sarakstu (ievietojiet savu uzņēmuma ID {companyId} vietā):

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

Tas pats caur curl:

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

Uzņēmuma ID ir redzams lietotnes adreses joslā: app.shifton.com/c/8397/... — skaitlis pēc /c/.

Kas ir pieejams caur API

Rokasgrāmata aptver vairāk nekā 360 metodes. Galvenās sadaļas izbraukuma apkalpošanai:

Uzdevumi — /companies/{companyId}/tasks: izveide, izmaiņas, statusi, uzdevumu faili.
Darbu saraksts (To Do) — /companies/{companyId}/todo.
Klienti — /companies/{companyId}/clients, kā arī klientu adreses un pielāgotie lauki.
Kontrolsaraksti — /companies/{companyId}/checklists.
Apkalpošanas zonas — /companies/{companyId}/tasks/service-areas.
Prasmes — /companies/{companyId}/skills.
Darbinieki — /companies/{companyId}/employees: pievienošana, rediģēšana, atbrīvošana no darba un atjaunošana.
Inventārs — priekšmeti, kategorijas, komplekti un atlikumi noliktavās.
Finanšu dokumenti — tāmes, darba pasūtījumi, rēķini, kvītis, dokumentu skaitītāji un logotips.
Pārskati — datu eksports par darbu un apmeklējumu.

Turklāt ir pieejami grafiki un maiņas, atvaļinājumi un brīvdienu pieprasījumi, apmeklējums, norēķini un SMS norēķini, paziņojumi un moduļi.

Tīmekļa āķi

Ja regulāru pieprasījumu uz API vietā jums nepieciešams saņemt notikumus to rašanās brīdī, izmantojiet tīmekļa āķus — cilne Webhooks sadaļā Developer. Shifton pats nosūtīs pieprasījumu uz jūsu adresi, kad notiks vajadzīgais notikums; atbalstīto notikumu sarakstu atgriež atsevišķa metode.

Kļūdu kodi

Shifton API izmanto standarta HTTP statusa kodus:

200 — pieprasījums izpildīts veiksmīgi.
201 — objekts veiksmīgi izveidots.
400 — nepareizi pieprasījuma parametri.
401 — autorizācijas kļūda: atslēga nav nodota, nav derīga vai ir atsaukta.
403 — piekļuve aizliegta.
404 — resurss nav atrasts (visbiežāk drukas kļūda metodes adresē).
500 — servera kļūda.

Ieteikumi lietošanai

Jaunām integrācijām izmantojiet jauno dokumentāciju — vecā ir atstāta jau strādājošām integrācijām.
Pieprasījumu pārbaudei ir ērti Postman vai curl — tie ļauj ieraudzīt atbildi, neuzrakstot nevienu koda rindiņu.
Neglabājiet atslēgu atklātā veidā kodā un nenododiet to trešajām personām: atslēga dod piekļuvi uzņēmuma datiem.
Ievērojiet pieprasījumu biežuma ierobežojumus (rate limits) — to pārsniegšana var novest pie pagaidu piekļuves bloķēšanas API.

Bieži uzdotie jautājumi

Jautājums: Kur iegūt API atslēgu? Atbilde: Lietotnē: sadaļa Developer → cilne API atslēgas → poga „Izveidot API atslēgu“. Atslēga tiek izsniegta pašreizējam uzņēmumam.

Jautājums: Es aizvēru logu un nenokopēju atslēgu. Kur to var apskatīt? Atbilde: Nekur — atslēga tiek parādīta tikai vienu reizi un atkārtoti netiek izsniegta. Izveidojiet jaunu atslēgu, bet veco atsauciet.

Jautājums: Kā atsaukt atslēgu, ja tā nokļuvusi nepareizās rokās? Atbilde: Izdzēsiet to cilnē API atslēgas. Atsaukums darbojas nekavējoties: visi pieprasījumi ar šo atslēgu uzreiz sāks atgriezt 401.

Jautājums: Ar ko atšķiras „Full access“ un „Restricted permissions“? Atbilde: Full access (act as me) dod atslēgai tās pašas tiesības, kādas ir jums. Ierobežotas atļaujas ļauj izsniegt atslēgai tikai izvēlēto atļauju kopu — tā ir drošāk integrācijai, kurai nepieciešama piekļuve tikai daļai datu.

Jautājums: Vai atslēgas darbības termiņu var ierobežot? Atbilde: Jā, lauks Beidzas plkst. izveides laikā. Ja to neaizpilda, atslēga būs beztermiņa.

Jautājums: Vai viena atslēga darbojas vairākiem uzņēmumiem? Atbilde: Nē. Atslēga ir piesaistīta uzņēmumam, kurā tā izveidota, un darbojas tikai ar tā datiem. Citam uzņēmumam izveidojiet atsevišķu atslēgu.

Jautājums: Kāda ir API bāzes adrese? Atbilde: https://api2.shifton.com/work/1.0.0. Tālāk seko metodes ceļš, piemēram, /companies/{companyId}/tasks.

Jautājums: Kur iegūt uzņēmuma ID pieprasījumiem? Atbilde: Tas ir lietotnes adreses joslā uzreiz pēc /c/ — piemēram, adresē app.shifton.com/c/8397/tasks uzņēmuma identifikators ir 8397.

Jautājums: Kuru dokumentācijas versiju lietot? Atbilde: Jaunām integrācijām — jauno (api2.shifton.com/openapi). Vecā (api2.shifton.com/docs) tiek atbalstīta esošajām integrācijām.

Jautājums: Vai ir dokumentācija krievu valodā? Atbilde: Jā. Jaunās dokumentācijas lapā augšējā labajā stūrī ir pārslēdzējs EN / RU.

Jautājums: Ar ko testēt pieprasījumus uz API? Atbilde: Visērtāk ir Postman vai curl — tie ļauj sūtīt pieprasījumus un skatīt atbildes, nerakstot kodu.

Jautājums: Kāpēc pienāk 401, lai gan atslēgu es nokopēju? Atbilde: Pārbaudiet, vai atslēga tiek nodota galvenē Authorization ar vārdu Bearer pirms tās, vai atslēga nav atsaukta un vai nav beidzies tās darbības termiņš.

Jautājums: Kāpēc pienāk 404? Atbilde: Visbiežāk ir sajaukta adrese: bāzes daļai jābūt https://api2.shifton.com/work/1.0.0, bet metodes ceļā — pareizajam {companyId}.

Jautājums: Ko var automatizēt caur API? Atbilde: Uzdevumu izveidi un izmaiņas, darbu ar klientiem un viņu adresēm, kontrolsarakstus, apkalpošanas zonas, prasmes, darbiniekus, inventāru, moduļa Finanšu dokumenti dokumentus un pārskatu eksportu, kā arī grafikus, maiņas un atvaļinājumus.

Jautājums: Vai var saņemt notikumus no Shifton, nevis aptaujāt API? Atbilde: Jā, tam ir tīmekļa āķi — cilne Webhooks sadaļā Developer.

Jautājums: Vai paroles maiņa ietekmē integrācijas darbu? Atbilde: Nē. Integrācijas strādā pēc API atslēgas, nevis pēc konta paroles.