REST API for vaktplanlegging | ShiftScheduler.ai

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.

2. Generering av API-nøkkel

Logg inn og åpne Innstillinger → API-tilgang for REST-klienter.
Klikk på Generer ny nøkkel.
Kopier nøkkelen som vises i dialogboksen. Den vises aldri i klartekst igjen.
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>"

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 | Beskrivelse |
| ------ | -------- | ----- |
| GET | `/api/persons` | Hent alle medarbeiderne i arbeidsområdet. |
| POST | `/api/persons` | Opprett en medarbeider. |
| PUT | `/api/persons/{id}` | Oppdater en medarbeider (delvise oppdateringer støttes). |
| DELETE | `/api/persons/{id}` | Slett en medarbeider og vedkommendes vakter. |
| GET | `/api/locations` | Hent alle arbeidsstedene. |
| POST | `/api/locations` | Opprett et arbeidssted. |
| PUT | `/api/locations/{id}` | Oppdater et arbeidssted. |
| DELETE | `/api/locations/{id}` | Slett et arbeidssted og vaktene som hører til. |
| PUT | `/api/location-day-schedules` | Oppdater planen for ett arbeidssted, eller flere med en `items`-liste. |
| GET | `/api/shifts` | Valgfrie filtre: `locationId`, `personId`, `from`, `to`. |
| POST | `/api/shifts` | Opprett én vakt, eller flere med en `items`-liste. |
| PUT | `/api/shifts/{id}` | Oppdater datoperiode, klokkeslett, merknad eller tilknytninger. |
| DELETE | `/api/shifts` | Slett ett planelement med `{ id }`, eller flere med `{ items: [{ id }] }`. |
| GET | `/api/schedule-draft` | Hent antall endringer i det felles utkastet og tilhørende tilganger. Legg til `?includeChanges=true` for trygge endringsbeskrivelser i samme format som historikken. |
| POST | `/api/schedule-draft/publish` | Publiser alle ventende planendringer samlet i én atomisk operasjon. |
| DELETE | `/api/schedule-draft` | Forkast alle ventende planendringer. |
| PUT | `/api/person-preferences` | Angi eller fjern én preferanse, eller flere med en `items`-liste. |
| POST | `/api/timeoff/requests` | Opprett én fraværssøknad, eller flere med en `items`-liste. Malen bestemmer klokkeslett og pause. |
| PUT | `/api/timeoff/requests/{id}` | Oppdater merknaden, flytt søknaden eller godkjenn/avslå en ventende søknad. Mal og klokkeslett kan ikke endres. |

Skriveendepunkter for samlinger godtar enten det eksisterende formatet for én oppføring eller et eksplisitt { items: [...] } -omslag. Svar på gruppeoperasjoner beholder inndatarekkefølgen og oppgir antall vellykkede, mislykkede og utførte endringer. Godtatte grupper returnerer HTTP 200 selv om en enkelt oppføring mislykkes.

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.

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",
        "email": "jordan.weaver@example.com",
        "invited": true,
        "membership": {
          "role": "member"
        }
      }'

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": "2025-10-20",
        "startTime": "09:00",
        "endTime": "17:00",
        "note": "Internal workshop prep and handoff"
      }'

Veiledning for REST API-tilgang