Dokumentace k API

Shifton Úkoly umožňuje automatizovat práci s platformou a propojit ji s externími službami přes otevřené API. Přes API jsou dostupné všechny klíčové entity — úkoly, klienti, zaměstnanci, kontrolní seznamy, inventář, obslužné zóny, dokumenty modulu Finanční dokumenty a zprávy — takže Shifton lze propojit s vašimi systémy HR, výpočtu mezd a analytiky i s interními službami společnosti.

Dokumentace k API

Dokumentace je publikována ve dvou verzích:

• 🚀 Nová dokumentace — aktuální verze příručky s aktualizovanou strukturou a nejnovějšími metodami: 👉 https://api2.shifton.com/openapi/
• 📄 Staré dokumentace — předchozí verze (nadále podporovaná pro stávající integrace): 👉 https://api2.shifton.com/docs/

Obě verze lze otevřít přímo z aplikace — v části Developer, na záložce Přehled, tlačítky „Nová dokumentace“ a „Staré dokumentace“.

Dokumentace je dostupná ve dvou jazycích. V pravém horním rohu stránky nové dokumentace je přepínač EN / RU — vybraný jazyk se zapamatuje.

Jak získat klíč API

Klíč API se vytváří přímo v aplikaci:

• Otevřete část Developer.
• Přejděte na záložku API klíče („API klíče“).
• Klikněte na „Vytvořit klíč API“.

Co vyplnit při vytváření klíče

Otevře se boční panel Vytvořit klíč API s poli:

• Název — název klíče, povinné pole. Pojmenujte ho podle účelu, aby bylo později jasné, co vypnout: „Export do 1C“, „Zprávy pro analytiku“.
• Platí do — datum, po kterém klíč přestane platit. Pokud pole necháte prázdné, platnost není omezena.
• Přístup — rozsah oprávnění klíče:
• Full access (act as me) — klíč pracuje vaším jménem a s vašimi právy.
• Omezená oprávnění — omezená sada oprávnění, kterou si vyberete sami.

Klikněte na Přidat, chcete-li klíč vytvořit, nebo na Zrušit, chcete-li panel zavřít.

📷 *Snímek panelu vytvoření klíče — pořídit na produkci*

Klíč se vytváří pro konkrétní společnost a pracuje pouze s jejími daty. Klíč lze kdykoli odvolat — odvolání platí okamžitě a všechny následné požadavky s tímto klíčem vrátí chybu 401.

Důležité: vytvořený klíč se zobrazí pouze jednou. Zkopírujte si ho hned a uložte na bezpečné místo — znovu ho získat nelze. Pokud klíč ztratíte, vytvořte nový a starý odvolejte.

Autorizace

Všechny požadavky na API se podepisují klíčem v hlavičce:

Authorization: Bearer {your_API_key}

Základní adresa API:

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

Požadavek bez platného klíče vrací 401 a tělo {"message":"Unauthenticated."}.

První požadavek

Například pro získání seznamu zaměstnanců společnosti (místo {companyId} doplňte své ID společnosti):

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

Totéž přes curl:

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

ID společnosti je vidět v adresním řádku aplikace: app.shifton.com/c/8397/... — číslo za /c/.

Co je dostupné přes API

Příručka pokrývá více než 360 metod. Hlavní části pro terénní obsluhu:

• Úkoly — /companies/{companyId}/tasks: vytváření, změny, stavy, soubory úkolů.
• Seznam činností (To Do) — /companies/{companyId}/todo.
• Klienti — /companies/{companyId}/clients, a také adresy a uživatelská pole klientů.
• Kontrolní seznamy — /companies/{companyId}/checklists.
• Obslužné zóny — /companies/{companyId}/tasks/service-areas.
• Dovednosti — /companies/{companyId}/skills.
• Zaměstnanci — /companies/{companyId}/employees: přidání, úprava, propuštění a obnovení.
• Inventář — položky, kategorie, sady a zůstatky na skladech.
• Finanční dokumenty — odhady, pracovní příkazy, faktury, účtenky, počítadla dokumentů a logo.
• Zprávy — export dat o práci a docházce.

Kromě toho jsou dostupné rozpisy a směny, dovolené a žádosti o volno, docházka, fakturace a SMS účtování, oznámení a moduly.

Webhooky

Pokud místo pravidelných dotazů na API potřebujete dostávat události v okamžiku jejich vzniku, použijte webhooky — záložka Webhooks v části Developer. Shifton sám odešle požadavek na vaši adresu, jakmile nastane potřebná událost; seznam podporovaných událostí vrací samostatná metoda.

Chybové kódy

API Shifton používá standardní stavové kódy HTTP:

• 200 — požadavek byl úspěšně proveden.
• 201 — objekt byl úspěšně vytvořen.
• 400 — nesprávné parametry požadavku.
• 401 — chyba autorizace: klíč nebyl předán, je neplatný nebo byl odvolán.
• 403 — přístup zamítnut.
• 404 — zdroj nenalezen (nejčastěji překlep v adrese metody).
• 500 — chyba serveru.

Tipy pro používání

• Pro nové integrace používejte novou dokumentaci — stará zůstala pro již fungující integrace.
• K ověřování požadavků se hodí Postman nebo curl — umožňují zobrazit odpověď, aniž byste napsali jediný řádek kódu.
• Neukládejte klíč v otevřené podobě v kódu a nepředávejte ho třetím osobám: klíč dává přístup k datům společnosti.
• Dodržujte omezení frekvence požadavků (rate limits) — jejich překročení může vést k dočasnému zablokování přístupu k API.

Často kladené otázky

Otázka: Kde získat klíč API? Odpověď: V aplikaci: část Developer → záložka API klíče → tlačítko „Vytvořit klíč API“. Klíč se vydává pro aktuální společnost.

Otázka: Zavřel jsem okno a klíč jsem si nezkopíroval. Kde si ho mohu zobrazit? Odpověď: Nikde — klíč se zobrazuje pouze jednou a znovu se nevydává. Vytvořte nový klíč a starý odvolejte.

Otázka: Jak klíč odvolat, pokud se dostal do nesprávných rukou? Odpověď: Smažte ho na záložce API klíče. Odvolání platí okamžitě: všechny požadavky s tímto klíčem začnou ihned vracet 401.

Otázka: Čím se liší „Full access“ a „Restricted permissions“? Odpověď: Full access (act as me) dává klíči stejná práva, jaká máte vy. Omezená oprávnění umožňují dát klíči pouze vybranou sadu oprávnění — to je bezpečnější pro integraci, která potřebuje přístup jen k části dat.

Otázka: Lze omezit dobu platnosti klíče? Odpověď: Ano, pole Platí do při vytváření. Pokud ho nevyplníte, bude klíč bez omezení platnosti.

Otázka: Funguje jeden klíč pro několik společností? Odpověď: Ne. Klíč je vázán na společnost, ve které byl vytvořen, a pracuje pouze s jejími daty. Pro jinou společnost vytvořte samostatný klíč.

Otázka: Jaká je základní adresa API? Odpověď: https://api2.shifton.com/work/1.0.0. Dál následuje cesta metody, například /companies/{companyId}/tasks.

Otázka: Kde získat ID společnosti pro požadavky? Odpověď: Je v adresním řádku aplikace hned za /c/ — například v app.shifton.com/c/8397/tasks je identifikátor společnosti 8397.

Otázka: Kterou verzi dokumentace používat? Odpověď: Pro nové integrace novou (api2.shifton.com/openapi). Stará (api2.shifton.com/docs) je podporovaná pro stávající integrace.

Otázka: Existuje dokumentace v ruštině? Odpověď: Ano. Na stránce nové dokumentace je v pravém horním rohu přepínač EN / RU.

Otázka: Čím testovat požadavky na API? Odpověď: Nejpohodlnější jsou Postman nebo curl — umožňují odesílat požadavky a prohlížet odpovědi bez psaní kódu.

Otázka: Proč přichází 401, i když jsem klíč zkopíroval? Odpověď: Zkontrolujte, že se klíč předává v hlavičce Authorization se slovem Bearer před ním, že klíč nebyl odvolán a že mu neskončila platnost.

Otázka: Proč přichází 404? Odpověď: Nejčastěji je zaměněná adresa: základní část musí být https://api2.shifton.com/work/1.0.0 a v cestě metody musí být správné {companyId}.

Otázka: Co lze přes API automatizovat? Odpověď: Vytváření a změny úkolů, práci s klienty a jejich adresami, kontrolní seznamy, obslužné zóny, dovednosti, zaměstnance, inventář, dokumenty modulu Finanční dokumenty a export zpráv, a také rozpisy, směny a dovolené.

Otázka: Lze dostávat události ze Shiftonu místo dotazování API? Odpověď: Ano, k tomu slouží webhooky — záložka Webhooks v části Developer.

Otázka: Ovlivňuje změna hesla fungování integrace? Odpověď: Ne. Integrace fungují na základě klíče API, nikoli hesla k účtu.