{
  "openapi": "3.0.4",
  "info": {
    "title": "CS4 ADM API",
    "description": "Integration API for ESSL / ZKTeco biometric devices. CS4 ADM support creates your application and issues its API keys; every key sees all devices, employees and punches of the application (devices on the CS4 ADM device server and on eSSL servers alike, in one shape). Base URL https://apiservice.adm.robeeta.com/api/v1. Authenticate with the X-Api-Key header. JSON is camelCase. Punch times are device-local wall clock (yyyy-MM-ddTHH:mm:ss, no offset); instants are UTC (…Z). Device commands are only queued (pending) — the device runs them on its next poll; read the result via GET /api/v1/commands/{id} or the command.completed webhook. Guide: https://apiservice.adm.robeeta.com/",
    "version": "v1"
  },
  "paths": {
    "/api/v1/me": {
      "get": {
        "tags": [
          "Application"
        ],
        "summary": "Returns the application, the key used for this request and where devices added with this key must report.",
        "description": "Needs no scope — use it to verify a key. `deviceServer` tells how to configure a device you add with this key:\nfor connection \"adm\" set the device's cloud server (ADMS) to host:port; for \"essl\" the device stays on that eSSL server.",
        "responses": {
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "429": {
            "description": "Too Many Requests",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MeResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/attendance": {
      "get": {
        "tags": [
          "Attendance"
        ],
        "summary": "Lists punches, newest first.",
        "description": "For integrations that import every punch, prefer the cursor feed GET /attendance/since.",
        "parameters": [
          {
            "name": "from",
            "in": "query",
            "description": "Device-local start (inclusive), e.g. 2026-11-01 or 2026-11-01T06:00:00.",
            "schema": {
              "type": "string",
              "description": "Device wall-clock times: yyyy-MM-ddTHH:mm:ss (no offset). Instants: UTC yyyy-MM-ddTHH:mm:ssZ.",
              "example": "2026-11-15T09:02:41"
            }
          },
          {
            "name": "to",
            "in": "query",
            "description": "Device-local end (exclusive).",
            "schema": {
              "type": "string",
              "description": "Device wall-clock times: yyyy-MM-ddTHH:mm:ss (no offset). Instants: UTC yyyy-MM-ddTHH:mm:ssZ.",
              "example": "2026-11-15T09:02:41"
            }
          },
          {
            "name": "pin",
            "in": "query",
            "description": "Only this employee code.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "deviceId",
            "in": "query",
            "description": "Only this device.",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "departmentId",
            "in": "query",
            "description": "Only employees of this department.",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "group",
            "in": "query",
            "description": "Only punches from devices with this group tag.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page",
            "in": "query",
            "description": "1-based page.",
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          },
          {
            "name": "pageSize",
            "in": "query",
            "description": "1–1000, default 100.",
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          }
        ],
        "responses": {
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "429": {
            "description": "Too Many Requests",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AttendanceDtoPagedResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/attendance/since": {
      "get": {
        "tags": [
          "Attendance"
        ],
        "summary": "Cursor feed: punches with id greater than `id`, in id (arrival) order.",
        "description": "Stable and gap-free for new data: store nextId after processing a page; when hasMore is true call again at once,\notherwise poll again later (e.g. every minute) or use the attendance.punch webhook as a trigger.\nPunches re-uploaded by a device for an older time still get a new, higher id, so they are never missed.",
        "parameters": [
          {
            "name": "id",
            "in": "query",
            "description": "Last id you processed (0 to start from the beginning). Pass the returned nextId on the next call.",
            "schema": {
              "type": "integer",
              "format": "int64",
              "default": 0
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "1–1000, default 500.",
            "schema": {
              "type": "integer",
              "format": "int32",
              "default": 500
            }
          },
          {
            "name": "group",
            "in": "query",
            "description": "Only punches from devices with this group tag (keep one cursor per group).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "429": {
            "description": "Too Many Requests",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AttendanceFeedResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/access-events": {
      "get": {
        "tags": [
          "Attendance"
        ],
        "summary": "Lists access-control events (door access devices), newest first.",
        "parameters": [
          {
            "name": "from",
            "in": "query",
            "description": "Device-local start (inclusive).",
            "schema": {
              "type": "string",
              "description": "Device wall-clock times: yyyy-MM-ddTHH:mm:ss (no offset). Instants: UTC yyyy-MM-ddTHH:mm:ssZ.",
              "example": "2026-11-15T09:02:41"
            }
          },
          {
            "name": "to",
            "in": "query",
            "description": "Device-local end (exclusive).",
            "schema": {
              "type": "string",
              "description": "Device wall-clock times: yyyy-MM-ddTHH:mm:ss (no offset). Instants: UTC yyyy-MM-ddTHH:mm:ssZ.",
              "example": "2026-11-15T09:02:41"
            }
          },
          {
            "name": "pin",
            "in": "query",
            "description": "Only this employee code.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "deviceId",
            "in": "query",
            "description": "Only this device.",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "page",
            "in": "query",
            "description": "1-based page.",
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          },
          {
            "name": "pageSize",
            "in": "query",
            "description": "1–1000, default 100.",
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          }
        ],
        "responses": {
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "429": {
            "description": "Too Many Requests",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AccessEventDtoPagedResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/commands": {
      "get": {
        "tags": [
          "Commands"
        ],
        "summary": "Lists commands, newest first.",
        "parameters": [
          {
            "name": "status",
            "in": "query",
            "description": "pending | sent | success | failed | fw_success | timeout | cancelled",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "deviceId",
            "in": "query",
            "description": "Only this device.",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "pin",
            "in": "query",
            "description": "Only commands for this employee code.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "batchId",
            "in": "query",
            "description": "Only commands queued together (returned by push / enroll / sync calls).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page",
            "in": "query",
            "description": "1-based page.",
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          },
          {
            "name": "pageSize",
            "in": "query",
            "description": "1–500, default 50.",
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          }
        ],
        "responses": {
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "429": {
            "description": "Too Many Requests",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CommandDtoPagedResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/commands/{id}": {
      "get": {
        "tags": [
          "Commands"
        ],
        "summary": "Gets one command — poll this until the status is final (success, failed, fw_success, timeout, cancelled).",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          }
        ],
        "responses": {
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "429": {
            "description": "Too Many Requests",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CommandDto"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/commands/{id}/cancel": {
      "post": {
        "tags": [
          "Commands"
        ],
        "summary": "Cancels a pending command. Commands already sent to the device can't be recalled (409).",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          }
        ],
        "responses": {
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "429": {
            "description": "Too Many Requests",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CommandDto"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "409": {
            "description": "Conflict",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/commands/{id}/retry": {
      "post": {
        "tags": [
          "Commands"
        ],
        "summary": "Re-queues a failed, timed-out or cancelled command as a NEW pending command (returned).",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          }
        ],
        "responses": {
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "429": {
            "description": "Too Many Requests",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "202": {
            "description": "Accepted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/QueuedResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "409": {
            "description": "Conflict",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/departments": {
      "get": {
        "tags": [
          "Departments"
        ],
        "summary": "Lists all departments with employee counts.",
        "responses": {
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "429": {
            "description": "Too Many Requests",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DepartmentDtoPagedResponse"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Departments"
        ],
        "summary": "Creates a department (name required, unique).",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DepartmentRequest"
              }
            },
            "text/json": {
              "schema": {
                "$ref": "#/components/schemas/DepartmentRequest"
              }
            },
            "application/*+json": {
              "schema": {
                "$ref": "#/components/schemas/DepartmentRequest"
              }
            }
          }
        },
        "responses": {
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "429": {
            "description": "Too Many Requests",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DepartmentDto"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "409": {
            "description": "Conflict",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/departments/{id}": {
      "get": {
        "tags": [
          "Departments"
        ],
        "summary": "Gets one department.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          }
        ],
        "responses": {
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "429": {
            "description": "Too Many Requests",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DepartmentDto"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          }
        }
      },
      "put": {
        "tags": [
          "Departments"
        ],
        "summary": "Updates a department. Omitted fields keep their value; \"\" clears code / description; parentId 0 clears the parent.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DepartmentRequest"
              }
            },
            "text/json": {
              "schema": {
                "$ref": "#/components/schemas/DepartmentRequest"
              }
            },
            "application/*+json": {
              "schema": {
                "$ref": "#/components/schemas/DepartmentRequest"
              }
            }
          }
        },
        "responses": {
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "429": {
            "description": "Too Many Requests",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DepartmentDto"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "409": {
            "description": "Conflict",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Departments"
        ],
        "summary": "Deletes a department (its employees keep existing without a department).",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          }
        ],
        "responses": {
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "429": {
            "description": "Too Many Requests",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeletedResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/devices": {
      "get": {
        "tags": [
          "Devices"
        ],
        "summary": "Lists the devices of the application (ADM and eSSL devices alike).",
        "parameters": [
          {
            "name": "search",
            "in": "query",
            "description": "Matches serial number, name or location.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "status",
            "in": "query",
            "description": "waiting | online | offline | blocked",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "group",
            "in": "query",
            "description": "Only devices with this group tag.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "429": {
            "description": "Too Many Requests",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeviceDtoPagedResponse"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Devices"
        ],
        "summary": "Registers a device serial number (allow-list). Status starts as \"waiting\" until the device connects.",
        "description": "The device reports where this API key's connection points (GET /api/v1/me → deviceServer): connection \"adm\" = the\ndevice pushes to the CS4 ADM device server (configure host:port on the device); \"essl\" = the device stays on that eSSL\nserver: its status and punches are read every minute and the last 3 months of punches are imported.\n409 when the serial is already registered (to you or another application) or the device limit is reached.",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateDeviceRequest"
              }
            },
            "text/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateDeviceRequest"
              }
            },
            "application/*+json": {
              "schema": {
                "$ref": "#/components/schemas/CreateDeviceRequest"
              }
            }
          }
        },
        "responses": {
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "429": {
            "description": "Too Many Requests",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeviceDto"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "409": {
            "description": "Conflict",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/devices/stats": {
      "get": {
        "tags": [
          "Devices"
        ],
        "summary": "Device counts by status.",
        "responses": {
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "429": {
            "description": "Too Many Requests",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeviceStatsDto"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/devices/{id}": {
      "get": {
        "tags": [
          "Devices"
        ],
        "summary": "Gets one device.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          }
        ],
        "responses": {
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "429": {
            "description": "Too Many Requests",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeviceDto"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          }
        }
      },
      "put": {
        "tags": [
          "Devices"
        ],
        "summary": "Updates name, location, time zone, FaceEx flag or group. Omitted fields keep their value; \"\" clears location / time zone / group.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateDeviceRequest"
              }
            },
            "text/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateDeviceRequest"
              }
            },
            "application/*+json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateDeviceRequest"
              }
            }
          }
        },
        "responses": {
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "429": {
            "description": "Too Many Requests",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeviceDto"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Devices"
        ],
        "summary": "Removes the device from the application. Its punches and commands are deleted with it; the device is refused afterwards.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          }
        ],
        "responses": {
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "429": {
            "description": "Too Many Requests",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeletedResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/devices/{id}/status": {
      "get": {
        "tags": [
          "Devices"
        ],
        "summary": "Live state of one device (online, last seen, counts) — the same for ADM and eSSL devices.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          }
        ],
        "responses": {
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "429": {
            "description": "Too Many Requests",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeviceStatusDto"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/devices/{id}/commands": {
      "post": {
        "tags": [
          "Devices"
        ],
        "summary": "Queues one command on the device.",
        "description": "Types: reboot, info, check, settime (device clock = now in the device time zone), userquery, biodataquery.\nWith the devices:admin scope also: clearattlog, cleardata, custom (raw command in \"text\").\nDevices on an eSSL server (source \"essl\") accept reboot, settime and check here (plus, through the employee\nendpoints, user add/delete, fingerprint/face enrollment and template push, and fetch-attendance) — other types return 422.\nThe command is only queued (status pending); the result arrives after the device's next poll —\nread it via GET /api/v1/commands/{id} or the command.completed webhook.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DeviceCommandRequest"
              }
            },
            "text/json": {
              "schema": {
                "$ref": "#/components/schemas/DeviceCommandRequest"
              }
            },
            "application/*+json": {
              "schema": {
                "$ref": "#/components/schemas/DeviceCommandRequest"
              }
            }
          }
        },
        "responses": {
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "429": {
            "description": "Too Many Requests",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "202": {
            "description": "Accepted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/QueuedResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "409": {
            "description": "Conflict",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "422": {
            "description": "Unprocessable Content",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          }
        }
      },
      "get": {
        "tags": [
          "Devices"
        ],
        "summary": "Commands of this device, newest first.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "Device id.",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "status",
            "in": "query",
            "description": "pending | sent | success | failed | fw_success | timeout | cancelled",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page",
            "in": "query",
            "description": "1-based page.",
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          },
          {
            "name": "pageSize",
            "in": "query",
            "description": "1–500, default 50.",
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          }
        ],
        "responses": {
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "429": {
            "description": "Too Many Requests",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CommandDtoPagedResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/devices/{id}/fetch-attendance": {
      "post": {
        "tags": [
          "Devices"
        ],
        "summary": "Asks the device to re-upload its punches between two device-local times (missing data recovery).",
        "description": "The punches arrive through the normal upload and show up in /attendance (duplicates are ignored).",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/FetchAttendanceRequest"
              }
            },
            "text/json": {
              "schema": {
                "$ref": "#/components/schemas/FetchAttendanceRequest"
              }
            },
            "application/*+json": {
              "schema": {
                "$ref": "#/components/schemas/FetchAttendanceRequest"
              }
            }
          }
        },
        "responses": {
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "429": {
            "description": "Too Many Requests",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "202": {
            "description": "Accepted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/QueuedResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/devices/{id}/sync-employees": {
      "post": {
        "tags": [
          "Devices"
        ],
        "summary": "Sends every active employee (optionally with fingerprint / face templates) to this device — e.g. a new or replaced device.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SyncEmployeesRequest"
              }
            },
            "text/json": {
              "schema": {
                "$ref": "#/components/schemas/SyncEmployeesRequest"
              }
            },
            "application/*+json": {
              "schema": {
                "$ref": "#/components/schemas/SyncEmployeesRequest"
              }
            }
          }
        },
        "responses": {
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "429": {
            "description": "Too Many Requests",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "202": {
            "description": "Accepted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/QueuedResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/devices/{id}/commands/cancel-pending": {
      "post": {
        "tags": [
          "Devices"
        ],
        "summary": "Cancels every pending (not yet sent) command of the device.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          }
        ],
        "responses": {
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "429": {
            "description": "Too Many Requests",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CancelledResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/employees": {
      "get": {
        "tags": [
          "Employees"
        ],
        "summary": "Lists employees ordered by name.",
        "parameters": [
          {
            "name": "search",
            "in": "query",
            "description": "PIN prefix, part of the name, exact card number or exact external reference.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "departmentId",
            "in": "query",
            "description": "Only this department.",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "active",
            "in": "query",
            "description": "true / false — only active / inactive employees.",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "group",
            "in": "query",
            "description": "Only employees with this group tag.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page",
            "in": "query",
            "description": "1-based page.",
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          },
          {
            "name": "pageSize",
            "in": "query",
            "description": "1–1000, default 100.",
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          }
        ],
        "responses": {
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "429": {
            "description": "Too Many Requests",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EmployeeDtoPagedResponse"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Employees"
        ],
        "summary": "Creates an employee (pin and name required). Then call POST /employees/{id}/push to send it to devices.",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EmployeeRequest"
              }
            },
            "text/json": {
              "schema": {
                "$ref": "#/components/schemas/EmployeeRequest"
              }
            },
            "application/*+json": {
              "schema": {
                "$ref": "#/components/schemas/EmployeeRequest"
              }
            }
          }
        },
        "responses": {
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "429": {
            "description": "Too Many Requests",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EmployeeDto"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "409": {
            "description": "Conflict",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/employees/{id}": {
      "get": {
        "tags": [
          "Employees"
        ],
        "summary": "Gets an employee by id.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          }
        ],
        "responses": {
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "429": {
            "description": "Too Many Requests",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EmployeeDto"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          }
        }
      },
      "put": {
        "tags": [
          "Employees"
        ],
        "summary": "Updates an employee. Omitted fields keep their value; \"\" clears a text field; departmentId 0 clears the department.",
        "description": "Changes reach the devices only after POST /employees/{id}/push.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EmployeeRequest"
              }
            },
            "text/json": {
              "schema": {
                "$ref": "#/components/schemas/EmployeeRequest"
              }
            },
            "application/*+json": {
              "schema": {
                "$ref": "#/components/schemas/EmployeeRequest"
              }
            }
          }
        },
        "responses": {
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "429": {
            "description": "Too Many Requests",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EmployeeDto"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "409": {
            "description": "Conflict",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Employees"
        ],
        "summary": "Deletes an employee. By default a user-delete command is first queued on every device where the employee may exist.",
        "description": "Attendance history is kept (punches keep the PIN).",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "Employee id.",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "removeFromDevices",
            "in": "query",
            "description": "Queue user.delete on the devices first (default true).",
            "schema": {
              "type": "boolean",
              "default": true
            }
          }
        ],
        "responses": {
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "429": {
            "description": "Too Many Requests",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeletedResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/employees/by-pin/{pin}": {
      "get": {
        "tags": [
          "Employees"
        ],
        "summary": "Gets an employee by PIN (employee code).",
        "parameters": [
          {
            "name": "pin",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "429": {
            "description": "Too Many Requests",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EmployeeDto"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/employees/by-ref/{externalRef}": {
      "get": {
        "tags": [
          "Employees"
        ],
        "summary": "Gets an employee by your external reference.",
        "parameters": [
          {
            "name": "externalRef",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "429": {
            "description": "Too Many Requests",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EmployeeDto"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/employees/{id}/push": {
      "post": {
        "tags": [
          "Employees"
        ],
        "summary": "Pushes the employee (user record + optionally stored fingerprint/face templates) to devices.",
        "description": "Body optional: deviceIds omitted = every non-blocked device. Commands are queued; track them by batchId.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PushEmployeeRequest"
              }
            },
            "text/json": {
              "schema": {
                "$ref": "#/components/schemas/PushEmployeeRequest"
              }
            },
            "application/*+json": {
              "schema": {
                "$ref": "#/components/schemas/PushEmployeeRequest"
              }
            }
          }
        },
        "responses": {
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "429": {
            "description": "Too Many Requests",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "202": {
            "description": "Accepted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/QueuedResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/employees/{id}/remove-from-devices": {
      "post": {
        "tags": [
          "Employees"
        ],
        "summary": "Removes the employee from devices (user record and templates on the device). The employee record stays.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RemoveEmployeeRequest"
              }
            },
            "text/json": {
              "schema": {
                "$ref": "#/components/schemas/RemoveEmployeeRequest"
              }
            },
            "application/*+json": {
              "schema": {
                "$ref": "#/components/schemas/RemoveEmployeeRequest"
              }
            }
          }
        },
        "responses": {
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "429": {
            "description": "Too Many Requests",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "202": {
            "description": "Accepted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/QueuedResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/employees/{id}/enroll": {
      "post": {
        "tags": [
          "Employees"
        ],
        "summary": "Starts remote enrollment on a device: the user record is (re)sent, then the device prompts for the finger / face.",
        "description": "Two commands are queued (user.add + enroll). The employee must scan within the device's enrollment timeout after the\ndevice picks the command up. Track the enroll command until success / fw_success / failed; the fingerprint/face\ntemplate is then uploaded by the device and appears under /employees/{id}/biometrics.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EnrollRequest"
              }
            },
            "text/json": {
              "schema": {
                "$ref": "#/components/schemas/EnrollRequest"
              }
            },
            "application/*+json": {
              "schema": {
                "$ref": "#/components/schemas/EnrollRequest"
              }
            }
          }
        },
        "responses": {
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "429": {
            "description": "Too Many Requests",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "202": {
            "description": "Accepted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/QueuedResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "409": {
            "description": "Conflict",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/employees/{id}/enrollments": {
      "get": {
        "tags": [
          "Employees"
        ],
        "summary": "Devices on which the employee is known, with fingerprint / face flags.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          }
        ],
        "responses": {
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "429": {
            "description": "Too Many Requests",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/EnrollmentDto"
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/employees/{id}/biometrics": {
      "get": {
        "tags": [
          "Employees"
        ],
        "summary": "Stored biometric templates of the employee — METADATA only (type, finger/slot, size, version); templates are never returned.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          }
        ],
        "responses": {
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "429": {
            "description": "Too Many Requests",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/BiometricDto"
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Employees"
        ],
        "summary": "Deletes the employee's stored fingerprint / face templates on the server.",
        "description": "Devices keep their copy until the user is removed from them (POST /employees/{id}/remove-from-devices) or re-pushed.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "Employee id.",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "type",
            "in": "query",
            "description": "Only this template type (1 fingerprint, 2 face, 9 visible-light face); omit for all.",
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          }
        ],
        "responses": {
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "429": {
            "description": "Too Many Requests",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BiometricsDeletedResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/reports/types": {
      "get": {
        "tags": [
          "Reports"
        ],
        "summary": "Available report types.",
        "responses": {
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "429": {
            "description": "Too Many Requests",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/ReportTypeDto"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/reports/run": {
      "post": {
        "tags": [
          "Reports"
        ],
        "summary": "Runs a report and returns it as JSON: title, subtitle, columns, rows (one value per column) and summary.",
        "description": "Dates are calendar dates (yyyy-MM-dd) of the device-local wall clock; at most 62 days per report.",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ReportRunRequest"
              }
            },
            "text/json": {
              "schema": {
                "$ref": "#/components/schemas/ReportRunRequest"
              }
            },
            "application/*+json": {
              "schema": {
                "$ref": "#/components/schemas/ReportRunRequest"
              }
            }
          }
        },
        "responses": {
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "429": {
            "description": "Too Many Requests",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReportResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/reports/run.{format}": {
      "get": {
        "tags": [
          "Reports"
        ],
        "summary": "Runs a report and downloads it as a file: run.xlsx (Excel), run.pdf (A4 landscape) or run.csv (UTF-8).",
        "parameters": [
          {
            "name": "format",
            "in": "path",
            "description": "xlsx | pdf | csv",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "type",
            "in": "query",
            "description": "Report type (GET /reports/types).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "from",
            "in": "query",
            "description": "First date, yyyy-MM-dd.",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "to",
            "in": "query",
            "description": "Last date, yyyy-MM-dd (inclusive).",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "departmentId",
            "in": "query",
            "description": "Only this department.",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "deviceId",
            "in": "query",
            "description": "Only punches of this device.",
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "pin",
            "in": "query",
            "description": "Only this employee code.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/octet-stream": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              },
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/octet-stream": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              },
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/octet-stream": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              },
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "429": {
            "description": "Too Many Requests",
            "content": {
              "application/octet-stream": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              },
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "200": {
            "description": "OK",
            "content": {
              "application/octet-stream": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "application/problem+json": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "application/json": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/octet-stream": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              },
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/webhooks/events": {
      "get": {
        "tags": [
          "Webhooks"
        ],
        "summary": "The event names you can subscribe to.",
        "responses": {
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "429": {
            "description": "Too Many Requests",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/WebhookEventDto"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/webhooks": {
      "get": {
        "tags": [
          "Webhooks"
        ],
        "summary": "Lists the webhooks of the application (secrets are never returned).",
        "responses": {
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "429": {
            "description": "Too Many Requests",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookDtoPagedResponse"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Webhooks"
        ],
        "summary": "Creates a webhook (HTTPS URL, at least one event). The signing secret is returned ONCE in the response.",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WebhookRequest"
              }
            },
            "text/json": {
              "schema": {
                "$ref": "#/components/schemas/WebhookRequest"
              }
            },
            "application/*+json": {
              "schema": {
                "$ref": "#/components/schemas/WebhookRequest"
              }
            }
          }
        },
        "responses": {
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "429": {
            "description": "Too Many Requests",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookSecretResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "409": {
            "description": "Conflict",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/webhooks/{id}": {
      "get": {
        "tags": [
          "Webhooks"
        ],
        "summary": "Gets one webhook.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          }
        ],
        "responses": {
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "429": {
            "description": "Too Many Requests",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookDto"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          }
        }
      },
      "put": {
        "tags": [
          "Webhooks"
        ],
        "summary": "Updates a webhook. Omitted fields keep their value. Setting isActive=true re-enables an auto-disabled webhook.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WebhookRequest"
              }
            },
            "text/json": {
              "schema": {
                "$ref": "#/components/schemas/WebhookRequest"
              }
            },
            "application/*+json": {
              "schema": {
                "$ref": "#/components/schemas/WebhookRequest"
              }
            }
          }
        },
        "responses": {
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "429": {
            "description": "Too Many Requests",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookDto"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Webhooks"
        ],
        "summary": "Deletes a webhook (pending deliveries are dropped).",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          }
        ],
        "responses": {
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "429": {
            "description": "Too Many Requests",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeletedResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/webhooks/{id}/rotate-secret": {
      "post": {
        "tags": [
          "Webhooks"
        ],
        "summary": "Generates a new signing secret (returned ONCE). The old secret stops working immediately.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          }
        ],
        "responses": {
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "429": {
            "description": "Too Many Requests",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookSecretResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/webhooks/{id}/deliveries": {
      "get": {
        "tags": [
          "Webhooks"
        ],
        "summary": "Delivery attempts of a webhook, newest first (status: pending | delivered | failed | dead).",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "Webhook id.",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "status",
            "in": "query",
            "description": "pending | delivered | failed | dead",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page",
            "in": "query",
            "description": "1-based page.",
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          },
          {
            "name": "pageSize",
            "in": "query",
            "description": "1–200, default 50.",
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          }
        ],
        "responses": {
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "429": {
            "description": "Too Many Requests",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookDeliveryDtoPagedResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/webhooks/{id}/deliveries/{deliveryId}/redeliver": {
      "post": {
        "tags": [
          "Webhooks"
        ],
        "summary": "Queues a delivery again (attempts reset; sent within seconds) — e.g. after fixing your endpoint.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          },
          {
            "name": "deliveryId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "format": "int64"
            }
          }
        ],
        "responses": {
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "429": {
            "description": "Too Many Requests",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RedeliveredResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "AccessEventDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "format": "int64"
          },
          "deviceId": {
            "type": "integer",
            "format": "int64"
          },
          "deviceName": {
            "type": "string",
            "nullable": true
          },
          "pin": {
            "type": "string",
            "nullable": true
          },
          "employeeName": {
            "type": "string",
            "nullable": true
          },
          "eventTime": {
            "type": "string",
            "description": "Device wall-clock times: yyyy-MM-ddTHH:mm:ss (no offset). Instants: UTC yyyy-MM-ddTHH:mm:ssZ.",
            "example": "2026-11-15T09:02:41"
          },
          "doorId": {
            "type": "string",
            "nullable": true
          },
          "eventType": {
            "type": "string",
            "nullable": true
          },
          "verifyType": {
            "type": "integer",
            "format": "int32",
            "nullable": true
          },
          "inOut": {
            "type": "integer",
            "format": "int32",
            "nullable": true
          },
          "receivedAt": {
            "type": "string",
            "description": "Device wall-clock times: yyyy-MM-ddTHH:mm:ss (no offset). Instants: UTC yyyy-MM-ddTHH:mm:ssZ.",
            "example": "2026-11-15T09:02:41"
          }
        },
        "additionalProperties": false,
        "description": "Access-control event (RTLOG). `eventTime` is device-local wall clock."
      },
      "AccessEventDtoPagedResponse": {
        "type": "object",
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AccessEventDto"
            }
          },
          "total": {
            "type": "integer",
            "format": "int64"
          },
          "page": {
            "type": "integer",
            "format": "int32"
          },
          "pageSize": {
            "type": "integer",
            "format": "int32"
          }
        },
        "additionalProperties": false,
        "description": "A page of a list. `page` is 1-based; `total` is the number of matching rows across all pages."
      },
      "ApiKeyInfoDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "format": "int64"
          },
          "name": {
            "type": "string"
          },
          "prefix": {
            "type": "string"
          },
          "scopes": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "ratePerMinute": {
            "type": "integer",
            "format": "int32"
          },
          "ipAllowlist": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "expiresAt": {
            "type": "string",
            "description": "Device wall-clock times: yyyy-MM-ddTHH:mm:ss (no offset). Instants: UTC yyyy-MM-ddTHH:mm:ssZ.",
            "nullable": true,
            "example": "2026-11-15T09:02:41"
          },
          "createdAt": {
            "type": "string",
            "description": "Device wall-clock times: yyyy-MM-ddTHH:mm:ss (no offset). Instants: UTC yyyy-MM-ddTHH:mm:ssZ.",
            "example": "2026-11-15T09:02:41"
          },
          "connection": {
            "type": "string"
          },
          "esslServer": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": false,
        "description": "The calling key. `connection` = where devices added with this key report: \"adm\" (CS4 ADM device server) or\n\"essl\" (the eSSL server `esslServer`). Set by CS4 ADM support; every key of the application sees all its data."
      },
      "ApplicationInfoDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "format": "int64"
          },
          "name": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "timeZone": {
            "type": "string"
          },
          "deviceLimit": {
            "type": "integer",
            "format": "int32"
          },
          "devicesUsed": {
            "type": "integer",
            "format": "int32"
          },
          "expiresAt": {
            "type": "string",
            "description": "Device wall-clock times: yyyy-MM-ddTHH:mm:ss (no offset). Instants: UTC yyyy-MM-ddTHH:mm:ssZ.",
            "nullable": true,
            "example": "2026-11-15T09:02:41"
          }
        },
        "additionalProperties": false,
        "description": "The application the key belongs to (created by CS4 ADM support). `status`: active | suspended."
      },
      "AttendanceDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "format": "int64"
          },
          "deviceId": {
            "type": "integer",
            "format": "int64"
          },
          "deviceName": {
            "type": "string",
            "nullable": true
          },
          "serialNumber": {
            "type": "string",
            "nullable": true
          },
          "employeeId": {
            "type": "integer",
            "format": "int64",
            "nullable": true
          },
          "pin": {
            "type": "string"
          },
          "employeeName": {
            "type": "string",
            "nullable": true
          },
          "departmentName": {
            "type": "string",
            "nullable": true
          },
          "punchTime": {
            "type": "string",
            "description": "Device wall-clock times: yyyy-MM-ddTHH:mm:ss (no offset). Instants: UTC yyyy-MM-ddTHH:mm:ssZ.",
            "example": "2026-11-15T09:02:41"
          },
          "status": {
            "type": "integer",
            "format": "int32"
          },
          "verifyType": {
            "type": "integer",
            "format": "int32"
          },
          "workCode": {
            "type": "string",
            "nullable": true
          },
          "receivedAt": {
            "type": "string",
            "description": "Device wall-clock times: yyyy-MM-ddTHH:mm:ss (no offset). Instants: UTC yyyy-MM-ddTHH:mm:ssZ.",
            "example": "2026-11-15T09:02:41"
          },
          "source": {
            "type": "string"
          },
          "group": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": false,
        "description": "A punch. `punchTime` is the DEVICE-LOCAL wall clock (no zone); `receivedAt` is the UTC instant the server stored it.\n`source`: \"adm\" (pushed by the device) or \"essl\" (imported from an eSSL server). `group` = group tag of the device."
      },
      "AttendanceDtoPagedResponse": {
        "type": "object",
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AttendanceDto"
            }
          },
          "total": {
            "type": "integer",
            "format": "int64"
          },
          "page": {
            "type": "integer",
            "format": "int32"
          },
          "pageSize": {
            "type": "integer",
            "format": "int32"
          }
        },
        "additionalProperties": false,
        "description": "A page of a list. `page` is 1-based; `total` is the number of matching rows across all pages."
      },
      "AttendanceFeedResponse": {
        "type": "object",
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AttendanceDto"
            }
          },
          "nextId": {
            "type": "integer",
            "format": "int64"
          },
          "hasMore": {
            "type": "boolean"
          }
        },
        "additionalProperties": false,
        "description": "Cursor feed page: pass `nextId` as `id` on the next call. `hasMore` = call again immediately."
      },
      "BiometricDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "format": "int64"
          },
          "type": {
            "type": "integer",
            "format": "int32"
          },
          "kind": {
            "type": "string"
          },
          "no": {
            "type": "integer",
            "format": "int32"
          },
          "index": {
            "type": "integer",
            "format": "int32"
          },
          "valid": {
            "type": "boolean"
          },
          "duress": {
            "type": "boolean"
          },
          "version": {
            "type": "string"
          },
          "format": {
            "type": "integer",
            "format": "int32"
          },
          "size": {
            "type": "integer",
            "format": "int32"
          },
          "sourceDeviceId": {
            "type": "integer",
            "format": "int64",
            "nullable": true
          },
          "updatedAt": {
            "type": "string",
            "description": "Device wall-clock times: yyyy-MM-ddTHH:mm:ss (no offset). Instants: UTC yyyy-MM-ddTHH:mm:ssZ.",
            "example": "2026-11-15T09:02:41"
          }
        },
        "additionalProperties": false,
        "description": "Biometric template METADATA (the template itself is never returned)."
      },
      "BiometricsDeletedResponse": {
        "type": "object",
        "properties": {
          "deleted": {
            "type": "integer",
            "format": "int32"
          }
        },
        "additionalProperties": false,
        "description": "Stored templates deleted on the server (devices keep theirs until the user is removed / re-pushed)."
      },
      "CancelledResponse": {
        "type": "object",
        "properties": {
          "cancelled": {
            "type": "integer",
            "format": "int32"
          }
        },
        "additionalProperties": false,
        "description": "Result of cancelling every pending command of a device."
      },
      "CommandDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "format": "int64"
          },
          "cmdId": {
            "type": "string"
          },
          "deviceId": {
            "type": "integer",
            "format": "int64"
          },
          "deviceName": {
            "type": "string",
            "nullable": true
          },
          "serialNumber": {
            "type": "string",
            "nullable": true
          },
          "type": {
            "type": "string"
          },
          "command": {
            "type": "string"
          },
          "employeePin": {
            "type": "string",
            "nullable": true
          },
          "status": {
            "type": "string"
          },
          "source": {
            "type": "string"
          },
          "requestedBy": {
            "type": "string"
          },
          "batchId": {
            "type": "string",
            "nullable": true
          },
          "createdAt": {
            "type": "string",
            "description": "Device wall-clock times: yyyy-MM-ddTHH:mm:ss (no offset). Instants: UTC yyyy-MM-ddTHH:mm:ssZ.",
            "example": "2026-11-15T09:02:41"
          },
          "sentAt": {
            "type": "string",
            "description": "Device wall-clock times: yyyy-MM-ddTHH:mm:ss (no offset). Instants: UTC yyyy-MM-ddTHH:mm:ssZ.",
            "nullable": true,
            "example": "2026-11-15T09:02:41"
          },
          "executedAt": {
            "type": "string",
            "description": "Device wall-clock times: yyyy-MM-ddTHH:mm:ss (no offset). Instants: UTC yyyy-MM-ddTHH:mm:ssZ.",
            "nullable": true,
            "example": "2026-11-15T09:02:41"
          },
          "sendCount": {
            "type": "integer",
            "format": "int32"
          },
          "returnCode": {
            "type": "integer",
            "format": "int32",
            "nullable": true
          },
          "result": {
            "type": "string",
            "nullable": true
          },
          "error": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": false,
        "description": "A device command. Lifecycle: pending → sent → success | failed | fw_success | timeout (or cancelled while pending)."
      },
      "CommandDtoPagedResponse": {
        "type": "object",
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CommandDto"
            }
          },
          "total": {
            "type": "integer",
            "format": "int64"
          },
          "page": {
            "type": "integer",
            "format": "int32"
          },
          "pageSize": {
            "type": "integer",
            "format": "int32"
          }
        },
        "additionalProperties": false,
        "description": "A page of a list. `page` is 1-based; `total` is the number of matching rows across all pages."
      },
      "CreateDeviceRequest": {
        "type": "object",
        "properties": {
          "serialNumber": {
            "type": "string",
            "description": "Device serial number as shown on the device (System info → Serial No.)."
          },
          "name": {
            "type": "string",
            "description": "Display name (defaults to the serial number).",
            "nullable": true
          },
          "location": {
            "type": "string",
            "nullable": true
          },
          "timeZone": {
            "type": "string",
            "description": "IANA time zone id of the device location (e.g. Asia/Kolkata) (defaults to the application time zone). Used by \"settime\".",
            "nullable": true
          },
          "supportsFaceEx": {
            "type": "boolean",
            "description": "True for visible-light face devices (FaceEx enrollment)."
          },
          "group": {
            "type": "string",
            "description": "Optional tag of your own (e.g. your customer / company id, 1–64 chars); filter lists with ?group=.",
            "nullable": true
          }
        },
        "additionalProperties": false,
        "description": "Register a device serial number for your application (the device is then accepted when it connects). Where the device\nreports (CS4 ADM device server or an eSSL server) is decided by the API key's connection — see GET /api/v1/me."
      },
      "DeletedResponse": {
        "type": "object",
        "properties": {
          "deleted": {
            "type": "boolean"
          },
          "batchId": {
            "type": "string",
            "nullable": true
          },
          "removalCommands": {
            "type": "integer",
            "format": "int32"
          },
          "message": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "DepartmentDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "format": "int64"
          },
          "name": {
            "type": "string"
          },
          "code": {
            "type": "string",
            "nullable": true
          },
          "description": {
            "type": "string",
            "nullable": true
          },
          "parentId": {
            "type": "integer",
            "format": "int64",
            "nullable": true
          },
          "parentName": {
            "type": "string",
            "nullable": true
          },
          "isActive": {
            "type": "boolean"
          },
          "employeeCount": {
            "type": "integer",
            "format": "int32"
          },
          "createdAt": {
            "type": "string",
            "description": "Device wall-clock times: yyyy-MM-ddTHH:mm:ss (no offset). Instants: UTC yyyy-MM-ddTHH:mm:ssZ.",
            "example": "2026-11-15T09:02:41"
          }
        },
        "additionalProperties": false
      },
      "DepartmentDtoPagedResponse": {
        "type": "object",
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DepartmentDto"
            }
          },
          "total": {
            "type": "integer",
            "format": "int64"
          },
          "page": {
            "type": "integer",
            "format": "int32"
          },
          "pageSize": {
            "type": "integer",
            "format": "int32"
          }
        },
        "additionalProperties": false,
        "description": "A page of a list. `page` is 1-based; `total` is the number of matching rows across all pages."
      },
      "DepartmentRequest": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "nullable": true
          },
          "code": {
            "type": "string",
            "nullable": true
          },
          "description": {
            "type": "string",
            "nullable": true
          },
          "parentId": {
            "type": "integer",
            "description": "Parent department id (0 = none on PUT).",
            "format": "int64",
            "nullable": true
          },
          "isActive": {
            "type": "boolean",
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "DeviceCommandRequest": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "description": "reboot | info | check | settime | userquery | biodataquery — and with the devices:admin scope:\nclearattlog (delete all punches on the device) | cleardata (delete ALL users, templates and punches) | custom (raw ADMS command text)."
          },
          "text": {
            "type": "string",
            "description": "Raw command text, only for type \"custom\" (e.g. \"DATA QUERY USERINFO PIN=1001\").",
            "nullable": true
          }
        },
        "additionalProperties": false,
        "description": "Queue a single command on a device."
      },
      "DeviceDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "format": "int64"
          },
          "serialNumber": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "location": {
            "type": "string",
            "nullable": true
          },
          "timeZone": {
            "type": "string",
            "nullable": true
          },
          "effectiveTimeZone": {
            "type": "string"
          },
          "supportsFaceEx": {
            "type": "boolean"
          },
          "status": {
            "type": "string"
          },
          "blockedReason": {
            "type": "string",
            "nullable": true
          },
          "ipAddress": {
            "type": "string",
            "nullable": true
          },
          "model": {
            "type": "string",
            "nullable": true
          },
          "firmwareVersion": {
            "type": "string",
            "nullable": true
          },
          "pushVersion": {
            "type": "string",
            "nullable": true
          },
          "userCount": {
            "type": "integer",
            "format": "int32",
            "nullable": true
          },
          "fpCount": {
            "type": "integer",
            "format": "int32",
            "nullable": true
          },
          "faceCount": {
            "type": "integer",
            "format": "int32",
            "nullable": true
          },
          "attlogCount": {
            "type": "integer",
            "format": "int32",
            "nullable": true
          },
          "pendingCommands": {
            "type": "integer",
            "format": "int32"
          },
          "lastSeenAt": {
            "type": "string",
            "description": "Device wall-clock times: yyyy-MM-ddTHH:mm:ss (no offset). Instants: UTC yyyy-MM-ddTHH:mm:ssZ.",
            "nullable": true,
            "example": "2026-11-15T09:02:41"
          },
          "lastPunchAt": {
            "type": "string",
            "description": "Device wall-clock times: yyyy-MM-ddTHH:mm:ss (no offset). Instants: UTC yyyy-MM-ddTHH:mm:ssZ.",
            "nullable": true,
            "example": "2026-11-15T09:02:41"
          },
          "onlineSince": {
            "type": "string",
            "description": "Device wall-clock times: yyyy-MM-ddTHH:mm:ss (no offset). Instants: UTC yyyy-MM-ddTHH:mm:ssZ.",
            "nullable": true,
            "example": "2026-11-15T09:02:41"
          },
          "createdAt": {
            "type": "string",
            "description": "Device wall-clock times: yyyy-MM-ddTHH:mm:ss (no offset). Instants: UTC yyyy-MM-ddTHH:mm:ssZ.",
            "example": "2026-11-15T09:02:41"
          },
          "source": {
            "type": "string"
          },
          "esslServer": {
            "type": "string",
            "nullable": true
          },
          "esslLinked": {
            "type": "boolean"
          },
          "esslLastPing": {
            "type": "string",
            "description": "Device wall-clock times: yyyy-MM-ddTHH:mm:ss (no offset). Instants: UTC yyyy-MM-ddTHH:mm:ssZ.",
            "nullable": true,
            "example": "2026-11-15T09:02:41"
          },
          "group": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": false,
        "description": "A registered device (serial number = allow-list entry). `source`: \"adm\" (pushes to CS4 ADM) or \"essl\" (stays on the\neSSL server `esslServer`; synced every minute). `group` = your optional tag. `esslLinked` = the serial was found on that eSSL server;\n`esslLastPing` is the eSSL server's wall clock."
      },
      "DeviceDtoPagedResponse": {
        "type": "object",
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DeviceDto"
            }
          },
          "total": {
            "type": "integer",
            "format": "int64"
          },
          "page": {
            "type": "integer",
            "format": "int32"
          },
          "pageSize": {
            "type": "integer",
            "format": "int32"
          }
        },
        "additionalProperties": false,
        "description": "A page of a list. `page` is 1-based; `total` is the number of matching rows across all pages."
      },
      "DeviceServerDto": {
        "type": "object",
        "properties": {
          "connection": {
            "type": "string"
          },
          "host": {
            "type": "string",
            "nullable": true
          },
          "ports": {
            "type": "array",
            "items": {
              "type": "integer",
              "format": "int32"
            }
          },
          "esslServer": {
            "type": "string",
            "nullable": true
          },
          "instructions": {
            "type": "string"
          }
        },
        "additionalProperties": false,
        "description": "How to configure a device added with this key. \"adm\": set the device's cloud server (ADMS) to `host` and one of\n`ports` (HTTP, no TLS). \"essl\": the device stays on the eSSL server `esslServer` — configure it there as usual."
      },
      "DeviceStatsDto": {
        "type": "object",
        "properties": {
          "total": {
            "type": "integer",
            "format": "int32"
          },
          "online": {
            "type": "integer",
            "format": "int32"
          },
          "offline": {
            "type": "integer",
            "format": "int32"
          },
          "waiting": {
            "type": "integer",
            "format": "int32"
          },
          "blocked": {
            "type": "integer",
            "format": "int32"
          }
        },
        "additionalProperties": false
      },
      "DeviceStatusDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "format": "int64"
          },
          "serialNumber": {
            "type": "string"
          },
          "source": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "online": {
            "type": "boolean"
          },
          "lastSeenAt": {
            "type": "string",
            "description": "Device wall-clock times: yyyy-MM-ddTHH:mm:ss (no offset). Instants: UTC yyyy-MM-ddTHH:mm:ssZ.",
            "nullable": true,
            "example": "2026-11-15T09:02:41"
          },
          "onlineSince": {
            "type": "string",
            "description": "Device wall-clock times: yyyy-MM-ddTHH:mm:ss (no offset). Instants: UTC yyyy-MM-ddTHH:mm:ssZ.",
            "nullable": true,
            "example": "2026-11-15T09:02:41"
          },
          "lastPunchAt": {
            "type": "string",
            "description": "Device wall-clock times: yyyy-MM-ddTHH:mm:ss (no offset). Instants: UTC yyyy-MM-ddTHH:mm:ssZ.",
            "nullable": true,
            "example": "2026-11-15T09:02:41"
          },
          "pendingCommands": {
            "type": "integer",
            "format": "int32"
          },
          "userCount": {
            "type": "integer",
            "format": "int32",
            "nullable": true
          },
          "fpCount": {
            "type": "integer",
            "format": "int32",
            "nullable": true
          },
          "faceCount": {
            "type": "integer",
            "format": "int32",
            "nullable": true
          },
          "attlogCount": {
            "type": "integer",
            "format": "int32",
            "nullable": true
          }
        },
        "additionalProperties": false,
        "description": "Live state of one device — the same shape for \"adm\" and \"essl\" devices."
      },
      "EmployeeDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "format": "int64"
          },
          "pin": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "cardNumber": {
            "type": "string",
            "nullable": true
          },
          "hasPassword": {
            "type": "boolean"
          },
          "privilege": {
            "type": "integer",
            "format": "int32"
          },
          "departmentId": {
            "type": "integer",
            "format": "int64",
            "nullable": true
          },
          "departmentName": {
            "type": "string",
            "nullable": true
          },
          "email": {
            "type": "string",
            "nullable": true
          },
          "mobile": {
            "type": "string",
            "nullable": true
          },
          "designation": {
            "type": "string",
            "nullable": true
          },
          "externalRef": {
            "type": "string",
            "nullable": true
          },
          "isActive": {
            "type": "boolean"
          },
          "deviceCount": {
            "type": "integer",
            "format": "int32"
          },
          "fpCount": {
            "type": "integer",
            "format": "int32"
          },
          "faceCount": {
            "type": "integer",
            "format": "int32"
          },
          "createdAt": {
            "type": "string",
            "description": "Device wall-clock times: yyyy-MM-ddTHH:mm:ss (no offset). Instants: UTC yyyy-MM-ddTHH:mm:ssZ.",
            "example": "2026-11-15T09:02:41"
          },
          "updatedAt": {
            "type": "string",
            "description": "Device wall-clock times: yyyy-MM-ddTHH:mm:ss (no offset). Instants: UTC yyyy-MM-ddTHH:mm:ssZ.",
            "example": "2026-11-15T09:02:41"
          },
          "group": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "EmployeeDtoPagedResponse": {
        "type": "object",
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/EmployeeDto"
            }
          },
          "total": {
            "type": "integer",
            "format": "int64"
          },
          "page": {
            "type": "integer",
            "format": "int32"
          },
          "pageSize": {
            "type": "integer",
            "format": "int32"
          }
        },
        "additionalProperties": false,
        "description": "A page of a list. `page` is 1-based; `total` is the number of matching rows across all pages."
      },
      "EmployeeRequest": {
        "type": "object",
        "properties": {
          "pin": {
            "type": "string",
            "description": "Employee code = user id on the devices (1–24 letters or digits; most firmware accepts digits only, max 9).",
            "nullable": true
          },
          "name": {
            "type": "string",
            "nullable": true
          },
          "cardNumber": {
            "type": "string",
            "description": "RFID card number (digits).",
            "nullable": true
          },
          "password": {
            "type": "string",
            "description": "Device keypad password (up to 8 digits). Never returned by the API (see hasPassword).",
            "nullable": true
          },
          "privilege": {
            "type": "integer",
            "description": "0 user (default), 2 enroller, 6 admin, 14 super admin.",
            "format": "int32",
            "nullable": true
          },
          "departmentId": {
            "type": "integer",
            "description": "Department id (0 = none on PUT).",
            "format": "int64",
            "nullable": true
          },
          "email": {
            "type": "string",
            "nullable": true
          },
          "mobile": {
            "type": "string",
            "nullable": true
          },
          "designation": {
            "type": "string",
            "nullable": true
          },
          "externalRef": {
            "type": "string",
            "description": "Your own identifier for this employee (unique per application) — look up with GET /employees/by-ref/{externalRef}.",
            "nullable": true
          },
          "group": {
            "type": "string",
            "description": "Optional tag of your own (e.g. your customer / company id, 1–64 chars; \"\" clears on PUT); filter with ?group=.",
            "nullable": true
          },
          "isActive": {
            "type": "boolean",
            "nullable": true
          }
        },
        "additionalProperties": false,
        "description": "Employee fields. On POST, `pin` and `name` are required. On PUT omitted fields keep their value; the PIN can't change."
      },
      "EnrollRequest": {
        "type": "object",
        "properties": {
          "deviceId": {
            "type": "integer",
            "format": "int64"
          },
          "kind": {
            "type": "string",
            "description": "\"fp\" (fingerprint) or \"face\"."
          },
          "fingerIndex": {
            "type": "integer",
            "description": "Finger 0–9 (fp only): 0 left little … 4 left thumb, 5 right thumb … 9 right little. Default 6 (right index).",
            "format": "int32"
          }
        },
        "additionalProperties": false,
        "description": "Start remote enrollment on a device: the employee then scans the finger / face on that device."
      },
      "EnrollmentDto": {
        "type": "object",
        "properties": {
          "deviceId": {
            "type": "integer",
            "format": "int64"
          },
          "deviceName": {
            "type": "string",
            "nullable": true
          },
          "serialNumber": {
            "type": "string",
            "nullable": true
          },
          "deviceStatus": {
            "type": "string",
            "nullable": true
          },
          "hasFingerprint": {
            "type": "boolean"
          },
          "hasFace": {
            "type": "boolean"
          },
          "syncedAt": {
            "type": "string",
            "description": "Device wall-clock times: yyyy-MM-ddTHH:mm:ss (no offset). Instants: UTC yyyy-MM-ddTHH:mm:ssZ.",
            "example": "2026-11-15T09:02:41"
          }
        },
        "additionalProperties": false,
        "description": "Employee is known on a device (user record pushed / uploaded), with biometric flags."
      },
      "FetchAttendanceRequest": {
        "type": "object",
        "properties": {
          "from": {
            "type": "string",
            "description": "Device-local start, yyyy-MM-ddTHH:mm:ss (no offset).",
            "example": "2026-11-15T09:02:41"
          },
          "to": {
            "type": "string",
            "description": "Device-local end, yyyy-MM-ddTHH:mm:ss (no offset).",
            "example": "2026-11-15T09:02:41"
          }
        },
        "additionalProperties": false,
        "description": "Ask the device to re-upload punches in a device-local time range."
      },
      "MeResponse": {
        "type": "object",
        "properties": {
          "application": {
            "$ref": "#/components/schemas/ApplicationInfoDto"
          },
          "key": {
            "$ref": "#/components/schemas/ApiKeyInfoDto"
          },
          "deviceServer": {
            "$ref": "#/components/schemas/DeviceServerDto"
          }
        },
        "additionalProperties": false,
        "description": "The calling key, its application and where devices added with this key must send their data."
      },
      "ProblemDetails": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "nullable": true
          },
          "title": {
            "type": "string",
            "nullable": true
          },
          "status": {
            "type": "integer",
            "format": "int32",
            "nullable": true
          },
          "detail": {
            "type": "string",
            "nullable": true
          },
          "instance": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": { }
      },
      "PushEmployeeRequest": {
        "type": "object",
        "properties": {
          "deviceIds": {
            "type": "array",
            "items": {
              "type": "integer",
              "format": "int64"
            },
            "description": "Target devices; omit (null) for every non-blocked device of the application.",
            "nullable": true
          },
          "includeBiometrics": {
            "type": "boolean",
            "description": "Also send the stored fingerprint / face templates."
          }
        },
        "additionalProperties": false
      },
      "QueuedResponse": {
        "type": "object",
        "properties": {
          "batchId": {
            "type": "string",
            "nullable": true
          },
          "count": {
            "type": "integer",
            "format": "int32"
          },
          "commands": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CommandDto"
            }
          },
          "message": {
            "type": "string"
          }
        },
        "additionalProperties": false,
        "description": "Result of an action that queued device commands. The commands are only QUEUED (status pending): each device fetches\nthem on its next poll. Read the outcome with GET /api/v1/commands/{id} (or by batchId) or via the command.completed webhook."
      },
      "RedeliveredResponse": {
        "type": "object",
        "properties": {
          "queued": {
            "type": "boolean"
          },
          "deliveryId": {
            "type": "integer",
            "format": "int64"
          }
        },
        "additionalProperties": false,
        "description": "A delivery queued again (attempts reset; sent within seconds)."
      },
      "RemoveEmployeeRequest": {
        "type": "object",
        "properties": {
          "deviceIds": {
            "type": "array",
            "items": {
              "type": "integer",
              "format": "int64"
            },
            "description": "Target devices; omit (null) for every device where the employee may exist.",
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "ReportResponse": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "subtitle": {
            "type": "string"
          },
          "columns": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "rows": {
            "type": "array",
            "items": {
              "type": "array",
              "items": { }
            }
          },
          "summary": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ReportSummaryItem"
            }
          }
        },
        "additionalProperties": false,
        "description": "A computed report. Each row has one value per column (strings, numbers, dates as yyyy-MM-dd)."
      },
      "ReportRunRequest": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "description": "One of GET /reports/types (e.g. daily-attendance)."
          },
          "from": {
            "type": "string",
            "format": "date"
          },
          "to": {
            "type": "string",
            "format": "date"
          },
          "departmentId": {
            "type": "integer",
            "format": "int64",
            "nullable": true
          },
          "deviceId": {
            "type": "integer",
            "format": "int64",
            "nullable": true
          },
          "pin": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": false,
        "description": "Run a report. Dates are calendar dates (yyyy-MM-dd) in device-local time; at most 62 days."
      },
      "ReportSummaryItem": {
        "type": "object",
        "properties": {
          "label": {
            "type": "string"
          },
          "value": {
            "type": "string"
          }
        },
        "additionalProperties": false
      },
      "ReportTypeDto": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string"
          },
          "label": {
            "type": "string"
          },
          "description": {
            "type": "string"
          }
        },
        "additionalProperties": false
      },
      "SyncEmployeesRequest": {
        "type": "object",
        "properties": {
          "includeBiometrics": {
            "type": "boolean",
            "description": "Also send stored fingerprint / face templates."
          }
        },
        "additionalProperties": false
      },
      "UpdateDeviceRequest": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "nullable": true
          },
          "location": {
            "type": "string",
            "nullable": true
          },
          "timeZone": {
            "type": "string",
            "nullable": true
          },
          "supportsFaceEx": {
            "type": "boolean",
            "nullable": true
          },
          "group": {
            "type": "string",
            "description": "Your group tag (\"\" clears it).",
            "nullable": true
          }
        },
        "additionalProperties": false,
        "description": "Update a device. Omitted fields keep their value. The serial number can't be changed."
      },
      "WebhookDeliveryDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "format": "int64"
          },
          "webhookId": {
            "type": "integer",
            "format": "int64"
          },
          "webhookName": {
            "type": "string",
            "nullable": true
          },
          "event": {
            "type": "string"
          },
          "deliveryId": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "attempts": {
            "type": "integer",
            "format": "int32"
          },
          "lastStatusCode": {
            "type": "integer",
            "format": "int32",
            "nullable": true
          },
          "lastError": {
            "type": "string",
            "nullable": true
          },
          "createdAt": {
            "type": "string",
            "description": "Device wall-clock times: yyyy-MM-ddTHH:mm:ss (no offset). Instants: UTC yyyy-MM-ddTHH:mm:ssZ.",
            "example": "2026-11-15T09:02:41"
          },
          "deliveredAt": {
            "type": "string",
            "description": "Device wall-clock times: yyyy-MM-ddTHH:mm:ss (no offset). Instants: UTC yyyy-MM-ddTHH:mm:ssZ.",
            "nullable": true,
            "example": "2026-11-15T09:02:41"
          },
          "nextAttemptAt": {
            "type": "string",
            "description": "Device wall-clock times: yyyy-MM-ddTHH:mm:ss (no offset). Instants: UTC yyyy-MM-ddTHH:mm:ssZ.",
            "example": "2026-11-15T09:02:41"
          },
          "payload": {
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "WebhookDeliveryDtoPagedResponse": {
        "type": "object",
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/WebhookDeliveryDto"
            }
          },
          "total": {
            "type": "integer",
            "format": "int64"
          },
          "page": {
            "type": "integer",
            "format": "int32"
          },
          "pageSize": {
            "type": "integer",
            "format": "int32"
          }
        },
        "additionalProperties": false,
        "description": "A page of a list. `page` is 1-based; `total` is the number of matching rows across all pages."
      },
      "WebhookDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "format": "int64"
          },
          "name": {
            "type": "string"
          },
          "url": {
            "type": "string"
          },
          "events": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "isActive": {
            "type": "boolean"
          },
          "failureCount": {
            "type": "integer",
            "format": "int32"
          },
          "disabledReason": {
            "type": "string",
            "nullable": true
          },
          "createdBy": {
            "type": "string"
          },
          "createdAt": {
            "type": "string",
            "description": "Device wall-clock times: yyyy-MM-ddTHH:mm:ss (no offset). Instants: UTC yyyy-MM-ddTHH:mm:ssZ.",
            "example": "2026-11-15T09:02:41"
          }
        },
        "additionalProperties": false
      },
      "WebhookDtoPagedResponse": {
        "type": "object",
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/WebhookDto"
            }
          },
          "total": {
            "type": "integer",
            "format": "int64"
          },
          "page": {
            "type": "integer",
            "format": "int32"
          },
          "pageSize": {
            "type": "integer",
            "format": "int32"
          }
        },
        "additionalProperties": false,
        "description": "A page of a list. `page` is 1-based; `total` is the number of matching rows across all pages."
      },
      "WebhookEventDto": {
        "type": "object",
        "properties": {
          "event": {
            "type": "string"
          },
          "description": {
            "type": "string"
          }
        },
        "additionalProperties": false
      },
      "WebhookRequest": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "nullable": true
          },
          "url": {
            "type": "string",
            "description": "HTTPS endpoint that receives POSTed JSON events.",
            "nullable": true
          },
          "events": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Subscribed events (see GET /webhooks/events).",
            "nullable": true
          },
          "isActive": {
            "type": "boolean",
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "WebhookSecretResponse": {
        "type": "object",
        "properties": {
          "webhook": {
            "$ref": "#/components/schemas/WebhookDto"
          },
          "secret": {
            "type": "string"
          },
          "note": {
            "type": "string"
          }
        },
        "additionalProperties": false,
        "description": "Returned on create / rotate: the signing secret is shown ONCE — store it now."
      }
    },
    "securitySchemes": {
      "ApiKey": {
        "type": "apiKey",
        "description": "API key issued by CS4 ADM support for your application, e.g. adm_k3y9pr3f_…",
        "name": "X-Api-Key",
        "in": "header"
      }
    }
  },
  "security": [
    {
      "ApiKey": [ ]
    }
  ],
  "tags": [
    {
      "name": "Attendance",
      "description": "Punches and access events. Times of punches/events are the DEVICE-LOCAL wall clock (yyyy-MM-ddTHH:mm:ss, no offset);\nfilters `from`/`to` use the same wall clock (`from` inclusive, `to` exclusive)."
    },
    {
      "name": "Commands",
      "description": "Device commands of the application. Lifecycle: pending (queued) → sent (taken by the device on its poll) →\nsuccess | failed | fw_success (device said failed but a punch proves the enrollment worked) | timeout (no reply);\na pending command can be cancelled."
    },
    {
      "name": "Departments",
      "description": "Departments (used to group employees in lists and reports)."
    },
    {
      "name": "Devices",
      "description": "Devices of your application. A device is accepted by the server only after its serial number is registered here (or by\nCS4 ADM support). Device commands are only QUEUED: the device fetches them on its next poll (usually within seconds when online).\nOne combined list in one shape: devices connected to CS4 ADM (source \"adm\") and devices that stay on an eSSL server\n(source \"essl\"). Where a new device reports is decided by the API key's connection (GET /api/v1/me)."
    },
    {
      "name": "Employees",
      "description": "Employees (device users). The PIN (employee code) is the user id on the devices and can't be changed.\nCreating or updating an employee does NOT change the devices — call /push (or /devices/{id}/sync-employees)."
    },
    {
      "name": "Application",
      "description": "The calling API key, its application and the device server to configure on devices."
    },
    {
      "name": "Reports",
      "description": "Attendance reports computed from punches with the application's working hours."
    },
    {
      "name": "Webhooks",
      "description": "Webhooks: the platform POSTs JSON events to your URL, signed with `X-ADM-Signature: t=<unix>,v1=<hex>`\n= HMAC-SHA256(secret, \"<t>.<raw body>\"). Failed deliveries are retried with exponential backoff (8 attempts);\na webhook is disabled automatically after 50 consecutive failures."
    }
  ]
}