API dokumentacija

Shifton Zadaci omogućuje automatizaciju rada s platformom i njezino povezivanje s vanjskim servisima putem otvorenog API-ja. Preko API-ja dostupni su svi ključni entiteti — zadaci, klijenti, zaposlenici, kontrolni popisi, inventar, servisne zone, dokumenti Financijski dokumenti i izvještaji — pa se Shifton može povezati s vašim sustavima HR, obračuna plaća i analitike, kao i s internim servisima kompanije.

Dokumentacija je objavljena u dvije verzije:

🚀 Nova dokumentacija — aktualna verzija priručnika s obnovljenom strukturom i najnovijim metodama: 👉 https://api2.shifton.com/openapi/
📄 Stara dokumentacija — prethodna verzija (i dalje se podržava za postojeće integracije): 👉 https://api2.shifton.com/docs/

Obje verzije možete otvoriti izravno iz aplikacije — u odjeljku Developer, na kartici Pregled, gumbima „Nova dokumentacija” i „Stara dokumentacija”.

Dokumentacija je dostupna na dva jezika. U gornjem desnom kutu stranice nove dokumentacije nalazi se preklopnik EN / RU — odabrani se jezik pamti.

Kako dobiti API ključ

API ključ stvara se u samoj aplikaciji:

Otvorite odjeljak Developer.
Prijeđite na karticu API ključevi („API ključevi”).
Kliknite „Stvori API ključ”.

Što ispuniti pri stvaranju ključa

Otvorit će se bočna ploča Stvori API ključ s poljima:

Naslov — naziv ključa, obavezno polje. Nazivajte ga prema namjeni kako bi poslije bilo jasno što isključiti: „Izvoz u 1C”, „Izvještaji za analitiku”.
Istječe u — datum nakon kojeg ključ prestaje vrijediti. Ako polje ostavite prazno, rok valjanosti nije ograničen.
Pristup — opseg prava ključa:
Full access (act as me) — ključ radi u vaše ime i s vašim pravima.
Ograničena dopuštenja — ograničen skup dopuštenja koji sami odabirete.

Kliknite Dodaj da biste stvorili ključ ili Otkaži da biste zatvorili ploču.

📷 *Snimka ploče za stvaranje ključa — snimiti na produkciji*

Ključ se stvara za konkretnu kompaniju i radi samo s njezinim podacima. Ključ možete opozvati u bilo kojem trenutku — opoziv djeluje odmah i svi sljedeći zahtjevi s tim ključem vratit će pogrešku 401.

Važno: stvoreni se ključ prikazuje samo jedanput. Kopirajte ga odmah i čuvajte na sigurnom mjestu — nije ga moguće dobiti ponovno. Ako je ključ izgubljen, stvorite novi, a stari opozovite.

Autorizacija

Svi zahtjevi prema API-ju potpisuju se ključem u zaglavlju:

Authorization: Bearer {your_API_key}

Osnovna adresa API-ja:

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

Zahtjev bez važećeg ključa vraća 401 i tijelo {"message":"Unauthenticated."}.

Prvi zahtjev

Na primjer, da biste dobili popis zaposlenika kompanije (umjesto {companyId} upišite svoj ID kompanije):

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

Isto to putem curl:

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

ID kompanije vidljiv je u adresnoj traci aplikacije: app.shifton.com/c/8397/... — broj nakon /c/.

Što je dostupno putem API-ja

Priručnik obuhvaća više od 360 metoda. Glavni odjeljci za terensko servisiranje:

Zadaci — /companies/{companyId}/tasks: stvaranje, izmjena, statusi, datoteke zadataka.
Popis obaveza (To Do) — /companies/{companyId}/todo.
Klijenti — /companies/{companyId}/clients, kao i adrese i korisnička polja klijenata.
Kontrolni popisi — /companies/{companyId}/checklists.
Servisne zone — /companies/{companyId}/tasks/service-areas.
Vještine — /companies/{companyId}/skills.
Zaposlenici — /companies/{companyId}/employees: dodavanje, uređivanje, otpuštanje i vraćanje.
Inventar — predmeti, kategorije, kompleti i zalihe u skladištima.
Financijski dokumenti — procjene, radni nalozi, računi, potvrde o plaćanju, brojači dokumenata i logotip.
Izvještaji — izvoz podataka o radu i prisutnosti.

Osim toga, dostupni su rasporedi i smjene, godišnji odmori i zahtjevi za slobodne dane, prisutnost, naplata i SMS naplata, obavijesti i moduli.

Webhookovi

Ako umjesto redovitih zahtjeva prema API-ju trebate primati događaje u trenutku njihova nastanka, upotrijebite webhookove — kartica Webhooks u odjeljku Developer. Shifton će sam poslati zahtjev na vašu adresu kada se dogodi potreban događaj; popis podržanih događaja vraća zasebna metoda.

Kodovi pogrešaka

Shiftonov API koristi standardne HTTP statusne kodove:

200 — zahtjev je uspješno izvršen.
201 — objekt je uspješno stvoren.
400 — neispravni parametri zahtjeva.
401 — pogreška autorizacije: ključ nije poslan, nije važeći ili je opozvan.
403 — pristup je zabranjen.
404 — resurs nije pronađen (najčešće tipfeler u adresi metode).
500 — pogreška poslužitelja.

Savjeti za korištenje

Za nove integracije koristite novu dokumentaciju — stara je ostavljena za integracije koje već rade.
Za provjeru zahtjeva praktični su Postman ili curl — omogućuju da vidite odgovor bez pisanja ijednog retka koda.
Ne čuvajte ključ u otvorenom obliku u kodu i ne predajte ga trećim osobama: ključ daje pristup podacima kompanije.
Poštujte ograničenja učestalosti zahtjeva (rate limits) — njihovo prekoračenje može dovesti do privremenog blokiranja pristupa API-ju.

Česta pitanja

Pitanje: Gdje se dobiva API ključ? Odgovor: U aplikaciji: odjeljak Developer → kartica API ključevi → gumb „Stvori API ključ”. Ključ se izdaje za trenutačnu kompaniju.

Pitanje: Zatvorio sam okno i nisam kopirao ključ. Gdje ga mogu vidjeti? Odgovor: Nigdje — ključ se prikazuje samo jedanput i ne izdaje se ponovno. Stvorite novi ključ, a stari opozovite.

Pitanje: Kako opozvati ključ ako je dospio u pogrešne ruke? Odgovor: Izbrišite ga na kartici API ključevi. Opoziv djeluje odmah: svi zahtjevi s tim ključem odmah počinju vraćati 401.

Pitanje: Po čemu se razlikuju „Full access” i „Restricted permissions”? Odgovor: Full access (act as me) daje ključu ista prava koja imate vi. Ograničena dopuštenja omogućuju da ključu dodijelite samo odabrani skup dopuštenja — tako je sigurnije za integraciju kojoj je potreban pristup samo dijelu podataka.

Pitanje: Može li se ograničiti rok valjanosti ključa? Odgovor: Da, poljem Istječe u pri stvaranju. Ako ga ne ispunite, ključ će biti bezvremenski.

Pitanje: Radi li jedan ključ za nekoliko kompanija? Odgovor: Ne. Ključ je vezan uz kompaniju u kojoj je stvoren i radi samo s njezinim podacima. Za drugu kompaniju stvorite zaseban ključ.

Pitanje: Koja je osnovna adresa API-ja? Odgovor: https://api2.shifton.com/work/1.0.0. Dalje slijedi putanja metode, na primjer /companies/{companyId}/tasks.

Pitanje: Gdje se dobiva ID kompanije za zahtjeve? Odgovor: Nalazi se u adresnoj traci aplikacije odmah nakon /c/ — na primjer, u app.shifton.com/c/8397/tasks identifikator kompanije jest 8397.

Pitanje: Koju verziju dokumentacije koristiti? Odgovor: Za nove integracije — novu (api2.shifton.com/openapi). Stara (api2.shifton.com/docs) podržava se za postojeće integracije.

Pitanje: Postoji li dokumentacija na ruskom jeziku? Odgovor: Da. Na stranici nove dokumentacije, u gornjem desnom kutu, nalazi se preklopnik EN / RU.

Pitanje: Čime testirati zahtjeve prema API-ju? Odgovor: Najpraktičniji su Postman ili curl — omogućuju slanje zahtjeva i pregled odgovora bez pisanja koda.

Pitanje: Zašto dobivam 401 iako sam ključ kopirao? Odgovor: Provjerite šalje li se ključ u zaglavlju Authorization s riječju Bearer ispred njega, je li ključ opozvan i je li mu istekao rok valjanosti.

Pitanje: Zašto dobivam 404? Odgovor: Najčešće je pomiješana adresa: osnovni dio mora biti https://api2.shifton.com/work/1.0.0, a u putanji metode — ispravan {companyId}.

Pitanje: Što se može automatizirati putem API-ja? Odgovor: Stvaranje i izmjenu zadataka, rad s klijentima i njihovim adresama, kontrolne popise, servisne zone, vještine, zaposlenike, inventar, dokumente Financijski dokumenti i izvoz izvještaja, kao i rasporede, smjene i godišnje odmore.

Pitanje: Mogu li se primati događaji iz Shiftona umjesto da se ispituje API? Odgovor: Da, za to postoje webhookovi — kartica Webhooks u odjeljku Developer.

Pitanje: Utječe li promjena lozinke na rad integracije? Odgovor: Ne. Integracije rade po API ključu, a ne po lozinci računa.