Dokumentácia k API

Shifton Úlohy umožňuje automatizovať prácu s platformou a pripájať ju k externým službám cez otvorené API. Cez API sú dostupné všetky kľúčové entity — úlohy, klienti, zamestnanci, kontrolné zoznamy, inventár, servisné zóny, dokumenty Finančné dokumenty a správy —, takže Shifton sa dá spojiť s vašimi systémami HR, výpočtu mzdy a analytiky, ako aj s internými službami spoločnosti.

Dokumentácia je zverejnená v dvoch verziách:

🚀 Nová dokumentácia — aktuálna verzia príručky s obnovenou štruktúrou a najnovšími metódami: 👉 https://api2.shifton.com/openapi/
📄 Staré dokumenty — predchádzajúca verzia (stále je podporovaná pre existujúce integrácie): 👉 https://api2.shifton.com/docs/

Obe verzie sa dajú otvoriť priamo z aplikácie — v sekcii Developer, na karte Prehľad, tlačidlami „Nová dokumentácia“ a „Staré dokumenty“.

Dokumentácia je dostupná v dvoch jazykoch. V pravom hornom rohu stránky novej dokumentácie je prepínač EN / RU — vybraný jazyk sa zapamätá.

Ako získať API kľúč

API kľúč sa vytvára v samotnej aplikácii:

Otvorte sekciu Developer.
Prejdite na kartu API kľúče („API kľúče“).
Kliknite na „Vytvoriť kľúč API“.

Čo vyplniť pri vytváraní kľúča

Otvorí sa bočný panel Vytvoriť kľúč API s poľami:

Názov — názov kľúča, povinné pole. Pomenúvajte podľa účelu, aby bolo neskôr jasné, čo vypnúť: „Export do 1C“, „Správy pre analytiku“.
Vyprší o — dátum, po ktorom kľúč prestane platiť. Ak pole ponecháte prázdne, platnosť nie je obmedzená.
Prístup — rozsah oprávnení kľúča:
Full access (act as me) — kľúč pracuje pod vaším menom a s vašimi oprávneniami.
Obmedzené oprávnenia — obmedzená sada povolení, ktorú si vyberáte sami.

Kliknite na Pridať, ak chcete kľúč vytvoriť, alebo na Zrušiť, ak chcete panel zavrieť.

📷 *Snímka panela vytvorenia kľúča — nasnímať na produkcii*

Kľúč sa vytvára pre konkrétnu spoločnosť a funguje iba s jej údajmi. Kľúč sa dá kedykoľvek odvolať — odvolanie platí okamžite a všetky nasledujúce požiadavky s týmto kľúčom vrátia chybu 401.

Dôležité: vytvorený kľúč sa zobrazí iba raz. Skopírujte si ho hneď a uchovávajte na bezpečnom mieste — opakovane ho získať nie je možné. Ak sa kľúč stratí, vytvorte nový a starý odvolajte.

Autorizácia

Všetky požiadavky na API sa podpisujú kľúčom v hlavičke:

Authorization: Bearer {your_API_key}

Základná adresa API:

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

Požiadavka bez platného kľúča vracia 401 a telo {"message":"Unauthenticated."}.

Prvá požiadavka

Napríklad ak chcete získať zoznam zamestnancov spoločnosti (namiesto {companyId} vložte svoje ID spoločnosti):

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

To isté cez curl:

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

ID spoločnosti je vidieť v adresnom riadku aplikácie: app.shifton.com/c/8397/... — číslo po /c/.

Čo je dostupné cez API

Príručka pokrýva viac ako 360 metód. Hlavné sekcie pre výjazdovú obsluhu:

Úlohy — /companies/{companyId}/tasks: vytváranie, zmeny, stavy, súbory úloh.
Zoznam úloh na vykonanie (To Do) — /companies/{companyId}/todo.
Klienti — /companies/{companyId}/clients, a takisto adresy a vlastné polia klientov.
Kontrolné zoznamy — /companies/{companyId}/checklists.
Servisné zóny — /companies/{companyId}/tasks/service-areas.
Zručnosti — /companies/{companyId}/skills.
Zamestnanci — /companies/{companyId}/employees: pridávanie, úpravy, ukončenie pracovného vzťahu a obnovenie.
Inventár — predmety, kategórie, sady a zásoby na skladoch.
Finančné dokumenty — odhady, pracovné objednávky, faktúry, potvrdenky, počítadlá dokumentov a logo.
Správy — export údajov o práci a dochádzke.

Okrem toho sú dostupné rozvrhy a zmeny, dovolenky a žiadosti o voľno, dochádzka, fakturácia a fakturácia SMS, upozornenia a moduly.

Webhooky

Ak namiesto pravidelných požiadaviek na API potrebujete dostávať udalosti v momente ich vzniku, používajte webhooky — karta Webhooks v sekcii Developer. Shifton sám odošle požiadavku na vašu adresu, keď nastane potrebná udalosť; zoznam podporovaných udalostí vracia samostatná metóda.

Kódy chýb

API Shifton používa štandardné stavové kódy HTTP:

200 — požiadavka bola úspešne vykonaná.
201 — objekt bol úspešne vytvorený.
400 — nesprávne parametre požiadavky.
401 — chyba autorizácie: kľúč nebol odoslaný, je neplatný alebo odvolaný.
403 — prístup je zakázaný.
404 — zdroj sa nenašiel (najčastejšie preklep v adrese metódy).
500 — chyba servera.

Tipy na používanie

Pri nových integráciách používajte novú dokumentáciu — stará je ponechaná pre už fungujúce integrácie.
Na overovanie požiadaviek sa hodí Postman alebo curl — umožňujú vidieť odpoveď bez napísania jediného riadka kódu.
Neuchovávajte kľúč v otvorenej podobe v kóde a neposkytujte ho tretím stranám: kľúč dáva prístup k údajom spoločnosti.
Dodržiavajte obmedzenia frekvencie požiadaviek (rate limits) — ich prekročenie môže viesť k dočasnému zablokovaniu prístupu k API.

Často kladené otázky

Otázka: Kde získať API kľúč? Odpoveď: V aplikácii: sekcia Developer → karta API kľúče → tlačidlo „Vytvoriť kľúč API“. Kľúč sa vydáva pre aktuálnu spoločnosť.

Otázka: Zavrel som okno a kľúč som si neskopíroval. Kde si ho zobrazím? Odpoveď: Nikde — kľúč sa zobrazí iba raz a opakovane sa nevydáva. Vytvorte nový kľúč a starý odvolajte.

Otázka: Ako odvolať kľúč, ak sa dostal do nesprávnych rúk? Odpoveď: Odstráňte ho na karte API kľúče. Odvolanie platí okamžite: všetky požiadavky s týmto kľúčom začnú hneď vracať 401.

Otázka: Čím sa odlišujú „Full access“ a „Restricted permissions“? Odpoveď: Full access (act as me) dáva kľúču tie isté oprávnenia, aké máte vy. Obmedzené oprávnenia umožňujú vydať kľúču iba vybranú sadu povolení — tak je to bezpečnejšie pre integráciu, ktorá potrebuje prístup len k časti údajov.

Otázka: Dá sa obmedziť platnosť kľúča? Odpoveď: Áno, pole Vyprší o pri vytváraní. Ak ho nevyplníte, kľúč bude bez časového obmedzenia.

Otázka: Funguje jeden kľúč pre viac spoločností? Odpoveď: Nie. Kľúč je pripojený k spoločnosti, v ktorej bol vytvorený, a funguje iba s jej údajmi. Pre inú spoločnosť vytvorte samostatný kľúč.

Otázka: Aká je základná adresa API? Odpoveď: https://api2.shifton.com/work/1.0.0. Ďalej nasleduje cesta metódy, napríklad /companies/{companyId}/tasks.

Otázka: Kde získať ID spoločnosti pre požiadavky? Odpoveď: Je v adresnom riadku aplikácie hneď po /c/ — napríklad v app.shifton.com/c/8397/tasks je identifikátor spoločnosti 8397.

Otázka: Ktorú verziu dokumentácie používať? Odpoveď: Pri nových integráciách novú (api2.shifton.com/openapi). Stará (api2.shifton.com/docs) je podporovaná pre existujúce integrácie.

Otázka: Existuje dokumentácia v ruštine? Odpoveď: Áno. Na stránke novej dokumentácie je v pravom hornom rohu prepínač EN / RU.

Otázka: Čím testovať požiadavky na API? Odpoveď: Najpohodlnejší je Postman alebo curl — umožňujú odosielať požiadavky a prezerať odpovede bez písania kódu.

Otázka: Prečo prichádza 401, hoci kľúč som skopíroval? Odpoveď: Skontrolujte, či sa kľúč odosiela v hlavičke Authorization so slovom Bearer pred ním, či kľúč nie je odvolaný a či mu neuplynula platnosť.

Otázka: Prečo prichádza 404? Odpoveď: Najčastejšie je zamenená adresa: základná časť musí byť https://api2.shifton.com/work/1.0.0 a v ceste metódy má byť správne {companyId}.

Otázka: Čo sa dá cez API automatizovať? Odpoveď: Vytváranie a zmeny úloh, prácu s klientmi a ich adresami, kontrolné zoznamy, servisné zóny, zručnosti, zamestnancov, inventár, dokumenty Finančné dokumenty a export správ, ako aj rozvrhy, zmeny a dovolenky.

Otázka: Dajú sa dostávať udalosti zo Shiftonu namiesto dopytovania API? Odpoveď: Áno, na to sú webhooky — karta Webhooks v sekcii Developer.

Otázka: Ovplyvňuje zmena hesla fungovanie integrácie? Odpoveď: Nie. Integrácie fungujú na základe API kľúča, nie hesla účtu.