API-dokumentation

Shifton Uppgifter låter dig automatisera arbetet med plattformen och koppla den till externa tjänster via ett öppet API. Via API:et är alla nyckelobjekt tillgängliga — uppgifter, kunder, anställda, checklistor, inventarium, serviceområden, dokument i Finansiella dokument och rapporter — så Shifton kan kopplas ihop med dina system för HR, löneberäkning och analys samt med företagets interna tjänster.

Dokumentationen är publicerad i två versioner:

🚀 Ny dokumentation — den aktuella versionen av referensen med uppdaterad struktur och de senaste metoderna: 👉 https://api2.shifton.com/openapi/
📄 Gammal dokumentation — den föregående versionen (stöds fortfarande för befintliga integrationer): 👉 https://api2.shifton.com/docs/

Båda versionerna kan öppnas direkt från appen — i avsnittet Developer, på fliken Översikt, med knapparna ”Ny dokumentation” och ”Gammal dokumentation”.

Dokumentationen finns på två språk. I det övre högra hörnet på sidan med den nya dokumentationen finns en växlare EN / RU — det valda språket sparas.

Så skaffar du en API-nyckel

API-nyckeln skapas i själva appen:

Öppna avsnittet Developer.
Gå till fliken API-nycklar (”API-nycklar”).
Klicka på ”Skapa API-nyckel”.

Vad du fyller i när nyckeln skapas

Sidopanelen Skapa API-nyckel öppnas med följande fält:

Titel — nyckelns namn, obligatoriskt fält. Namnge den efter användningsområdet, så att det senare är tydligt vad som ska stängas av: ”Export till 1C”, ”Rapporter för analys”.
Löper ut kl. — det datum då nyckeln slutar gälla. Om fältet lämnas tomt är giltighetstiden obegränsad.
Åtkomst — nyckelns behörighetsomfång:
Full access (act as me) — nyckeln arbetar i ditt namn och med dina behörigheter.
Begränsade behörigheter — en begränsad uppsättning behörigheter som du väljer själv.

Klicka på Lägg till för att skapa nyckeln, eller på Avbryt för att stänga panelen.

📷 *Skärmbild av panelen för att skapa en nyckel — tas i prod*

Nyckeln skapas för ett specifikt företag och fungerar bara med dess data. Nyckeln kan återkallas när som helst — återkallelsen gäller omedelbart, och alla efterföljande förfrågningar med den nyckeln returnerar felet 401.

Viktigt: den skapade nyckeln visas bara en gång. Kopiera den direkt och förvara den på ett säkert ställe — den går inte att få fram igen. Om nyckeln tappas bort skapar du en ny och återkallar den gamla.

Auktorisering

Alla förfrågningar till API:et signeras med nyckeln i rubriken:

Authorization: Bearer {din_API_nyckel}

API:ets basadress:

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

En förfrågan utan en giltig nyckel returnerar 401 och kroppen {"message":"Unauthenticated."}.

Den första förfrågan

Till exempel för att hämta listan över företagets anställda (sätt in ditt eget företags-ID i stället för {companyId}):

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

Samma sak via curl:

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

Företags-ID:t syns i appens adressfält: app.shifton.com/c/8397/... — talet efter /c/.

Vad som är tillgängligt via API:et

Referensen omfattar mer än 360 metoder. Huvudavsnitten för utgående service:

Uppgifter — /companies/{companyId}/tasks: skapande, ändring, statusar, uppgiftsfiler.
Att göra-lista (To Do) — /companies/{companyId}/todo.
Kunder — /companies/{companyId}/clients, samt kundernas adresser och anpassade fält.
Checklistor — /companies/{companyId}/checklists.
Serviceområden — /companies/{companyId}/tasks/service-areas.
Färdigheter — /companies/{companyId}/skills.
Anställda — /companies/{companyId}/employees: tillägg, redigering, avslut och återställning.
Inventarium — artiklar, kategorier, set och lagersaldon.
Finansiella dokument — offerter, arbetsordrar, fakturor, kvitton, dokumenträknare och logotyp.
Rapporter — export av data om arbete och närvaro.

Dessutom är scheman och skift, semester och ledighetsansökningar, närvaro, fakturering och SMS-fakturering, aviseringar och moduler tillgängliga.

Webhooks

Om du i stället för regelbundna förfrågningar till API:et behöver få händelser i samma stund som de inträffar använder du webhooks — fliken Webhooks i avsnittet Developer. Shifton skickar själv en förfrågan till din adress när den önskade händelsen inträffar; listan över händelser som stöds returneras av en separat metod.

Felkoder

Shiftons API använder standardiserade HTTP-statuskoder:

200 — förfrågan utfördes utan problem.
201 — objektet skapades.
400 — felaktiga parametrar i förfrågan.
401 — auktoriseringsfel: nyckeln skickades inte med, är ogiltig eller har återkallats.
403 — åtkomst nekad.
404 — resursen hittades inte (oftast ett stavfel i metodens adress).
500 — serverfel.

Tips för användningen

Använd den nya dokumentationen för nya integrationer — den gamla finns kvar för integrationer som redan fungerar.
För att kontrollera förfrågningar är Postman eller curl praktiska — med dem ser du svaret utan att skriva en enda rad kod.
Förvara inte nyckeln i klartext i koden och lämna inte ut den till tredje part: nyckeln ger åtkomst till företagets data.
Följ begränsningarna för antal förfrågningar (rate limits) — om de överskrids kan åtkomsten till API:et blockeras tillfälligt.

Vanliga frågor

Fråga: Var får man tag på en API-nyckel? Svar: I appen: avsnittet Developer → fliken API-nycklar → knappen ”Skapa API-nyckel”. Nyckeln utfärdas för det aktuella företaget.

Fråga: Jag stängde fönstret och kopierade inte nyckeln. Var kan jag se den? Svar: Ingenstans — nyckeln visas bara en gång och utfärdas inte igen. Skapa en ny nyckel och återkalla den gamla.

Fråga: Hur återkallar man en nyckel som har hamnat i fel händer? Svar: Ta bort den på fliken API-nycklar. Återkallelsen gäller omedelbart: alla förfrågningar med den nyckeln börjar direkt returnera 401.

Fråga: Vad är skillnaden mellan ”Full access” och ”Restricted permissions”? Svar: Full access (act as me) ger nyckeln samma behörigheter som du har. Begränsade behörigheter gör att du kan ge nyckeln endast en utvald uppsättning behörigheter — det är säkrare för en integration som bara behöver åtkomst till en del av datan.

Fråga: Kan man begränsa nyckelns giltighetstid? Svar: Ja, fältet Löper ut kl. när nyckeln skapas. Om det inte fylls i gäller nyckeln utan tidsgräns.

Fråga: Fungerar en och samma nyckel för flera företag? Svar: Nej. Nyckeln är kopplad till det företag där den skapades och fungerar bara med dess data. Skapa en separat nyckel för ett annat företag.

Fråga: Vilken basadress har API:et? Svar: https://api2.shifton.com/work/1.0.0. Därefter följer metodens sökväg, till exempel /companies/{companyId}/tasks.

Fråga: Var hittar man företags-ID:t för förfrågningarna? Svar: Det finns i appens adressfält direkt efter /c/ — till exempel i app.shifton.com/c/8397/tasks är företagets identifierare 8397.

Fråga: Vilken version av dokumentationen ska man använda? Svar: För nya integrationer — den nya (api2.shifton.com/openapi). Den gamla (api2.shifton.com/docs) stöds för befintliga integrationer.

Fråga: Finns dokumentationen på ryska? Svar: Ja. På sidan med den nya dokumentationen finns växlaren EN / RU i det övre högra hörnet.

Fråga: Vad testar man API-förfrågningar med? Svar: Enklast är Postman eller curl — med dem kan du skicka förfrågningar och se svaren utan att skriva kod.

Fråga: Varför får jag 401 trots att jag kopierade nyckeln? Svar: Kontrollera att nyckeln skickas i rubriken Authorization med ordet Bearer framför, att nyckeln inte är återkallad och att giltighetstiden inte har gått ut.

Fråga: Varför får jag 404? Svar: Oftast är adressen förväxlad: basdelen ska vara https://api2.shifton.com/work/1.0.0, och i metodens sökväg ska rätt {companyId} anges.

Fråga: Vad kan man automatisera via API:et? Svar: Skapande och ändring av uppgifter, arbete med kunder och deras adresser, checklistor, serviceområden, färdigheter, anställda, inventarium, dokument i Finansiella dokument och export av rapporter, samt scheman, skift och semester.

Fråga: Kan man ta emot händelser från Shifton i stället för att fråga API:et? Svar: Ja, för det finns webhooks — fliken Webhooks i avsnittet Developer.

Fråga: Påverkar ett lösenordsbyte integrationens funktion? Svar: Nej. Integrationerna fungerar med API-nyckeln, inte med kontots lösenord.