API-dokumentáció

A Shifton Feladatok lehetővé teszi a platformmal végzett munka automatizálását és a platform külső szolgáltatásokhoz való kapcsolását a nyílt API-n keresztül. Az API-n keresztül minden fő entitás elérhető — feladatok, ügyfelek, munkatársak, ellenőrző listák, leltár, szolgáltatási zónák, a Pénzügyi dokumentumok dokumentumai és jelentések —, ezért a Shifton összekapcsolható az Ön HR-, bérszámfejtési és elemzési rendszereivel, valamint a vállalat belső szolgáltatásaival.

A dokumentáció két változatban jelent meg:

🚀 Új dokumentáció — a kézikönyv aktuális változata frissített szerkezettel és a legújabb metódusokkal: 👉 https://api2.shifton.com/openapi/
📄 Régi dokumentáció — az előző változat (a meglévő integrációk esetében továbbra is támogatott): 👉 https://api2.shifton.com/docs/

Mindkét változat megnyitható közvetlenül az alkalmazásból — a Developer szakaszban, az Áttekintés fülön, az „Új dokumentáció” és a „Régi dokumentáció” gombbal.

A dokumentáció két nyelven érhető el. Az új dokumentáció oldalának jobb felső sarkában található egy EN / RU átváltó — a kiválasztott nyelvet megjegyzi a rendszer.

Hogyan szerezzen API-kulcsot

Az API-kulcs magában az alkalmazásban jön létre:

Nyissa meg a Developer szakaszt.
Lépjen az API-kulcsok fülre („API-kulcsok”).
Kattintson az „API-kulcs létrehozása” pontra.

Mit kell megadni a kulcs létrehozásakor

Megnyílik az API-kulcs létrehozása oldalpanel a következő mezőkkel:

Cím — a kulcs neve, kötelező mező. A rendeltetése szerint nevezze el, hogy később világos legyen, mit kell kikapcsolni: „Exportálás az 1C-be”, „Jelentések az elemzéshez”.
Lejár ekkor — az a dátum, amely után a kulcs érvényét veszti. Ha a mezőt üresen hagyja, az érvényesség nincs időben korlátozva.
Hozzáférés — a kulcs jogosultságainak köre:
Full access (act as me) — a kulcs az Ön nevében és az Ön jogosultságaival működik.
Korlátozott jogosultságok — korlátozott engedélykészlet, amelyet Ön maga választ ki.

A kulcs létrehozásához kattintson a Hozzáadás, a panel bezárásához a Törlés gombra.

📷 *A kulcslétrehozó panel képernyőképe — felvenni a prod környezetben*

A kulcs egy konkrét vállalathoz jön létre, és csak annak adataival működik. A kulcs bármikor visszavonható — a visszavonás azonnal érvénybe lép, és az ezzel a kulccsal küldött minden további kérés 401 hibát ad vissza.

Fontos: a létrehozott kulcs csak egyetlen egyszer jelenik meg. Másolja ki azonnal, és tárolja biztonságos helyen — ismételten nem lehet megszerezni. Ha a kulcs elveszett, hozzon létre újat, a régit pedig vonja vissza.

Hitelesítés

Az API-hoz küldött minden kérést a fejlécben szereplő kulccsal írunk alá:

Authorization: Bearer {your_API_key}

Az API alapcíme:

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

Az érvényes kulcs nélküli kérés 401 választ és {"message":"Unauthenticated."} törzset ad vissza.

Az első kérés

Például a vállalat munkatársai listájának megszerzéséhez (a {companyId} helyére írja be a saját vállalati azonosítóját):

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

Ugyanez curl segítségével:

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

A vállalat azonosítója az alkalmazás címsorában látható: app.shifton.com/c/8397/... — a /c/ utáni szám.

Mi érhető el az API-n keresztül

A kézikönyv több mint 360 metódust fed le. A helyszíni szolgáltatás fő szakaszai:

Feladatok — /companies/{companyId}/tasks: létrehozás, módosítás, állapotok, feladatfájlok.
Tennivalólista (To Do) — /companies/{companyId}/todo.
Ügyfelek — /companies/{companyId}/clients, valamint az ügyfelek címei és egyéni mezői.
Ellenőrző listák — /companies/{companyId}/checklists.
Szolgáltatási zónák — /companies/{companyId}/tasks/service-areas.
Készségek — /companies/{companyId}/skills.
Munkatársak — /companies/{companyId}/employees: hozzáadás, szerkesztés, elbocsátás és visszaállítás.
Leltár — tárgyak, kategóriák, készletek és a raktári maradványok.
Pénzügyi dokumentumok — árajánlatok, munkamegrendelések, számlák, nyugták, dokumentumszámlálók és logó.
Jelentések — a munkára és a jelenlétre vonatkozó adatok exportálása.

Ezen kívül elérhetők a beosztások és a műszakok, a szabadságok és a szabadságkérelmek, a jelenlét, a számlázás és az SMS számlázás, az értesítések és a modulok.

Webhookok

Ha a rendszeres API-kérések helyett az eseményeket a bekövetkezésük pillanatában szeretné megkapni, használjon webhookokat — a Webhooks fül a Developer szakaszban található. A Shifton magától küld kérést az Ön címére, amikor a kívánt esemény bekövetkezik; a támogatott események listáját külön metódus adja vissza.

Hibakódok

A Shifton API a szabványos HTTP-állapotkódokat használja:

200 — a kérés sikeresen végrehajtva.
201 — az objektum sikeresen létrejött.
400 — hibás kérésparaméterek.
401 — hitelesítési hiba: a kulcs nincs átadva, érvénytelen vagy visszavonták.
403 — a hozzáférés megtagadva.
404 — az erőforrás nem található (leggyakrabban elírás a metódus címében).
500 — kiszolgálóhiba.

Használati tippek

Új integrációkhoz az új dokumentációt használja — a régi a már működő integrációk számára maradt meg.
A kérések ellenőrzésére kényelmes a Postman vagy a curl — ezekkel egyetlen sor kód megírása nélkül láthatja a választ.
Ne tárolja a kulcsot nyílt formában a kódban, és ne adja át harmadik feleknek: a kulcs hozzáférést ad a vállalat adataihoz.
Tartsa be a kérések gyakoriságára vonatkozó korlátozásokat (rate limits) — ezek túllépése az API-hoz való hozzáférés ideiglenes letiltásához vezethet.

Gyakran ismételt kérdések

Kérdés: Honnan szerezhető API-kulcs? Válasz: Az alkalmazásban: Developer szakasz → API-kulcsok fül → „API-kulcs létrehozása” gomb. A kulcs az aktuális vállalathoz kerül kiadásra.

Kérdés: Bezártam az ablakot, és nem másoltam ki a kulcsot. Hol látható? Válasz: Sehol — a kulcs csak egyszer jelenik meg, és ismételten nem kerül kiadásra. Hozzon létre új kulcsot, a régit pedig vonja vissza.

Kérdés: Hogyan vonható vissza egy illetéktelen kezekbe került kulcs? Válasz: Törölje az API-kulcsok fülön. A visszavonás azonnal érvénybe lép: az ezzel a kulccsal küldött minden kérés azonnal 401 hibát ad vissza.

Kérdés: Miben különbözik a „Full access” és a „Restricted permissions”? Válasz: A Full access (act as me) ugyanazokat a jogosultságokat adja a kulcsnak, amelyekkel Ön rendelkezik. A Korlátozott jogosultságok lehetővé teszi, hogy csak a kiválasztott engedélykészletet adja ki a kulcsnak — így biztonságosabb az olyan integrációhoz, amelynek csak az adatok egy részéhez kell hozzáférnie.

Kérdés: Korlátozható a kulcs érvényességi ideje? Válasz: Igen, a létrehozáskor a Lejár ekkor mezőben. Ha nem tölti ki, a kulcs időbeli korlátozás nélkül érvényes.

Kérdés: Működik egy kulcs több vállalathoz is? Válasz: Nem. A kulcs ahhoz a vállalathoz kötődik, amelyben létrejött, és csak annak adataival működik. Másik vállalathoz hozzon létre külön kulcsot.

Kérdés: Mi az API alapcíme? Válasz: https://api2.shifton.com/work/1.0.0. Ezt követi a metódus útvonala, például /companies/{companyId}/tasks.

Kérdés: Honnan szerezhető meg a vállalat azonosítója a kérésekhez? Válasz: Megtalálható az alkalmazás címsorában közvetlenül a /c/ után — például az app.shifton.com/c/8397/tasks címben a vállalat azonosítója 8397.

Kérdés: A dokumentáció melyik változatát használja? Válasz: Új integrációkhoz az újat (api2.shifton.com/openapi). A régi (api2.shifton.com/docs) a meglévő integrációk esetében támogatott.

Kérdés: Van orosz nyelvű dokumentáció? Válasz: Igen. Az új dokumentáció oldalának jobb felső sarkában található az EN / RU átváltó.

Kérdés: Mivel tesztelhetők az API-kérések? Válasz: Legkényelmesebb a Postman vagy a curl — ezekkel kód írása nélkül küldhet kéréseket és tekintheti meg a válaszokat.

Kérdés: Miért kapok 401-et, holott kimásoltam a kulcsot? Válasz: Ellenőrizze, hogy a kulcs az Authorization fejlécben, előtte a Bearer szóval kerül-e átadásra, hogy a kulcsot nem vonták-e vissza, és hogy nem járt-e le az érvényessége.

Kérdés: Miért kapok 404-et? Válasz: Leggyakrabban a cím van elírva: az alapnak https://api2.shifton.com/work/1.0.0-nak kell lennie, a metódus útvonalában pedig a helyes {companyId} szerepeljen.

Kérdés: Mi automatizálható az API-n keresztül? Válasz: A feladatok létrehozása és módosítása, az ügyfelekkel és azok címeivel végzett munka, az ellenőrző listák, a szolgáltatási zónák, a készségek, a munkatársak, a leltár, a Pénzügyi dokumentumok dokumentumai és a jelentések exportálása, valamint a beosztások, a műszakok és a szabadságok.

Kérdés: Kaphatók események a Shiftonból az API lekérdezése helyett? Válasz: Igen, ehhez vannak a webhookok — a Webhooks fül a Developer szakaszban.

Kérdés: Hatással van a jelszó módosítása az integráció működésére? Válasz: Nem. Az integrációk API-kulccsal működnek, nem a fiók jelszavával.