Shifton Zadania pozwala zautomatyzować pracę z platformą i połączyć ją z zewnętrznymi serwisami przez otwarte API. Przez API dostępne są wszystkie kluczowe obiekty — zadania, klienci, pracownicy, listy kontrolne, inwentarz, strefy obsługi, dokumenty Dokumenty finansowe i raporty — dlatego Shifton można powiązać z Twoimi systemami HR, obliczania wynagrodzeń i analityki, a także z wewnętrznymi serwisami firmy.
Dokumentacja API
Dokumentacja jest opublikowana w dwóch wersjach:
- 🚀 Nowa dokumentacja — aktualna wersja przewodnika ze zaktualizowaną strukturą i najnowszymi metodami: 👉 https://api2.shifton.com/openapi/
- 📄 Stara dokumentacja — poprzednia wersja (nadal wspierana dla istniejących integracji): 👉 https://api2.shifton.com/docs/
Otworzyć obie wersje można bezpośrednio z aplikacji — w sekcji Developer, na karcie Przegląd, przyciskami „Nowa dokumentacja” i „Stara dokumentacja”.
Dokumentacja jest dostępna w dwóch językach. W prawym górnym narożniku strony nowej dokumentacji jest przełącznik EN / RU — wybrany język jest zapamiętywany.
Jak otrzymać klucz API
Klucz API tworzy się w samej aplikacji:
- Otwórz sekcję Developer.
- Przejdź na kartę Klucze API („Klucze API”).
- Kliknij „Utwórz klucz API”.
Co wypełnić przy tworzeniu klucza
Otworzy się panel boczny Utwórz klucz API z polami:
- tytuł — nazwa klucza, pole obowiązkowe. Nazywaj według przeznaczenia, aby później było jasne, co wyłączyć: „Eksport do 1C”, „Raporty dla analityki”.
- Wygasa o — data, po której klucz przestanie działać. Jeśli pole zostanie puste, okres ważności jest nieograniczony.
- Dostęp — zakres uprawnień klucza:
- Full access (act as me) — klucz działa w Twoim imieniu i z Twoimi uprawnieniami.
- Ograniczone uprawnienia — ograniczony zestaw uprawnień, który wybierasz sam.
Kliknij Dodać, aby utworzyć klucz, albo Anulować, aby zamknąć panel.
📷 *Zrzut panelu tworzenia klucza — zrobić na prodzie*
Klucz tworzony jest dla konkretnej firmy i działa tylko z jej danymi. Odwołać klucz można w dowolnym momencie — odwołanie działa natychmiast i wszystkie kolejne zapytania z tym kluczem zwrócą błąd 401.
Ważne: utworzony klucz jest pokazywany tylko jeden raz. Skopiuj go od razu i przechowuj w bezpiecznym miejscu — otrzymać go ponownie nie można. Jeśli klucz został utracony, utwórz nowy, a stary odwołaj.
Autoryzacja
Wszystkie zapytania do API podpisywane są kluczem w nagłówku:
Authorization: Bearer {your_API_key}Adres bazowy API:
https://api2.shifton.com/work/1.0.0Zapytanie bez działającego klucza zwraca 401 i treść {"message":"Unauthenticated."}.
Najczęściej zadawane pytania
Na przykład, aby otrzymać listę pracowników firmy (podstaw swoje ID firmy w miejsce {companyId}):
GET https://api2.shifton.com/work/1.0.0/companies/{companyId}/employees
Authorization: Bearer {your_API_key}
Accept: application/jsonTo samo przez curl:
curl -H "Authorization: Bearer {your_API_key}" \
-H "Accept: application/json" \
https://api2.shifton.com/work/1.0.0/companies/{companyId}/employeesID firmy jest widoczne w pasku adresu aplikacji: app.shifton.com/c/8397/... — liczba po /c/.
Co jest dostępne przez API
Przewodnik obejmuje ponad 360 metod. Główne sekcje dla obsługi wyjazdowej:
- Zadania —
/companies/{companyId}/tasks: tworzenie, zmiany, statusy, pliki zadań. - Lista spraw (To Do) —
/companies/{companyId}/todo. - Klienci —
/companies/{companyId}/clients, a także adresy i pola użytkownika klientów. - Listy kontrolne —
/companies/{companyId}/checklists. - Strefy obsługi —
/companies/{companyId}/tasks/service-areas. - Umiejętności —
/companies/{companyId}/skills. - Pracownicy —
/companies/{companyId}/employees: dodawanie, edytowanie, zwalnianie i przywracanie. - Inwentarz — przedmioty, kategorie, zestawy i stany w magazynach.
- Dokumenty finansowe — kosztorysy, zlecenia pracy, faktury, pokwitowania, liczniki dokumentów i logo.
- Raporty — eksport danych o pracy i obecności.
Poza tym dostępne są harmonogramy i zmiany, urlopy i wnioski o wolne, obecność, rozliczenia i rozliczenia SMS, powiadomienia oraz moduły.
Webhooki
Jeśli zamiast regularnych zapytań do API chcesz otrzymywać zdarzenia w momencie ich wystąpienia, użyj webhooków — karta Webhooks w sekcji Developer. Shifton sam wyśle zapytanie na Twój adres, gdy nastąpi potrzebne zdarzenie; listę wspieranych zdarzeń zwraca osobna metoda.
Kody błędów
API Shifton używa standardowych kodów stanu HTTP:
- 200 — zapytanie wykonane pomyślnie.
- 201 — obiekt utworzony pomyślnie.
- 400 — nieprawidłowe parametry zapytania.
- 401 — błąd autoryzacji: klucz nie został przekazany, jest nieważny lub odwołany.
- 403 — dostęp zabroniony.
- 404 — zasób nie znaleziony (najczęściej literówka w adresie metody).
- 500 — błąd serwera.
Wskazówki dotyczące korzystania
- Do nowych integracji używaj nowej dokumentacji — stara została zachowana dla już działających integracji.
- Do sprawdzania zapytań wygodne są Postman albo curl — pozwalają zobaczyć odpowiedź bez napisania ani jednej linijki kodu.
- Nie przechowuj klucza w postaci otwartej w kodzie i nie przekazuj go osobom trzecim: klucz daje dostęp do danych firmy.
- Przestrzegaj ograniczeń częstotliwości zapytań (rate limits) — ich przekroczenie może doprowadzić do czasowego zablokowania dostępu do API.
Najczęściej zadawane pytania
Pytanie: Gdzie wziąć klucz API? Odpowiedź: W aplikacji: sekcja Developer → karta Klucze API → przycisk „Utwórz klucz API”. Klucz wydawany jest dla bieżącej firmy.
Pytanie: Zamknąłem okno i nie skopiowałem klucza. Gdzie go zobaczyć? Odpowiedź: Nigdzie — klucz jest pokazywany tylko jeden raz i nie jest wydawany ponownie. Utwórz nowy klucz, a stary odwołaj.
Pytanie: Jak odwołać klucz, jeśli trafił w niewłaściwe ręce? Odpowiedź: Usuń go na karcie Klucze API. Odwołanie działa natychmiast: wszystkie zapytania z tym kluczem od razu zaczną zwracać 401.
Pytanie: Czym różnią się „Full access” i „Restricted permissions”? Odpowiedź: Full access (act as me) daje kluczowi te same uprawnienia, jakie masz Ty. Ograniczone uprawnienia pozwalają wydać kluczowi tylko wybrany zestaw uprawnień — tak jest bezpieczniej dla integracji, której potrzebny jest dostęp jedynie do części danych.
Pytanie: Czy można ograniczyć okres ważności klucza? Odpowiedź: Tak, pole Wygasa o przy tworzeniu. Jeśli nie zostanie wypełnione, klucz będzie bezterminowy.
Pytanie: Czy jeden klucz działa dla kilku firm? Odpowiedź: Nie. Klucz jest przypisany do firmy, w której został utworzony, i działa tylko z jej danymi. Dla innej firmy utwórz osobny klucz.
Pytanie: Jaki jest adres bazowy API? Odpowiedź: https://api2.shifton.com/work/1.0.0. Dalej idzie ścieżka metody, na przykład /companies/{companyId}/tasks.
Pytanie: Gdzie wziąć ID firmy do zapytań? Odpowiedź: Jest w pasku adresu aplikacji od razu po /c/ — na przykład w app.shifton.com/c/8397/tasks identyfikator firmy to 8397.
Pytanie: Której wersji dokumentacji używać? Odpowiedź: Do nowych integracji — nowej (api2.shifton.com/openapi). Stara (api2.shifton.com/docs) jest wspierana dla istniejących integracji.
Pytanie: Czy jest dokumentacja w języku rosyjskim? Odpowiedź: Tak. Na stronie nowej dokumentacji w prawym górnym narożniku jest przełącznik EN / RU.
Pytanie: Czym testować zapytania do API? Odpowiedź: Najwygodniej Postman albo curl — pozwalają wysyłać zapytania i przeglądać odpowiedzi bez pisania kodu.
Pytanie: Dlaczego przychodzi 401, chociaż klucz skopiowałem? Odpowiedź: Sprawdź, czy klucz przekazywany jest w nagłówku Authorization ze słowem Bearer przed nim, czy klucz nie został odwołany i czy nie upłynął okres jego ważności.
Pytanie: Dlaczego przychodzi 404? Odpowiedź: Najczęściej pomylony jest adres: część bazowa powinna być https://api2.shifton.com/work/1.0.0, a w ścieżce metody — prawidłowy {companyId}.
Pytanie: Co można zautomatyzować przez API? Odpowiedź: Tworzenie i zmienianie zadań, pracę z klientami i ich adresami, listy kontrolne, strefy obsługi, umiejętności, pracowników, inwentarz, dokumenty Dokumenty finansowe i eksport raportów, a także harmonogramy, zmiany i urlopy.
Pytanie: Czy można otrzymywać zdarzenia z Shifton, a nie odpytywać API? Odpowiedź: Tak, do tego są webhooki — karta Webhooks w sekcji Developer.
Pytanie: Czy zmiana hasła wpływa na działanie integracji? Odpowiedź: Nie. Integracje działają na kluczu API, a nie na haśle konta.