ShiftGo

Voor ontwikkelaars

ShiftGo API

Haal roosters, medewerkers en goedgekeurde uren op in je eigen systemen, zoals een loonpakket of BI-dashboard. Stuur de omzet uit je kassa naar ShiftGo en krijg live meldingen met webhooks.

De API en webhooks zitten in ShiftGo Enterprise.

Adres
https://shiftgo.nl/api/v1
Formaat
JSON (UTF-8)
Sleutel
Authorization: Bearer sgk_…
Limiet
300 verzoeken per minuut per sleutel

Snel aan de slag

  1. Log in als eigenaar of beheerder en ga naar Instellingen → Integraties.
  2. Maak een API-sleutel en geef hem een naam, bijvoorbeeld “Power BI”. Kopieer de sleutel meteen: je ziet hem maar één keer.
  3. Doe je eerste verzoek:
Terminal
curl https://shiftgo.nl/api/v1/locations \
  -H "Authorization: Bearer sgk_jouw_sleutel"
Antwoord · 200
[
  {
    "id": "cm3f9x2k10004l708h2r1d6qa",
    "name": "Centrum",
    "address": "Stationsplein 12",
    "city": "Lelystad",
    "timezone": "Europe/Amsterdam"
  }
]

Authenticatie

Stuur bij elk verzoek je sleutel mee in de header Authorization: Bearer sgk_…. Een sleutel geeft toegang tot de gegevens van je hele organisatie, van alle vestigingen.

  • Gebruik de sleutel alleen op een server. Zet hem nooit in een website of app: iedereen die de code kan bekijken, kan hem dan gebruiken.
  • Is een sleutel uitgelekt? Trek hem in bij Integraties. Hij werkt dan direct niet meer. Maak daarna een nieuwe.
  • De sleutels werken zolang je Enterprise hebt. Daarna krijg je een foutmelding (403).

Tijden, periodes en limieten

  • Tijden in antwoorden staan in UTC, in ISO 8601: 2026-11-02T07:00:00.000Z. Dat is 08:00 uur in Nederland. De tijdzone van een vestiging staat bij Vestigingen.
  • Diensten en uren vraag je op per periode, met from en to. to telt niet mee, en een periode is hoogstens 31 dagen.
  • Een datum zonder tijd, zoals 2026-11-02, is middernacht UTC. Wil je Nederlandse dagen, geef dan de tijd mee met de tijdzone: 2026-11-02T00:00:00+01:00. Zet de + in een URL om naar %2B, of laat dat doen zoals in de voorbeelden hieronder.
  • Bedragen zijn in centen: € 1.234,50 is 123450.
  • Een lijst komt in één keer terug, zonder pagina's.
  • Je kunt per sleutel 300 verzoeken per minuut doen, en ook 300 per minuut vanaf één IP-adres. Daarboven krijg je 429 met "code": "RATE_LIMITED". Wacht dan het aantal seconden uit de header Retry-After, of anders een minuut.

Vestigingen

GET/v1/locations

Alle vestigingen die niet gearchiveerd zijn.

idstring
Vaste code van de vestiging. Die gebruik je bij diensten, uren en omzet.
namestring
Naam, zoals je hem in ShiftGo ziet.
addressstring
Straat en huisnummer. Leeg als het niet is ingevuld.
citystring
Plaats. Leeg als het niet is ingevuld.
timezonestring
Tijdzone, bijvoorbeeld Europe/Amsterdam.

Medewerkers

GET/v1/employees

Alle actieve medewerkers. Medewerkers die uit dienst zijn, komen niet mee.

Antwoord · 200
[
  {
    "id": "cm3f9x2k10009l708q4w8n1zt",
    "name": "Anna de Vries",
    "employeeNumber": "1042",
    "contractType": "FIXED_HOURS",
    "contractHoursPerWeek": 24,
    "locations": [{ "locationId": "cm3f9x2k10004l708h2r1d6qa" }]
  }
]
idstring
Vaste code van de medewerker.
namestring
Naam.
employeeNumberstring · null
Personeelsnummer, of null als het niet is ingevuld.
contractTypestring
FIXED_HOURS (vaste uren), ZERO_HOURS (nul-uren), MIN_MAX (min-max) of FREELANCE.
contractHoursPerWeeknumber
Contracturen per week.
locationsarray
De vestigingen waar de medewerker werkt.

Diensten

GET/v1/shifts

Gepubliceerde diensten die beginnen in de periode, op volgorde van begintijd. Concepten en geannuleerde diensten komen niet mee. Open diensten wel: die hebben geen medewerker.

fromdatum-tijd · verplicht
Begin van de periode.
todatum-tijd · verplicht
Einde van de periode (telt niet mee). Hoogstens 31 dagen na from.
Terminal
curl -G https://shiftgo.nl/api/v1/shifts \
  -H "Authorization: Bearer sgk_jouw_sleutel" \
  --data-urlencode "from=2026-11-02T00:00:00+01:00" \
  --data-urlencode "to=2026-11-09T00:00:00+01:00"
Antwoord · 200
[
  {
    "id": "cm3fa1b7c0012l708x9k2m4pe",
    "locationId": "cm3f9x2k10004l708h2r1d6qa",
    "employeeId": "cm3f9x2k10009l708q4w8n1zt",
    "positionId": "cm3f9x2k10006l708c7v3b5hy",
    "start": "2026-11-02T07:00:00.000Z",
    "end": "2026-11-02T15:30:00.000Z",
    "breakMinutes": 30
  }
]
employeeIdstring · null
null bij een open dienst.
positionIdstring · null
De functie, of null als de dienst geen functie heeft.
start, enddatum-tijd
Begin en einde. Heeft een dienst geen vaste eindtijd, dan is end het verwachte einde.
breakMinutesnumber
Geplande pauze in minuten.

Gewerkte uren

GET/v1/time-entries

Goedgekeurde uren die beginnen in de periode, op volgorde van begintijd. Uren die nog wachten op goedkeuring of zijn afgekeurd, komen niet mee. Dezelfde from en to als bij diensten.

Terminal
curl -G https://shiftgo.nl/api/v1/time-entries \
  -H "Authorization: Bearer sgk_jouw_sleutel" \
  --data-urlencode "from=2026-11-01T00:00:00+01:00" \
  --data-urlencode "to=2026-12-01T00:00:00+01:00"
Antwoord · 200
[
  {
    "id": "cm3fb4d2e0020l708r6t1y8ua",
    "employeeId": "cm3f9x2k10009l708q4w8n1zt",
    "locationId": "cm3f9x2k10004l708h2r1d6qa",
    "shiftId": "cm3fa1b7c0012l708x9k2m4pe",
    "start": "2026-11-02T06:58:00.000Z",
    "end": "2026-11-02T15:34:00.000Z",
    "breakMinutes": 30,
    "netMinutes": 486,
    "status": "APPROVED"
  }
]
shiftIdstring · null
De geplande dienst, of null als iemand zonder dienst heeft geklokt.
locationIdstring · null
De vestiging waar is geklokt.
breakMinutesnumber
Pauze in minuten.
netMinutesnumber
Gewerkte minuten zonder pauze. Dit zijn de uren voor de loonadministratie.
statusstring
APPROVED (goedgekeurd) of CORRECTED (aangepast door een manager).

Omzet insturen

POST/v1/revenue

Stuur de omzet per dag vanuit je kassa of boekhouding. Je ziet hem in ShiftGo bij Inzicht, naast de loonkosten. Stuur je een dag opnieuw, dan vervangt het nieuwe bedrag het oude. Zo kun je een dag gerust nog eens sturen.

Terminal
curl https://shiftgo.nl/api/v1/revenue \
  -H "Authorization: Bearer sgk_jouw_sleutel" \
  -H "Content-Type: application/json" \
  -d '{
    "locationId": "cm3f9x2k10004l708h2r1d6qa",
    "days": [
      { "date": "2026-11-01", "amountCents": 284750 },
      { "date": "2026-11-02", "amountCents": 193020 }
    ]
  }'
Antwoord · 200
{ "saved": 2 }
locationIdstring · verplicht
De vestiging.
daysarray · verplicht
1 tot 400 dagen per verzoek.
days[].datestring · verplicht
De dag als JJJJ-MM-DD.
days[].amountCentsnumber · verplicht
De omzet van die dag in centen, als heel getal van 0 of meer.

Foutmeldingen

Gaat er iets mis, dan krijg je een statuscode en JSON met een message in het Nederlands. Bij ongeldige invoer staat in issues welk veld niet klopt.

Antwoord · 400
{
  "message": "Ongeldige invoer",
  "issues": [{ "path": "days.0.date", "message": "Datum als JJJJ-MM-DD" }]
}
400Ongeldige invoer
Een veld klopt niet, de periode is langer dan 31 dagen of de vestiging bestaat niet.
401Geen toegang
De sleutel ontbreekt, is onjuist of is ingetrokken.
403Niet in je pakket of geblokkeerd
Je organisatie heeft geen Enterprise (meer), of je account bij ShiftGo is geblokkeerd ("code": "ORG_SUSPENDED").
429Te veel verzoeken
Meer dan 300 verzoeken in een minuut met deze sleutel of vanaf dit IP-adres ("code": "RATE_LIMITED"). Wacht de seconden uit Retry-After en probeer het opnieuw.
500Storing
Er ging bij ons iets mis. Probeer het later opnieuw.

Webhooks

Met een webhook stuurt ShiftGo een bericht naar jouw systeem zodra er iets gebeurt, bijvoorbeeld als iemand inklokt. Je stelt webhooks in bij Instellingen → Integraties: vul een https-adres in en kies de gebeurtenissen. Met de knop Test stuur je een ping.

ShiftGo stuurt een POST met JSON naar je adres:

Verzoek van ShiftGo
POST /shiftgo HTTP/1.1
Content-Type: application/json
User-Agent: ShiftGo-Webhooks/1.0
X-ShiftGo-Event: clock.in
X-ShiftGo-Signature: sha256=5d41402abc4b2a76b9719d911017c592...
X-ShiftGo-Timestamp: 1793602692
X-ShiftGo-Signature-V2: t=1793602692,v1=9f86d081884c7d659a2feaa0c55ad015...

{
  "event": "clock.in",
  "createdAt": "2026-11-02T06:58:12.402Z",
  "data": {
    "employeeId": "cm3f9x2k10009l708q4w8n1zt",
    "locationId": "cm3f9x2k10004l708h2r1d6qa",
    "method": "APP_GPS",
    "at": "2026-11-02T06:58:12.390Z",
    "flags": []
  }
}

Gebeurtenissen

clock.inIngeklokt
employeeId, locationId, method (APP_GPS, QR, KIOSK_PIN of NFC), at en flags: signalen voor de manager, zoals LATE of OUTSIDE_GEOFENCE.
clock.outUitgeklokt
Dezelfde velden als bij clock.in.
shift.publishedRooster gepubliceerd
locationId, weekStart (de maandag, JJJJ-MM-DD) en shifts: het aantal gepubliceerde diensten. Haal de diensten daarna op met /v1/shifts.
leave.approvedVerlof goedgekeurd
employeeId, leaveType (de naam, zoals “Vakantie”), startDate, endDate en minutes: het aantal verlofminuten.
timesheet.approvedUren goedgekeurd
ids: de goedgekeurde uren. Haal ze op met /v1/time-entries.

Zo bezorgen we

  • Antwoord binnen 5 seconden met een statuscode in de 200's. Doe het echte werk daarna, bijvoorbeeld in een wachtrij.
  • We sturen een bericht één keer. Lukt het niet, dan proberen we het niet opnieuw. Bij Integraties zie je het antwoord op de laatste poging.
  • Mis je liever niets? Haal dan ook regelmatig de gegevens op met de API, bijvoorbeeld elke nacht de goedgekeurde uren van de afgelopen week.
  • Berichten kunnen in een andere volgorde aankomen dan ze zijn gebeurd. Gebruik het veld createdAt als de volgorde belangrijk is.
  • We volgen geen doorverwijzingen (redirects) en sturen alleen naar openbare https-adressen.

Handtekening controleren

Elke webhook heeft een eigen geheim dat begint met whsec_. Je ziet het één keer: als je de webhook aanmaakt. Kwijt? Klik bij Integraties op Nieuw geheim; het oude werkt dan meteen niet meer.

ShiftGo ondertekent elk bericht met dat geheim (HMAC-SHA256). Gebruik de body precies zoals hij binnenkomt, vóórdat je de JSON leest. Er zijn twee handtekeningen:

  • X-ShiftGo-Signature-V2 (aanbevolen): t=<tijdstempel>,v1=<hmac>. De hmac is berekend over tijdstempel + "." + body. Het tijdstempel staat ook in X-ShiftGo-Timestamp, in seconden sinds 1970 (UTC). Weiger berichten die ouder zijn dan 5 minuten: zo kan niemand een oud bericht opnieuw afspelen.
  • X-ShiftGo-Signature (v1): sha256=<hmac> over alleen de body. Blijft werken voor bestaande koppelingen, maar zonder bescherming tegen opnieuw afspelen.
Node.js (Express)
import crypto from 'node:crypto';
import express from 'express';

const app = express();
const secret = process.env.SHIFTGO_WEBHOOK_SECRET; // whsec_…

app.post('/shiftgo', express.raw({ type: 'application/json' }), (req, res) => {
  // X-ShiftGo-Signature-V2: t=<timestamp>,v1=<hmac of timestamp + "." + body>
  const parts = Object.fromEntries((req.get('X-ShiftGo-Signature-V2') ?? '').split(',').map((p) => p.split('=')));
  const t = Number(parts.t);
  if (!t || Math.abs(Date.now() / 1000 - t) > 300) return res.sendStatus(401); // older than 5 minutes
  const expected = crypto.createHmac('sha256', secret).update(t + '.').update(req.body).digest('hex');
  const received = parts.v1 ?? '';
  const ok = received.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));
  if (!ok) return res.sendStatus(401);

  const { event, data } = JSON.parse(req.body.toString('utf8'));
  res.sendStatus(204); // eerst antwoorden, dan verwerken
  // … verwerk event en data
});
PHP
<?php
$secret = getenv('SHIFTGO_WEBHOOK_SECRET'); // whsec_…
$body = file_get_contents('php://input');
// X-ShiftGo-Signature-V2: t=<timestamp>,v1=<hmac of timestamp + "." + body>
parse_str(str_replace(',', '&', $_SERVER['HTTP_X_SHIFTGO_SIGNATURE_V2'] ?? ''), $parts);
$t = (int) ($parts['t'] ?? 0);
$expected = hash_hmac('sha256', $t . '.' . $body, $secret);
$received = $parts['v1'] ?? '';

if (!$t || abs(time() - $t) > 300 || !hash_equals($expected, $received)) {
    http_response_code(401); // wrong, or older than 5 minutes
    exit;
}

$message = json_decode($body, true);
http_response_code(204);
// … verwerk $message['event'] en $message['data']

OpenAPI

De hele API staat ook in een OpenAPI-bestand (versie 3.1). Importeer het in Postman of Insomnia, of maak er een client mee voor je eigen programmeertaal.

openapi.json downloaden

Hulp nodig bij een koppeling?

Mail naar info@shiftgo.nl. Zet er de naam van je organisatie bij en, als het kan, het verzoek en het antwoord dat je kreeg. Stuur nooit je API-sleutel mee.