Veiledning for REST API-tilgang

Sist verifisert: 11. oktober 2026

1. Dette er inkludert

PRO-arbeidsområder kan generere en API-nøkkel for å kalle ShiftSchedulers innebygde REST-endepunkter direkte. Nøkkelen autentiserer forespørsler til de samme serverrutene som nettappen bruker, slik at du alltid får normaliserte JSON-svar.

Bare administratorer kan administrere integrasjonsnøkler. Organisasjonen må ha minst én betalt lisens for å opprette eller bruke en REST API-nøkkel; en gratis prøveperiode alene er ikke nok. Nøkler har administratorrettigheter i sitt arbeidsområde.

2. Generering av API-nøkkel

  1. Logg inn og åpne Innstillinger → API-tilgang for REST-klienter.
  2. Klikk på Generer ny nøkkel.
  3. Kopier nøkkelen som vises i dialogboksen. Den vises aldri i klartekst igjen.
  4. Oppbevar den sikkert, gjerne i et verktøy for hemmelighetshåndtering. Du kan når som helst tilbakekalle eller generere nøkkelen på nytt fra samme side.

Hvert arbeidsområde kan bare ha én API-nøkkel. Når du genererer en ny, blir den forrige ugyldig umiddelbart.

3. Autentisering

Alle API-forespørsler må inkludere nøkkelen i headeren Authorization med autentiseringsmetoden Bearer :

curl https://shiftscheduler.ai/api/persons \
  -H "Authorization: Bearer <YOUR_API_ACCESS_KEY>"

For forespørsler mellom servere, send Bearer-nøkkelen uten nettleserens øktinformasjonskapsler. En gyldig økt har forrang og bruker sine egne tillatelser. JSON-innhold krever Content-Type: application/json; forespørsler uten innhold trenger ikke dette.

Autentiseringsfeil gir 401. En gyldig nøkkel uten betalt tilgang gir 403. Tillatelser og lisensgrenser kan også gi 403; konflikter gir 409 og ugyldige data vanligvis 400. Feilsvar inneholder en error-streng. Betalt lisens omgår ikke organisasjonens persongrenser.

  • Nøkkelen inneholder arbeidsområdets ID, slik at hver forespørsel automatisk avgrenses til arbeidsområdet ditt.
  • API-nøkler gir tilgang til hele arbeidsområdet og er bare beregnet på kommunikasjon mellom servere. Ikke eksponer nøkkelen i nettleser- eller mobilappkode.
  • Det er foreløpig ingen frekvensgrense per nøkkel. Innfør derfor passende begrensninger i integrasjonen din.

Hente arbeidssteder

Bruk REST API-nøkkelen, ikke en MCP-nøkkel eller webhook-hemmelighet. Svaret er et JSON-objekt der egenskapen locations inneholder listen over arbeidssteder. Svaret er ikke en frittstående liste.

curl https://shiftscheduler.ai/api/locations \
  -H "Authorization: Bearer <YOUR_API_ACCESS_KEY>" \
  -H "Accept: application/json"
{
  "locations": [
    {
      "id": "66f01234567890abcdef1234",
      "title": "Ward A",
      "sortOrder": 1,
      "weeklyTemplate": []
    }
  ]
}

Ved henting av samlinger brukes tilsvarende omslag: persons, locations eller shifts. En manglende, ugyldig, tilbakekalt eller erstattet nøkkel gir 401 med en JSON-feilmelding i error .

4. Støttede endepunkter

Følgende endepunkter støtter Bearer-autentisering. Datafeltene bruker camelCase , og svarene følger alltid ShiftSchedulers normaliserte format.

| Metode | Endepunkt | Merknader |
| --- | --- | --- |
| GET, POST | `/api/persons` | List opp eller opprett personer. |
| GET, PUT, DELETE | `/api/persons/{id}` | Les, oppdater delvis eller slett en person og tilhørende oppføringer. |
| POST | `/api/persons/reorder` | Endre rekkefølgen med orderedIds; utilgjengelig ved alfabetisk sortering. |
| POST | `/api/persons/{id}/access` | Administrer tilgang med action: invite, cancel-invite eller revoke. Invitasjoner sender e-post. |
| GET, POST | `/api/locations` | List opp eller opprett lokasjoner. |
| GET, PUT, DELETE | `/api/locations/{id}` | Les, oppdater eller slett en lokasjon og dens vakter. |
| POST | `/api/locations/reorder` | Endre rekkefølgen med orderedIds; utilgjengelig ved alfabetisk sortering. |
| GET, POST | `/api/shift-templates` | List opp eller opprett maler for arbeidsområdet. |
| GET, PUT, DELETE | `/api/shift-templates/{id}` | Les, oppdater eller slett en mal; referanser kan hindre sletting (409). |
| POST | `/api/shift-templates/{id}` | Forhåndsvis virkningen av en malendring uten å lagre. |
| GET, PUT, DELETE | `/api/location-day-schedules` | GET: locationIds/locationId, from, to. PUT: locationId, date, slots. DELETE: parametrene locationId og date. |
| GET, POST, DELETE | `/api/shifts` | GET: locationId, personId, date, from, to. POST: opprett. DELETE: JSON-innhold med id. |
| PUT | `/api/shifts/{id}` | Oppdater en vakt delvis. |
| GET, DELETE | `/api/schedule-draft` | Les det delte utkastet; includeChanges=true legger til trygge endringsbeskrivelser. DELETE forkaster hele utkastet. |
| POST | `/api/schedule-draft/publish` | Publiser alle ventende endringer atomisk. |
| GET, PUT | `/api/person-preferences` | GET: personIds/personId, from, to. PUT: personId, date, preference; en tom verdi fjerner preferansen. |
| GET, POST | `/api/timeoff/requests` | GET: status (requested som standard; archived inkluderer approved/rejected). POST: personId, date, typeId; tidene hentes fra malen. |
| PUT | `/api/timeoff/requests/{id}` | Oppdater merknad/dato eller action: approve/reject. Mal og tider kan ikke endres. |
| GET | `/api/timeoff/allowances` | Les synlige fraværssaldoer. |
| GET, POST | `/api/timeoff/grants` | GET krever personId. POST: personId, typeId, hours, valgfri note. |
| DELETE | `/api/timeoff/grants/{id}` | Annuller en tildeling; revisjonsoppføringen beholdes til personen slettes. |
| GET | `/api/overview` | Oversikt med valgfrie datoer start/end. |
| GET, PUT | `/api/workspace/ai-settings` | Les KI-regler; PUT erstatter rules eller utfører den støttede regelhandlingen. |
| PATCH | `/api/workspace/rules/reset-interpretation` | Tilbakestill regeltolkningen med ruleId. |

Svarfeltene varierer: persons, locations, shifts, schedules, preferences (med quotas), data (maler og fraværsforespørsler), grants (med summary) eller allowances. De er ikke rene lister. Svar på skriveoperasjoner varierer også etter endepunkt.

Bare POST /api/shifts, DELETE /api/shifts, PUT /api/location-day-schedules, PUT /api/person-preferences og POST /api/timeoff/requests støtter en { items: [...] }.

Samleresultater beholder rekkefølgen og inneholder successCount, failureCount, mutationCount og results. En akseptert samling gir HTTP 200 selv om noen eller alle elementene feiler. Kontroller ok og status for hvert resultat; HTTP 200 alene betyr ikke at alt lyktes.

Svar for fravær inneholder createdAt, dagens søknadsrekkefølge orderog referanser til godkjenning eller avslag. Køen omfatter ventende, godkjente og avslåtte søknader for samme kalenderdag.

Hvis utkast til vaktplan er aktivert, leser API-et vakter fra den felles arbeidsversjonen og skriver vanlige vakter til den. Medlemmer varsles ikke, og vakt-webhooks sendes ikke før utkastet publiseres. Publisering gjennomfører alle ventende endringer samlet. Sletting forkaster hele utkastet. Fraværsoperasjoner utføres fortsatt umiddelbart. API-nøkler har samme rett til å publisere og forkaste som administratorer.

For å se gjennom det felles utkastet uten å eksponere rå vaktdata, kall GET /api/schedule-draft?includeChanges=true. Det valgfrie feltet changes inneholder operasjonstype, dokument-ID, etikett og parametere for lokaliserte historikkbeskrivelser for hver upublisert vaktendring, sortert etter vaktdato.

Filtrere vakter

GET /api/shifts godtar de valgfrie spørringsparameterne locationId, personId, from og to for å avgrense listen. Oppgi én dato for å hente alt fra og med eller til og med den dagen, eller begge datoene for å avgrense perioden. Uten filtre får du alle vaktene i arbeidsområdet.

5. Opprette data

Skriveendepunktene godtar de samme dataformatene som nettappen bruker internt. Eksemplene nedenfor viser hvordan du oppretter hver type oppføring med vanlige felter.

Endringer i personer, lokasjoner eller maler ugyldiggjør KI-regeltolkninger. Sletting av personer eller lokasjoner fjerner tilhørende plandata. Malendringer kan kreve valg for videreføring; forhåndsvis virkningen først. Bruk et testarbeidsområde for å prøve skriveoperasjoner.

Opprette en medarbeider

curl -X POST https://shiftscheduler.ai/api/persons \
  -H "Authorization: Bearer <YOUR_API_ACCESS_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
        "name": "Jordan Weaver",
        "invited": false
      }'

Angi invited=true for å sende en e-postinvitasjon. Serveren validerer og normaliserer membership -data før lagring.

For å legge til noen uten å invitere dem ennå, utelat invited (eller sett den til false) og utelat membership -blokken. Medarbeideren opprettes uten tilgang til arbeidsområdet.

Medlemskapsinnstillinger krever invited=true og en gyldig email. Det valgfrie feltet membership.role kan være admin, manager eller member; standardverdien er member. Medlemskapsinnstillinger uten forespørsel om invitasjon gir en valideringsfeil.

Svaret inneholder de normaliserte medlemskapsopplysningene (status, invitasjonsadresse og tidsstempler), slik at du kan kontrollere hva som ble lagret.

Opprette et arbeidssted

curl -X POST https://shiftscheduler.ai/api/locations \
  -H "Authorization: Bearer <YOUR_API_ACCESS_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
        "title": "Ward A",
        "weeklyTemplate": []
      }'

Opprette en vakt

curl -X POST https://shiftscheduler.ai/api/shifts \
  -H "Authorization: Bearer <YOUR_API_ACCESS_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
        "location": "LOCATION_ID",
        "person": "PERSON_ID",
        "date": "2026-10-20",
        "startTime": "09:00",
        "endTime": "17:00",
        "note": "Internal workshop prep and handoff"
      }'