API-dokumentation

Shifton Feltservice giver dig mulighed for at automatisere arbejdet med platformen og forbinde den til eksterne tjenester via et åbent API. Gennem API’et er alle centrale enheder tilgængelige — opgaver, kunder, medarbejdere, tjeklister, inventar, serviceområder, dokumenter i Fakturering og rapporter — så Shifton kan kobles sammen med dine systemer til HR, lønberegning og analyse samt med virksomhedens interne tjenester.

Dokumentationen er udgivet i to versioner:

🚀 Ny dokumentation — den aktuelle version af opslagsværket med opdateret struktur og de nyeste metoder: 👉 https://api2.shifton.com/openapi/
📄 Gammel dokumentation — den forrige version (understøttes stadig for eksisterende integrationer): 👉 https://api2.shifton.com/docs/

Begge versioner kan åbnes direkte fra applikationen — i afsnittet Developer, på fanen Oversigt, med knapperne ”Ny dokumentation” og ”Gammel dokumentation”.

Dokumentationen findes på to sprog. Øverst til højre på siden med den nye dokumentation er der en omskifter, EN / RU — det valgte sprog huskes.

Sådan får du en API-nøgle

API-nøglen oprettes i selve applikationen:

Åbn afsnittet Developer.
Gå til fanen API-nøgler (”API-nøgler”).
Klik på ”Opret API-nøgle”.

Hvad du skal udfylde, når du opretter en nøgle

Sidepanelet Opret API-nøgle åbnes med felterne:

Titel — nøglens navn, obligatorisk felt. Navngiv efter formålet, så det senere er tydeligt, hvad der skal slås fra: ”Eksport til 1C”, ”Rapporter til analyse”.
Udløber kl. — den dato, hvorefter nøglen holder op med at virke. Hvis feltet efterlades tomt, er gyldigheden ubegrænset.
Adgang — nøglens rettighedsomfang:
Full access (act as me) — nøglen arbejder i dit navn og med dine rettigheder.
Begrænsede tilladelser — et begrænset sæt tilladelser, som du selv vælger.

Klik på Tilføj for at oprette nøglen, eller på Annuller for at lukke panelet.

📷 *Skærmbillede af panelet til oprettelse af nøgle — skal tages på prod*

Nøglen oprettes til en bestemt virksomhed og virker kun med dens data. Nøglen kan tilbagekaldes når som helst — tilbagekaldelsen træder i kraft med det samme, og alle efterfølgende forespørgsler med denne nøgle returnerer fejlen 401.

Vigtigt: den oprettede nøgle vises kun én gang. Kopiér den med det samme, og opbevar den et sikkert sted — den kan ikke hentes frem igen. Hvis nøglen mistes, skal du oprette en ny og tilbagekalde den gamle.

Autorisation

Alle forespørgsler til API’et signeres med nøglen i headeren:

Authorization: Bearer {your_API_key}

API’ets basisadresse:

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

En forespørgsel uden en gyldig nøgle returnerer 401 og bodyen {"message":"Unauthenticated."}.

Den første forespørgsel

For eksempel for at få listen over virksomhedens medarbejdere (indsæt dit eget virksomheds-ID i stedet for {companyId}):

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

Det samme via curl:

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

Virksomhedens ID kan ses i applikationens adresselinje: app.shifton.com/c/8397/... — tallet efter /c/.

Hvad der er tilgængeligt via API’et

Opslagsværket dækker mere end 360 metoder. Hovedafsnittene for feltservice:

Opgaver — /companies/{companyId}/tasks: oprettelse, ændring, statusser, opgavefiler.
Huskeliste (To Do) — /companies/{companyId}/todo.
Kunder — /companies/{companyId}/clients samt kundernes adresser og brugerdefinerede felter.
Tjeklister — /companies/{companyId}/checklists.
Serviceområder — /companies/{companyId}/tasks/service-areas.
Færdigheder — /companies/{companyId}/skills.
Medarbejdere — /companies/{companyId}/employees: tilføjelse, redigering, afskedigelse og genindsættelse.
Inventar — genstande, kategorier, sæt og lagerbeholdninger.
Fakturering — overslag, arbejdsordrer, fakturaer, kvitteringer, dokumenttællere og logo.
Rapporter — eksport af data om arbejde og fremmøde.

Derudover er skemaer og vagter, ferier og anmodninger om fri, fremmøde, billing og SMS-billing, notifikationer og moduler tilgængelige.

Webhooks

Hvis du i stedet for regelmæssige forespørgsler til API’et har brug for at modtage hændelser i det øjeblik, de opstår, skal du bruge webhooks — fanen Webhooks i afsnittet Developer. Shifton sender selv en forespørgsel til din adresse, når den ønskede hændelse indtræffer; listen over understøttede hændelser returneres af en særskilt metode.

Fejlkoder

Shiftons API bruger standard HTTP-statuskoder:

200 — forespørgslen blev udført.
201 — objektet blev oprettet.
400 — forkerte forespørgselsparametre.
401 — autorisationsfejl: nøglen blev ikke sendt, er ugyldig eller er tilbagekaldt.
403 — adgang nægtet.
404 — ressourcen blev ikke fundet (oftest en tastefejl i metodens adresse).
500 — serverfejl.

Tips til brugen

Brug den nye dokumentation til nye integrationer — den gamle er bevaret til integrationer, der allerede kører.
Postman eller curl er praktiske til at afprøve forespørgsler — de gør det muligt at se svaret uden at skrive en eneste linje kode.
Opbevar ikke nøglen i klartekst i koden, og videregiv den ikke til tredjepart: nøglen giver adgang til virksomhedens data.
Overhold begrænsningerne for forespørgselsfrekvens (rate limits) — overskridelse kan føre til en midlertidig blokering af adgangen til API’et.

FAQ

Spørgsmål: Hvor får jeg en API-nøgle? Svar: I applikationen: afsnittet Developer → fanen API-nøgler → knappen ”Opret API-nøgle”. Nøglen udstedes til den aktuelle virksomhed.

Spørgsmål: Jeg lukkede vinduet og kopierede ikke nøglen. Hvor ser jeg den? Svar: Ingen steder — nøglen vises kun én gang og udstedes ikke igen. Opret en ny nøgle, og tilbagekald den gamle.

Spørgsmål: Hvordan tilbagekalder jeg en kompromitteret nøgle? Svar: Slet den på fanen API-nøgler. Tilbagekaldelsen træder i kraft med det samme: alle forespørgsler med denne nøgle begynder straks at returnere 401.

Spørgsmål: Hvad er forskellen på ”Full access” og ”Restricted permissions”? Svar: Full access (act as me) giver nøglen de samme rettigheder, som du har. Begrænsede tilladelser gør det muligt kun at give nøglen et udvalgt sæt tilladelser — det er sikrere for en integration, der kun har brug for adgang til en del af dataene.

Spørgsmål: Kan nøglens gyldighed begrænses? Svar: Ja, med feltet Udløber kl. ved oprettelsen. Hvis det ikke udfyldes, er nøglen tidsubegrænset.

Spørgsmål: Virker én nøgle til flere virksomheder? Svar: Nej. Nøglen er knyttet til den virksomhed, den blev oprettet i, og virker kun med dens data. Opret en særskilt nøgle til en anden virksomhed.

Spørgsmål: Hvad er API’ets basisadresse? Svar: https://api2.shifton.com/work/1.0.0. Derefter følger metodens sti, for eksempel /companies/{companyId}/tasks.

Spørgsmål: Hvor finder jeg virksomhedens ID til forespørgslerne? Svar: Det står i applikationens adresselinje lige efter /c/ — i app.shifton.com/c/8397/tasks er virksomhedens identifikator for eksempel 8397.

Spørgsmål: Hvilken version af dokumentationen skal jeg bruge? Svar: Til nye integrationer — den nye (api2.shifton.com/openapi). Den gamle (api2.shifton.com/docs) understøttes til eksisterende integrationer.

Spørgsmål: Findes dokumentationen på russisk? Svar: Ja. Øverst til højre på siden med den nye dokumentation er der en omskifter, EN / RU.

Spørgsmål: Hvad tester jeg API-forespørgsler med? Svar: Nemmest er Postman eller curl — de gør det muligt at sende forespørgsler og se svar uden at skrive kode.

Spørgsmål: Hvorfor får jeg 401, selv om jeg har kopieret nøglen? Svar: Kontrollér, at nøglen sendes i headeren Authorization med ordet Bearer foran, at nøglen ikke er tilbagekaldt, og at dens gyldighed ikke er udløbet.

Spørgsmål: Hvorfor får jeg 404? Svar: Oftest er adressen forkert: basisdelen skal være https://api2.shifton.com/work/1.0.0, og metodens sti skal indeholde det rigtige {companyId}.

Spørgsmål: Hvad kan automatiseres via API’et? Svar: Oprettelse og ændring af opgaver, arbejde med kunder og deres adresser, tjeklister, serviceområder, færdigheder, medarbejdere, inventar, dokumenter i Fakturering og eksport af rapporter samt skemaer, vagter og ferier.

Spørgsmål: Kan man modtage hændelser fra Shifton i stedet for at spørge API’et? Svar: Ja, til det er der webhooks — fanen Webhooks i afsnittet Developer.

Spørgsmål: Påvirker et skift af adgangskode integrationens drift? Svar: Nej. Integrationer arbejder via API-nøglen og ikke via kontoens adgangskode.