Dokumentacija API

Shifton Naloge omogoča avtomatizacijo dela s platformo in njeno povezovanje z zunanjimi storitvami prek odprtega API-ja. Prek API-ja so dostopne vse ključne entitete — naloge, stranke, zaposleni, kontrolni seznami, inventar, območja storitev, dokumenti Finančni dokumenti in poročila —, zato je Shifton mogoče povezati z vašimi sistemi HR, za obračun plač in analitike ter z internimi storitvami podjetja.

Dokumentacija je objavljena v dveh različicah:

🚀 Nova dokumentacija — aktualna različica priročnika s posodobljeno strukturo in najnovejšimi metodami: 👉 https://api2.shifton.com/openapi/
📄 Stara dokumentacija — prejšnja različica (še naprej je podprta za obstoječe integracije): 👉 https://api2.shifton.com/docs/

Obe različici lahko odprete neposredno iz aplikacije — v razdelku Developer, na zavihku Pregled, z gumbi „Nova dokumentacija“ in „Stara dokumentacija“.

Dokumentacija je na voljo v dveh jezikih. V zgornjem desnem kotu strani nove dokumentacije je preklopnik EN / RU — izbrani jezik se zapomni.

Kako dobite API-ključ

API-ključ se ustvari v sami aplikaciji:

Odprite razdelek Developer.
Pojdite na zavihek API ključi („API ključi“).
Kliknite „Ustvari API-ključ“.

Kaj izpolniti pri ustvarjanju ključa

Odprla se bo stranska plošča Ustvari API-ključ s polji:

Naslov — ime ključa, obvezno polje. Poimenujte ga po namenu, da bo pozneje jasno, kaj izklopiti: „Izvoz v 1C“, „Poročila za analitiko“.
Poteče ob — datum, po katerem ključ preneha veljati. Če polje pustite prazno, veljavnost ni omejena.
Dostop — obseg pravic ključa:
Full access (act as me) — ključ deluje v vašem imenu in z vašimi pravicami.
Omejena dovoljenja — omejen nabor dovoljenj, ki ga izberete sami.

Kliknite Dodaj, da ključ ustvarite, ali Prekliči, da ploščo zaprete.

📷 *Posnetek plošče za ustvarjanje ključa — posneti na produkciji*

Ključ se ustvari za določeno podjetje in deluje samo z njegovimi podatki. Ključ lahko prekličete kadar koli — preklic velja takoj in vse nadaljnje zahteve s tem ključem bodo vrnile napako 401.

Pomembno: ustvarjeni ključ se prikaže samo enkrat. Kopirajte ga takoj in ga hranite na zanesljivem mestu — ponovno ga ni mogoče dobiti. Če ključ izgubite, ustvarite nov, starega pa prekličite.

Avtorizacija

Vse zahteve do API-ja se podpišejo s ključem v glavi:

Authorization: Bearer {your_API_key}

Osnovni naslov API-ja:

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

Zahteva brez veljavnega ključa vrne 401 in telo {"message":"Unauthenticated."}.

Prva zahteva

Na primer, če želite dobiti seznam zaposlenih podjetja (namesto {companyId} vstavite svoj ID podjetja):

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

Isto prek curl:

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

ID podjetja je viden v naslovni vrstici aplikacije: app.shifton.com/c/8397/... — številka za /c/.

Kaj je dostopno prek API-ja

Priročnik zajema več kot 360 metod. Glavni razdelki za terensko službo:

Naloge — /companies/{companyId}/tasks: ustvarjanje, spreminjanje, statusi, datoteke nalog.
Seznam opravil (To Do) — /companies/{companyId}/todo.
Stranke — /companies/{companyId}/clients, pa tudi naslovi in uporabniška polja strank.
Kontrolni seznami — /companies/{companyId}/checklists.
Območja storitev — /companies/{companyId}/tasks/service-areas.
Spretnosti — /companies/{companyId}/skills.
Zaposleni — /companies/{companyId}/employees: dodajanje, urejanje, odpuščanje in obnovitev.
Inventar — predmeti, kategorije, kompleti in zaloge v skladiščih.
Finančni dokumenti — ponudbe, delovna naročila, fakture, potrdila o plačilu, števci dokumentov in logotip.
Poročila — izvoz podatkov o delu in prisotnosti.

Poleg tega so na voljo urniki in izmene, dopusti in zahteve za prosti dan, prisotnost, obračun in obračun SMS, obvestila in moduli.

Webhooki

Če želite namesto rednih zahtev do API-ja prejemati dogodke v trenutku, ko nastanejo, uporabite webhooke — zavihek Webhooks v razdelku Developer. Shifton bo sam poslal zahtevo na vaš naslov, ko se bo zgodil ustrezen dogodek; seznam podprtih dogodkov vrne ločena metoda.

Kode napak

API Shifton uporablja standardne kode stanja HTTP:

200 — zahteva je bila uspešno izvedena.
201 — objekt je bil uspešno ustvarjen.
400 — napačni parametri zahteve.
401 — napaka avtorizacije: ključ ni bil poslan, ni veljaven ali je bil preklican.
403 — dostop je prepovedan.
404 — vir ni bil najden (največkrat tipkarska napaka v naslovu metode).
500 — napaka strežnika.

Nasveti za uporabo

Za nove integracije uporabljajte novo dokumentacijo — stara je ostala za že delujoče integracije.
Za preverjanje zahtev sta priročna Postman ali curl — omogočata ogled odgovora, ne da bi napisali eno samo vrstico kode.
Ključa ne hranite v odprti obliki v kodi in ga ne posredujte tretjim osebam: ključ daje dostop do podatkov podjetja.
Upoštevajte omejitve pogostosti zahtev (rate limits) — njihova prekoračitev lahko privede do začasne blokade dostopa do API-ja.

Pogosta vprašanja

Vprašanje: Kje dobim API-ključ? Odgovor: V aplikaciji: razdelek Developer → zavihek API ključi → gumb „Ustvari API-ključ“. Ključ se izda za trenutno podjetje.

Vprašanje: Zaprl sem okno in ključa nisem kopiral. Kje si ga lahko ogledam? Odgovor: Nikjer — ključ se prikaže samo enkrat in se ponovno ne izda. Ustvarite nov ključ, starega pa prekličite.

Vprašanje: Kako prekličem ključ, če je prišel v napačne roke? Odgovor: Izbrišite ga na zavihku API ključi. Preklic velja takoj: vse zahteve s tem ključem bodo takoj začele vračati 401.

Vprašanje: V čem se razlikujeta „Full access“ in „Restricted permissions“? Odgovor: Full access (act as me) daje ključu enake pravice, kot jih imate vi. Omejena dovoljenja omogoča, da ključu izdate samo izbrani nabor dovoljenj — tako je varneje za integracijo, ki potrebuje dostop le do dela podatkov.

Vprašanje: Ali je mogoče omejiti veljavnost ključa? Odgovor: Da, polje Poteče ob pri ustvarjanju. Če ga ne izpolnite, bo ključ neomejen.

Vprašanje: Ali en ključ deluje za več podjetij? Odgovor: Ne. Ključ je vezan na podjetje, v katerem je bil ustvarjen, in deluje samo z njegovimi podatki. Za drugo podjetje ustvarite ločen ključ.

Vprašanje: Kakšen je osnovni naslov API-ja? Odgovor: https://api2.shifton.com/work/1.0.0. Nato sledi pot metode, na primer /companies/{companyId}/tasks.

Vprašanje: Kje dobim ID podjetja za zahteve? Odgovor: Je v naslovni vrstici aplikacije takoj za /c/ — na primer v app.shifton.com/c/8397/tasks je identifikator podjetja enak 8397.

Vprašanje: Katero različico dokumentacije uporabljati? Odgovor: Za nove integracije novo (api2.shifton.com/openapi). Stara (api2.shifton.com/docs) je podprta za obstoječe integracije.

Vprašanje: Ali obstaja dokumentacija v ruskem jeziku? Odgovor: Da. Na strani nove dokumentacije je v zgornjem desnem kotu preklopnik EN / RU.

Vprašanje: S čim testirati zahteve do API-ja? Odgovor: Najbolj priročna sta Postman ali curl — omogočata pošiljanje zahtev in ogled odgovorov brez pisanja kode.

Vprašanje: Zakaj prihaja 401, čeprav sem ključ kopiral? Odgovor: Preverite, da se ključ pošilja v glavi Authorization z besedo Bearer pred njim, da ključ ni preklican in da njegova veljavnost ni potekla.

Vprašanje: Zakaj prihaja 404? Odgovor: Najpogosteje je zamešan naslov: osnovni del mora biti https://api2.shifton.com/work/1.0.0, v poti metode pa mora biti pravilen {companyId}.

Vprašanje: Kaj je mogoče avtomatizirati prek API-ja? Odgovor: Ustvarjanje in spreminjanje nalog, delo s strankami in njihovimi naslovi, kontrolne sezname, območja storitev, spretnosti, zaposlene, inventar, dokumente Finančni dokumenti in izvoz poročil ter urnike, izmene in dopuste.

Vprašanje: Ali je mogoče dogodke prejemati iz Shiftona, namesto da bi poizvedovali po API-ju? Odgovor: Da, za to obstajajo webhooki — zavihek Webhooks v razdelku Developer.

Vprašanje: Ali sprememba gesla vpliva na delovanje integracije? Odgovor: Ne. Integracije delujejo prek API-ključa, ne prek gesla računa.