API-dokumentasjon

Shifton Oppgaver lar deg automatisere arbeidet med plattformen og koble den til eksterne tjenester gjennom et åpent API. Gjennom API-et er alle sentrale enheter tilgjengelige — oppgaver, klienter, ansatte, sjekklister, inventar, tjenesteområder, dokumentene i Finansielle dokumenter og rapporter — derfor kan Shifton kobles sammen med systemene dine for HR, lønnsberegning og analyse, og også med selskapets interne tjenester.

Dokumentasjonen er publisert i to versjoner:

🚀 Ny dokumentasjon — den aktuelle versjonen av oppslagsverket med oppdatert struktur og de nyeste metodene: 👉 https://api2.shifton.com/openapi/
📄 Gammel dokumentasjon — den forrige versjonen (støttes fortsatt for integrasjoner som finnes fra før): 👉 https://api2.shifton.com/docs/

Begge versjonene kan åpnes direkte fra applikasjonen — i delen Developer, på fanen Oversikt, med knappene «Ny dokumentasjon» og «Gammel dokumentasjon».

Dokumentasjonen finnes på to språk. Øverst til høyre på siden med den nye dokumentasjonen er det en veksler, EN / RU — språket du velger, blir husket.

Slik får du en API-nøkkel

API-nøkkelen opprettes i selve applikasjonen:

Åpne delen Developer.
Gå til fanen API-nøkler («API-nøkler»).
Klikk på «Opprett API-nøkkel».

Hva du skal fylle ut når du oppretter en nøkkel

Sidepanelet Opprett API-nøkkel åpnes med feltene:

Tittel — navnet på nøkkelen, obligatorisk felt. Gi den navn etter formålet, slik at det senere er tydelig hva som skal slås av: «Eksport til 1C», «Rapporter til analyse».
Utløper kl. — datoen nøkkelen slutter å virke etter. Hvis du lar feltet stå tomt, er gyldigheten ubegrenset.
Tilgang — omfanget av nøkkelens rettigheter:
Full access (act as me) — nøkkelen arbeider i ditt navn og med dine rettigheter.
Begrensede tillatelser — et begrenset sett tillatelser som du velger selv.

Klikk på Legg til for å opprette nøkkelen, eller på Avbryt for å lukke panelet.

📷 *Skjermbilde av panelet for oppretting av nøkkel — skal tas på prod*

Nøkkelen opprettes for et bestemt selskap og virker bare med dette selskapets data. Nøkkelen kan trekkes tilbake når som helst — tilbaketrekkingen får virkning umiddelbart, og alle senere forespørsler med denne nøkkelen returnerer feilen 401.

Viktig: nøkkelen som opprettes, vises bare én gang. Kopier den med én gang og oppbevar den på et trygt sted — den kan ikke hentes fram igjen. Hvis nøkkelen blir mistet, oppretter du en ny og trekker den gamle tilbake.

Autorisasjon

Alle forespørsler til API-et signeres med nøkkelen i headeren:

Authorization: Bearer {your_API_key}

Basisadressen til API-et:

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

En forespørsel uten en gyldig nøkkel returnerer 401 og kroppen {"message":"Unauthenticated."}.

Den første forespørselen

For eksempel for å få listen over selskapets ansatte (sett inn din egen selskaps-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

Selskapets ID ser du i adresselinjen i applikasjonen: app.shifton.com/c/8397/... — tallet etter /c/.

Hva som er tilgjengelig gjennom API-et

Oppslagsverket dekker mer enn 360 metoder. Hoveddelene for felttjeneste:

Oppgaver — /companies/{companyId}/tasks: oppretting, endring, statuser, oppgavefiler.
Huskeliste (To Do) — /companies/{companyId}/todo.
Klienter — /companies/{companyId}/clients, og også klientenes adresser og egendefinerte felt.
Sjekklister — /companies/{companyId}/checklists.
Tjenesteområder — /companies/{companyId}/tasks/service-areas.
Ferdigheter — /companies/{companyId}/skills.
Ansatte — /companies/{companyId}/employees: legge til, redigere, avslutte arbeidsforhold og gjenopprette.
Inventar — gjenstander, kategorier, sett og beholdning på lagrene.
Finansielle dokumenter — kostnadsoverslag, arbeidsordrer, fakturaer, kvitteringer, dokumenttellere og logo.
Rapporter — eksport av data om arbeid og oppmøte.

I tillegg er tidsplaner og skift, ferier og forespørsler om fri, oppmøte, fakturering og SMS-fakturering, varsler og moduler tilgjengelige.

Webhooks

Hvis du trenger å få hendelser i det øyeblikket de oppstår, i stedet for å sende jevnlige forespørsler til API-et, bruker du webhooks — fanen Webhooks i delen Developer. Shifton sender selv en forespørsel til adressen din når den aktuelle hendelsen inntreffer; listen over støttede hendelser returneres av en egen metode.

Feilkoder

Shiftons API bruker standard HTTP-statuskoder:

200 — forespørselen er utført.
201 — objektet er opprettet.
400 — feil parametere i forespørselen.
401 — autorisasjonsfeil: nøkkelen er ikke sendt, er ugyldig eller er trukket tilbake.
403 — tilgang nektet.
404 — ressursen er ikke funnet (oftest en skrivefeil i adressen til metoden).
500 — serverfeil.

Tips om bruk

For nye integrasjoner bruker du den nye dokumentasjonen — den gamle er beholdt for integrasjoner som alt er i drift.
For å prøve ut forespørsler er Postman eller curl praktisk — der ser du svaret uten å skrive én linje kode.
Ikke lagre nøkkelen i klartekst i koden, og ikke gi den videre til tredjeparter: nøkkelen gir tilgang til selskapets data.
Hold deg innenfor grensene for forespørselsfrekvens (rate limits) — hvis du overskrider dem, kan tilgangen til API-et bli midlertidig blokkert.

Ofte stilte spørsmål

Spørsmål: Hvor får jeg en API-nøkkel? Svar: I applikasjonen: delen Developer → fanen API-nøkler → knappen «Opprett API-nøkkel». Nøkkelen utstedes for det gjeldende selskapet.

Spørsmål: Jeg lukket vinduet og kopierte ikke nøkkelen. Hvor ser jeg den? Svar: Ingen steder — nøkkelen vises bare én gang og utstedes ikke på nytt. Opprett en ny nøkkel og trekk den gamle tilbake.

Spørsmål: Hvordan trekker jeg nøkkelen tilbake hvis den er kommet i gale hender? Svar: Slett den på fanen API-nøkler. Tilbaketrekkingen får virkning umiddelbart: alle forespørsler med denne nøkkelen begynner straks å returnere 401.

Spørsmål: Hva skiller «Full access» fra «Restricted permissions»? Svar: Full access (act as me) gir nøkkelen de samme rettighetene som du har. Begrensede tillatelser gjør det mulig å gi nøkkelen bare et utvalgt sett tillatelser — det er tryggere for en integrasjon som bare trenger tilgang til deler av dataene.

Spørsmål: Kan gyldigheten til nøkkelen begrenses? Svar: Ja, feltet Utløper kl. ved oppretting. Hvis du ikke fyller det ut, er nøkkelen uten tidsbegrensning.

Spørsmål: Virker én nøkkel for flere selskaper? Svar: Nei. Nøkkelen er knyttet til selskapet den er opprettet i, og virker bare med dette selskapets data. For et annet selskap oppretter du en egen nøkkel.

Spørsmål: Hva er basisadressen til API-et? Svar: https://api2.shifton.com/work/1.0.0. Deretter følger banen til metoden, for eksempel /companies/{companyId}/tasks.

Spørsmål: Hvor finner jeg selskaps-ID-en til forespørslene? Svar: Den står i adresselinjen i applikasjonen rett etter /c/ — i app.shifton.com/c/8397/tasks er selskapets identifikator for eksempel 8397.

Spørsmål: Hvilken versjon av dokumentasjonen bør jeg bruke? Svar: For nye integrasjoner — den nye (api2.shifton.com/openapi). Den gamle (api2.shifton.com/docs) støttes for integrasjoner som finnes fra før.

Spørsmål: Finnes dokumentasjonen på russisk? Svar: Ja. På siden med den nye dokumentasjonen er det en veksler øverst til høyre, EN / RU.

Spørsmål: Hva prøver jeg ut forespørsler til API-et med? Svar: Det enkleste er Postman eller curl — der kan du sende forespørsler og se svarene uten å skrive kode.

Spørsmål: Hvorfor får jeg 401 selv om jeg kopierte nøkkelen? Svar: Kontroller at nøkkelen sendes i headeren Authorization med ordet Bearer foran, at nøkkelen ikke er trukket tilbake, og at gyldigheten ikke er utløpt.

Spørsmål: Hvorfor får jeg 404? Svar: Oftest er adressen forvekslet: basisdelen skal være https://api2.shifton.com/work/1.0.0, og i banen til metoden skal {companyId} være riktig.

Spørsmål: Hva kan automatiseres gjennom API-et? Svar: Oppretting og endring av oppgaver, arbeid med klienter og adressene deres, sjekklister, tjenesteområder, ferdigheter, ansatte, inventar, dokumentene i Finansielle dokumenter og eksport av rapporter, og også tidsplaner, skift og ferier.

Spørsmål: Kan jeg få hendelser fra Shifton i stedet for å spørre API-et? Svar: Ja, til det finnes webhooks — fanen Webhooks i delen Developer.

Spørsmål: Påvirker en passordendring driften av integrasjonen? Svar: Nei. Integrasjonene virker med API-nøkkelen, ikke med passordet til kontoen.