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
- Log in als eigenaar of beheerder en ga naar Instellingen → Integraties.
- Maak een API-sleutel en geef hem een naam, bijvoorbeeld “Power BI”. Kopieer de sleutel meteen: je ziet hem maar één keer.
- Doe je eerste verzoek:
curl https://shiftgo.nl/api/v1/locations \
-H "Authorization: Bearer sgk_jouw_sleutel"[
{
"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
fromento.totelt 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
429met"code": "RATE_LIMITED". Wacht dan het aantal seconden uit de headerRetry-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.
[
{
"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
nullals het niet is ingevuld. - contractTypestring
FIXED_HOURS(vaste uren),ZERO_HOURS(nul-uren),MIN_MAX(min-max) ofFREELANCE.- 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.
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"[
{
"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
nullbij een open dienst.- positionIdstring · null
- De functie, of
nullals 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.
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"[
{
"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
nullals 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) ofCORRECTED(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.
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 }
]
}'{ "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.
{
"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 uitRetry-Afteren 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:
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_PINofNFC),atenflags: signalen voor de manager, zoalsLATEofOUTSIDE_GEOFENCE.- clock.outUitgeklokt
- Dezelfde velden als bij
clock.in. - shift.publishedRooster gepubliceerd
locationId,weekStart(de maandag,JJJJ-MM-DD) enshifts: het aantal gepubliceerde diensten. Haal de diensten daarna op met /v1/shifts.- leave.approvedVerlof goedgekeurd
employeeId,leaveType(de naam, zoals “Vakantie”),startDate,endDateenminutes: 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
createdAtals 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 overtijdstempel + "." + body. Het tijdstempel staat ook inX-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.
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
$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.
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.