{
  "openapi": "3.1.0",
  "info": {
    "title": "ShiftGo API",
    "version": "1.1.0",
    "summary": "Roosters, medewerkers en goedgekeurde uren ophalen en omzet insturen.",
    "description": "Onderdeel van ShiftGo Enterprise. Maak een sleutel bij Instellingen → Integraties en stuur hem mee als `Authorization: Bearer sgk_…`. Tijden staan in UTC (ISO 8601), bedragen in centen. Hoogstens 300 verzoeken per minuut per sleutel en per IP-adres; daarboven 429 met Retry-After. Uitleg en webhooks: https://shiftgo.nl/developers",
    "contact": { "name": "ShiftGo", "email": "info@shiftgo.nl", "url": "https://shiftgo.nl/developers" }
  },
  "servers": [{ "url": "https://shiftgo.nl/api" }],
  "security": [{ "apiKey": [] }],
  "tags": [
    { "name": "Organisatie", "description": "Vestigingen en medewerkers" },
    { "name": "Rooster en uren", "description": "Gepubliceerde diensten en goedgekeurde uren" },
    { "name": "Omzet", "description": "Omzet uit je kassa of boekhouding" }
  ],
  "paths": {
    "/v1/locations": {
      "get": {
        "tags": ["Organisatie"],
        "operationId": "listLocations",
        "summary": "Vestigingen",
        "description": "Alle vestigingen die niet gearchiveerd zijn.",
        "responses": {
          "200": {
            "description": "Vestigingen",
            "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Location" } } } }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "429": { "$ref": "#/components/responses/TooManyRequests" }
        }
      }
    },
    "/v1/employees": {
      "get": {
        "tags": ["Organisatie"],
        "operationId": "listEmployees",
        "summary": "Medewerkers",
        "description": "Alle actieve medewerkers.",
        "responses": {
          "200": {
            "description": "Medewerkers",
            "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Employee" } } } }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "429": { "$ref": "#/components/responses/TooManyRequests" }
        }
      }
    },
    "/v1/shifts": {
      "get": {
        "tags": ["Rooster en uren"],
        "operationId": "listShifts",
        "summary": "Diensten",
        "description": "Gepubliceerde diensten die beginnen in de periode, op volgorde van begintijd. Open diensten hebben `employeeId: null`.",
        "parameters": [{ "$ref": "#/components/parameters/From" }, { "$ref": "#/components/parameters/To" }],
        "responses": {
          "200": {
            "description": "Diensten",
            "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Shift" } } } }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "429": { "$ref": "#/components/responses/TooManyRequests" }
        }
      }
    },
    "/v1/time-entries": {
      "get": {
        "tags": ["Rooster en uren"],
        "operationId": "listTimeEntries",
        "summary": "Gewerkte uren",
        "description": "Goedgekeurde (of door een manager aangepaste) uren die beginnen in de periode, op volgorde van begintijd.",
        "parameters": [{ "$ref": "#/components/parameters/From" }, { "$ref": "#/components/parameters/To" }],
        "responses": {
          "200": {
            "description": "Gewerkte uren",
            "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TimeEntry" } } } }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "429": { "$ref": "#/components/responses/TooManyRequests" }
        }
      }
    },
    "/v1/revenue": {
      "post": {
        "tags": ["Omzet"],
        "operationId": "saveRevenue",
        "summary": "Omzet insturen",
        "description": "Omzet per dag voor één vestiging. Een dag die al bestaat, wordt overschreven.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/RevenueInput" },
              "example": {
                "locationId": "cm3f9x2k10004l708h2r1d6qa",
                "days": [
                  { "date": "2026-11-01", "amountCents": 284750 },
                  { "date": "2026-11-02", "amountCents": 193020 }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Opgeslagen",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["saved"],
                  "properties": { "saved": { "type": "integer", "description": "Aantal opgeslagen dagen" } }
                },
                "example": { "saved": 2 }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "429": { "$ref": "#/components/responses/TooManyRequests" }
        }
      }
    }
  },
  "webhooks": {
    "clock.in": {
      "post": {
        "summary": "Ingeklokt",
        "parameters": [{ "$ref": "#/components/parameters/WebhookEvent" }, { "$ref": "#/components/parameters/WebhookSignature" }, { "$ref": "#/components/parameters/WebhookTimestamp" }, { "$ref": "#/components/parameters/WebhookSignatureV2" }],
        "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClockWebhook" } } } },
        "responses": { "2XX": { "description": "Ontvangen. Antwoord binnen 5 seconden." } }
      }
    },
    "clock.out": {
      "post": {
        "summary": "Uitgeklokt",
        "parameters": [{ "$ref": "#/components/parameters/WebhookEvent" }, { "$ref": "#/components/parameters/WebhookSignature" }, { "$ref": "#/components/parameters/WebhookTimestamp" }, { "$ref": "#/components/parameters/WebhookSignatureV2" }],
        "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClockWebhook" } } } },
        "responses": { "2XX": { "description": "Ontvangen. Antwoord binnen 5 seconden." } }
      }
    },
    "shift.published": {
      "post": {
        "summary": "Rooster gepubliceerd",
        "parameters": [{ "$ref": "#/components/parameters/WebhookEvent" }, { "$ref": "#/components/parameters/WebhookSignature" }, { "$ref": "#/components/parameters/WebhookTimestamp" }, { "$ref": "#/components/parameters/WebhookSignatureV2" }],
        "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShiftPublishedWebhook" } } } },
        "responses": { "2XX": { "description": "Ontvangen. Antwoord binnen 5 seconden." } }
      }
    },
    "leave.approved": {
      "post": {
        "summary": "Verlof goedgekeurd",
        "parameters": [{ "$ref": "#/components/parameters/WebhookEvent" }, { "$ref": "#/components/parameters/WebhookSignature" }, { "$ref": "#/components/parameters/WebhookTimestamp" }, { "$ref": "#/components/parameters/WebhookSignatureV2" }],
        "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeaveApprovedWebhook" } } } },
        "responses": { "2XX": { "description": "Ontvangen. Antwoord binnen 5 seconden." } }
      }
    },
    "timesheet.approved": {
      "post": {
        "summary": "Uren goedgekeurd",
        "parameters": [{ "$ref": "#/components/parameters/WebhookEvent" }, { "$ref": "#/components/parameters/WebhookSignature" }, { "$ref": "#/components/parameters/WebhookTimestamp" }, { "$ref": "#/components/parameters/WebhookSignatureV2" }],
        "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TimesheetApprovedWebhook" } } } },
        "responses": { "2XX": { "description": "Ontvangen. Antwoord binnen 5 seconden." } }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "apiKey": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "sgk_…",
        "description": "API-sleutel uit Instellingen → Integraties"
      }
    },
    "parameters": {
      "From": {
        "name": "from",
        "in": "query",
        "required": true,
        "description": "Begin van de periode (ISO 8601). Een datum zonder tijd is middernacht UTC; geef voor Nederlandse dagen de tijdzone mee, bijv. 2026-11-02T00:00:00+01:00.",
        "schema": { "type": "string", "format": "date-time" },
        "example": "2026-11-02T00:00:00+01:00"
      },
      "To": {
        "name": "to",
        "in": "query",
        "required": true,
        "description": "Einde van de periode (telt niet mee). Hoogstens 31 dagen na from.",
        "schema": { "type": "string", "format": "date-time" },
        "example": "2026-11-09T00:00:00+01:00"
      },
      "WebhookEvent": {
        "name": "X-ShiftGo-Event",
        "in": "header",
        "required": true,
        "schema": { "type": "string" }
      },
      "WebhookSignature": {
        "name": "X-ShiftGo-Signature",
        "in": "header",
        "required": true,
        "description": "v1, voor bestaande koppelingen: sha256=<hex>, HMAC-SHA256 van de ruwe body met het geheim van de webhook (whsec_…). Gebruik liever X-ShiftGo-Signature-V2.",
        "schema": { "type": "string", "pattern": "^sha256=[0-9a-f]{64}$" }
      },
      "WebhookTimestamp": {
        "name": "X-ShiftGo-Timestamp",
        "in": "header",
        "required": true,
        "description": "Moment van versturen in seconden sinds 1970 (UTC). Weiger berichten die ouder zijn dan 5 minuten.",
        "schema": { "type": "string", "pattern": "^[0-9]{10}$" },
        "example": "1793602692"
      },
      "WebhookSignatureV2": {
        "name": "X-ShiftGo-Signature-V2",
        "in": "header",
        "required": true,
        "description": "Aanbevolen: t=<tijdstempel>,v1=<hex>. De hex is HMAC-SHA256 van tijdstempel + \".\" + ruwe body met het geheim van de webhook. Het tijdstempel is gelijk aan X-ShiftGo-Timestamp.",
        "schema": { "type": "string", "pattern": "^t=[0-9]{10},v1=[0-9a-f]{64}$" }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Ongeldige invoer, een periode van meer dan 31 dagen of een onbekende vestiging",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      },
      "Unauthorized": {
        "description": "Sleutel ontbreekt, is onjuist of is ingetrokken",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      },
      "Forbidden": {
        "description": "De organisatie heeft geen ShiftGo Enterprise, of is bij ShiftGo geblokkeerd (code ORG_SUSPENDED)",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      },
      "TooManyRequests": {
        "description": "Meer dan 300 verzoeken per minuut met deze sleutel of vanaf dit IP-adres (code RATE_LIMITED)",
        "headers": {
          "Retry-After": { "description": "Seconden tot je het opnieuw kunt proberen (bij de limiet per sleutel)", "schema": { "type": "integer", "minimum": 1 } }
        },
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      }
    },
    "schemas": {
      "Location": {
        "type": "object",
        "required": ["id", "name", "address", "city", "timezone"],
        "properties": {
          "id": { "type": "string" },
          "name": { "type": "string" },
          "address": { "type": "string", "description": "Leeg als het niet is ingevuld" },
          "city": { "type": "string", "description": "Leeg als het niet is ingevuld" },
          "timezone": { "type": "string", "example": "Europe/Amsterdam" }
        }
      },
      "Employee": {
        "type": "object",
        "required": ["id", "name", "employeeNumber", "contractType", "contractHoursPerWeek", "locations"],
        "properties": {
          "id": { "type": "string" },
          "name": { "type": "string" },
          "employeeNumber": { "type": ["string", "null"] },
          "contractType": { "type": "string", "enum": ["FIXED_HOURS", "ZERO_HOURS", "MIN_MAX", "FREELANCE"] },
          "contractHoursPerWeek": { "type": "number" },
          "locations": {
            "type": "array",
            "items": { "type": "object", "required": ["locationId"], "properties": { "locationId": { "type": "string" } } }
          }
        }
      },
      "Shift": {
        "type": "object",
        "required": ["id", "locationId", "employeeId", "positionId", "start", "end", "breakMinutes"],
        "properties": {
          "id": { "type": "string" },
          "locationId": { "type": "string" },
          "employeeId": { "type": ["string", "null"], "description": "null bij een open dienst" },
          "positionId": { "type": ["string", "null"] },
          "start": { "type": "string", "format": "date-time" },
          "end": { "type": "string", "format": "date-time", "description": "Bij een dienst zonder vaste eindtijd: het verwachte einde" },
          "breakMinutes": { "type": "integer" }
        }
      },
      "TimeEntry": {
        "type": "object",
        "required": ["id", "employeeId", "locationId", "shiftId", "start", "end", "breakMinutes", "netMinutes", "status"],
        "properties": {
          "id": { "type": "string" },
          "employeeId": { "type": "string" },
          "locationId": { "type": ["string", "null"] },
          "shiftId": { "type": ["string", "null"], "description": "null als er zonder dienst is geklokt" },
          "start": { "type": "string", "format": "date-time" },
          "end": { "type": ["string", "null"], "format": "date-time" },
          "breakMinutes": { "type": "integer" },
          "netMinutes": { "type": "integer", "description": "Gewerkte minuten zonder pauze" },
          "status": { "type": "string", "enum": ["APPROVED", "CORRECTED"] }
        }
      },
      "RevenueInput": {
        "type": "object",
        "required": ["locationId", "days"],
        "properties": {
          "locationId": { "type": "string" },
          "days": {
            "type": "array",
            "minItems": 1,
            "maxItems": 400,
            "items": {
              "type": "object",
              "required": ["date", "amountCents"],
              "properties": {
                "date": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" },
                "amountCents": { "type": "integer", "minimum": 0 }
              }
            }
          }
        }
      },
      "Error": {
        "type": "object",
        "required": ["message"],
        "properties": {
          "message": { "type": "string" },
          "code": { "type": "string", "description": "Vaste code bij sommige fouten, bijv. RATE_LIMITED of ORG_SUSPENDED", "examples": ["RATE_LIMITED"] },
          "issues": {
            "type": "array",
            "description": "Bij ongeldige invoer: welk veld niet klopt",
            "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }
          }
        }
      },
      "ClockWebhook": {
        "type": "object",
        "required": ["event", "createdAt", "data"],
        "properties": {
          "event": { "type": "string", "enum": ["clock.in", "clock.out"] },
          "createdAt": { "type": "string", "format": "date-time" },
          "data": {
            "type": "object",
            "required": ["employeeId", "locationId", "method", "at", "flags"],
            "properties": {
              "employeeId": { "type": "string" },
              "locationId": { "type": "string" },
              "method": { "type": "string", "enum": ["APP_GPS", "QR", "KIOSK_PIN", "NFC"] },
              "at": { "type": "string", "format": "date-time" },
              "flags": { "type": "array", "items": { "type": "string" }, "description": "Signalen voor de manager, zoals LATE, EARLY_OUT, NO_SHIFT of OUTSIDE_GEOFENCE" }
            }
          }
        }
      },
      "ShiftPublishedWebhook": {
        "type": "object",
        "required": ["event", "createdAt", "data"],
        "properties": {
          "event": { "const": "shift.published" },
          "createdAt": { "type": "string", "format": "date-time" },
          "data": {
            "type": "object",
            "required": ["locationId", "weekStart", "shifts"],
            "properties": {
              "locationId": { "type": "string" },
              "weekStart": { "type": "string", "format": "date", "description": "Maandag van de week" },
              "shifts": { "type": "integer", "description": "Aantal gepubliceerde diensten" }
            }
          }
        }
      },
      "LeaveApprovedWebhook": {
        "type": "object",
        "required": ["event", "createdAt", "data"],
        "properties": {
          "event": { "const": "leave.approved" },
          "createdAt": { "type": "string", "format": "date-time" },
          "data": {
            "type": "object",
            "required": ["employeeId", "leaveType", "startDate", "endDate", "minutes"],
            "properties": {
              "employeeId": { "type": "string" },
              "leaveType": { "type": "string", "description": "Naam van het verloftype" },
              "startDate": { "type": "string", "format": "date" },
              "endDate": { "type": "string", "format": "date" },
              "minutes": { "type": "integer" }
            }
          }
        }
      },
      "TimesheetApprovedWebhook": {
        "type": "object",
        "required": ["event", "createdAt", "data"],
        "properties": {
          "event": { "const": "timesheet.approved" },
          "createdAt": { "type": "string", "format": "date-time" },
          "data": {
            "type": "object",
            "required": ["ids"],
            "properties": { "ids": { "type": "array", "items": { "type": "string" }, "description": "Goedgekeurde uren (TimeEntry-id's)" } }
          }
        }
      }
    }
  }
}
