API-dokumentaatio

Shifton Tehtävät antaa sinulle mahdollisuuden automatisoida alustan käyttöä ja liittää se ulkoisiin palveluihin avoimen API:n kautta. API:n kautta ovat käytettävissä kaikki keskeiset kohteet — tehtävät, asiakkaat, työntekijät, tarkistuslistat, varasto, palvelualueet, Laskutus-asiakirjat ja raportit — joten Shiftonin voi yhdistää HR-, palkanlaskenta- ja analytiikkajärjestelmiisi sekä yrityksen sisäisiin palveluihin.

Dokumentaatio on julkaistu kahtena versiona:

🚀 Uusi dokumentaatio — hakuteoksen ajantasainen versio päivitetyllä rakenteella ja uusimmilla metodeilla: 👉 https://api2.shifton.com/openapi/
📄 Vanha dokumentaatio — edellinen versio (edelleen tuettu olemassa olevia integraatioita varten): 👉 https://api2.shifton.com/docs/

Molemmat versiot voi avata suoraan sovelluksesta — osiossa Developer, välilehdellä Yleiskatsaus, painikkeilla ”Uusi dokumentaatio” ja ”Vanha dokumentaatio”.

Dokumentaatio on saatavilla kahdella kielellä. Uuden dokumentaation sivun oikeassa ylänurkassa on valitsin EN / RU — valittu kieli jää muistiin.

Näin saat API-avaimen

API-avain luodaan itse sovelluksessa:

Avaa osio Developer.
Siirry välilehdelle API-avaimet (”API-avaimet”).
Napsauta ”Luo API-avain”.

Mitä avainta luotaessa täytetään

Avautuu sivupaneeli Luo API-avain, jossa on kentät:

Otsikko — avaimen nimi, pakollinen kenttä. Nimeä se käyttötarkoituksen mukaan, jotta myöhemmin on selvää, mitä poistaa käytöstä: ”Vienti 1C:hen”, ”Analytiikan raportit”.
Vanhenee klo — päivämäärä, jonka jälkeen avain lakkaa toimimasta. Jos kenttä jätetään tyhjäksi, voimassaoloa ei ole rajoitettu.
Käyttöoikeus — avaimen oikeuksien laajuus:
Full access (act as me) — avain toimii sinun nimissäsi ja sinun oikeuksillasi.
Rajoitetut käyttöoikeudet — rajattu joukko oikeuksia, jotka valitset itse.

Napsauta Lisää luodaksesi avaimen tai Peruuta sulkeaksesi paneelin.

📷 *Kuvakaappaus avaimen luontipaneelista — otetaan tuotannossa*

Avain luodaan tiettyä yritystä varten, ja se toimii vain sen tietojen kanssa. Avaimen voi peruuttaa milloin tahansa — peruutus tulee voimaan välittömästi, ja kaikki myöhemmät pyynnöt tällä avaimella palauttavat virheen 401.

Tärkeää: luotu avain näytetään vain yhden kerran. Kopioi se heti ja säilytä luotettavassa paikassa — sitä ei voi saada uudelleen. Jos avain katoaa, luo uusi ja peruuta vanha.

Valtuutus

Kaikki API-pyynnöt allekirjoitetaan avaimella otsakkeessa:

Authorization: Bearer {API_avaimesi}

API:n perusosoite:

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

Pyyntö ilman voimassa olevaa avainta palauttaa 401 ja rungon {"message":"Unauthenticated."}.

Ensimmäinen pyyntö

Esimerkiksi yrityksen työntekijöiden listan hakeminen (lisää oma yrityksesi tunnus merkinnän {companyId} tilalle):

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

Sama curl-komennolla:

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

Yrityksen tunnus näkyy sovelluksen osoiterivillä: app.shifton.com/c/8397/... — luku merkinnän /c/ jälkeen.

Mitä API:n kautta on käytettävissä

Hakuteos kattaa yli 360 metodia. Kenttäpalvelun keskeiset osiot:

Tehtävät — /companies/{companyId}/tasks: luonti, muuttaminen, tilat, tehtävien tiedostot.
Tehtävälista (To Do) — /companies/{companyId}/todo.
Asiakkaat — /companies/{companyId}/clients, sekä asiakkaiden osoitteet ja mukautetut kentät.
Tarkistuslistat — /companies/{companyId}/checklists.
Palvelualueet — /companies/{companyId}/tasks/service-areas.
Taidot — /companies/{companyId}/skills.
Työntekijät — /companies/{companyId}/employees: lisääminen, muokkaaminen, työsuhteen päättäminen ja palauttaminen.
Varasto — nimikkeet, kategoriat, sarjat ja varastosaldot.
Laskutus — tarjoukset, työtilaukset, laskut, kuitit, asiakirjojen laskurit ja logo.
Raportit — työtä ja läsnäoloa koskevien tietojen vienti.

Lisäksi käytettävissä ovat aikataulut ja vuorot, lomat ja vapaapyynnöt, läsnäolo, laskutus ja SMS-laskutus, ilmoitukset ja moduulit.

Webhookit

Jos haluat säännöllisten API-pyyntöjen sijaan saada tapahtumat sillä hetkellä, kun ne syntyvät, käytä webhookeja — välilehti Webhooks osiossa Developer. Shifton lähettää itse pyynnön osoitteeseesi, kun haluttu tapahtuma sattuu; tuettujen tapahtumien listan palauttaa erillinen metodi.

Virhekoodit

Shiftonin API käyttää vakiomuotoisia HTTP-tilakoodeja:

200 — pyyntö suoritettiin onnistuneesti.
201 — kohde luotiin onnistuneesti.
400 — pyynnön parametrit ovat virheellisiä.
401 — valtuutusvirhe: avainta ei ole välitetty, se on virheellinen tai peruutettu.
403 — käyttö on kielletty.
404 — resurssia ei löytynyt (useimmiten kirjoitusvirhe metodin osoitteessa).
500 — palvelinvirhe.

Käyttövinkkejä

Käytä uusissa integraatioissa uutta dokumentaatiota — vanha on jätetty jo toimiville integraatioille.
Pyyntöjen testaamiseen ovat käteviä Postman tai curl — niillä näkee vastauksen kirjoittamatta riviäkään koodia.
Älä säilytä avainta selkokielisenä koodissa äläkä luovuta sitä kolmansille osapuolille: avain antaa pääsyn yrityksen tietoihin.
Noudata pyyntötaajuuden rajoituksia (rate limits) — niiden ylittäminen voi johtaa API-käytön väliaikaiseen estoon.

Usein kysytyt kysymykset

Kysymys: Mistä API-avain saadaan? Vastaus: Sovelluksesta: osio Developer → välilehti API-avaimet → painike ”Luo API-avain”. Avain myönnetään nykyiselle yritykselle.

Kysymys: Suljin ikkunan enkä kopioinut avainta. Mistä sen näkee? Vastaus: Ei mistään — avain näytetään vain yhden kerran, eikä sitä anneta uudelleen. Luo uusi avain ja peruuta vanha.

Kysymys: Miten avain peruutetaan, jos se on joutunut väärille henkilöille? Vastaus: Poista se välilehdellä API-avaimet. Peruutus tulee voimaan välittömästi: kaikki tällä avaimella tehdyt pyynnöt alkavat heti palauttaa 401.

Kysymys: Mitä eroa on ”Full access”- ja ”Restricted permissions” -oikeuksilla? Vastaus: Full access (act as me) antaa avaimelle samat oikeudet, jotka sinulla on. Rajoitetut käyttöoikeudet antaa mahdollisuuden myöntää avaimelle vain valitun joukon oikeuksia — se on turvallisempaa integraatiolle, joka tarvitsee pääsyn vain osaan tiedoista.

Kysymys: Voiko avaimen voimassaoloa rajoittaa? Vastaus: Kyllä, kenttä Vanhenee klo luonnin yhteydessä. Jos sitä ei täytä, avain on voimassa toistaiseksi.

Kysymys: Toimiiko yksi avain useassa yrityksessä? Vastaus: Ei. Avain on sidottu siihen yritykseen, jossa se on luotu, ja toimii vain sen tietojen kanssa. Toista yritystä varten luo erillinen avain.

Kysymys: Mikä on API:n perusosoite? Vastaus: https://api2.shifton.com/work/1.0.0. Sen jälkeen tulee metodin polku, esimerkiksi /companies/{companyId}/tasks.

Kysymys: Mistä saan yrityksen tunnuksen pyyntöihin? Vastaus: Se on sovelluksen osoiterivillä heti merkinnän /c/ jälkeen — esimerkiksi osoitteessa app.shifton.com/c/8397/tasks yrityksen tunnus on 8397.

Kysymys: Kumpaa dokumentaation versiota kannattaa käyttää? Vastaus: Uusissa integraatioissa uutta (api2.shifton.com/openapi). Vanhaa (api2.shifton.com/docs) tuetaan olemassa olevia integraatioita varten.

Kysymys: Onko dokumentaatiota venäjän kielellä? Vastaus: Kyllä. Uuden dokumentaation sivun oikeassa ylänurkassa on valitsin EN / RU.

Kysymys: Millä API-pyyntöjä kannattaa testata? Vastaus: Kätevimmin Postman tai curl — niillä voi lähettää pyyntöjä ja katsoa vastauksia kirjoittamatta koodia.

Kysymys: Miksi tulee 401, vaikka kopioin avaimen? Vastaus: Tarkista, että avain välitetään otsakkeessa Authorization ja sen edessä on sana Bearer, että avainta ei ole peruutettu ja että sen voimassaolo ei ole päättynyt.

Kysymys: Miksi tulee 404? Vastaus: Useimmiten osoite on sekoittunut: perusosan täytyy olla https://api2.shifton.com/work/1.0.0, ja metodin polussa täytyy olla oikea {companyId}.

Kysymys: Mitä API:n kautta voi automatisoida? Vastaus: Tehtävien luontia ja muuttamista, asiakkaiden ja heidän osoitteidensa käsittelyä, tarkistuslistoja, palvelualueita, taitoja, työntekijöitä, varastoa, Laskutus-asiakirjoja ja raporttien vientiä sekä aikatauluja, vuoroja ja lomia.

Kysymys: Voiko Shiftonista saada tapahtumia sen sijaan, että API:ta kysellään? Vastaus: Kyllä, sitä varten ovat webhookit — välilehti Webhooks osiossa Developer.

Kysymys: Vaikuttaako salasanan vaihto integraation toimintaan? Vastaus: Ei. Integraatiot toimivat API-avaimella, ei tilin salasanalla.