126 lines
6.4 KiB
Markdown
126 lines
6.4 KiB
Markdown
# Krona Staff Terminal: HTTP API Requirements & Specification
|
|
|
|
**Document Version:** 1.0.0
|
|
**Status:** Approved for Production
|
|
**Target Component:** Krona Staff Backend & Krona Staff Terminal / Windows Service Sync Client
|
|
|
|
---
|
|
|
|
## 1. Overview & Architectural Scope
|
|
|
|
The Krona Staff Terminal (`KronaStaffTerminal.exe`) and its companion Windows Service (`KronaStaffService.exe`) operate on Windows POS / kiosk devices in branch locations. The terminal functions both in fully connected environments and during extended offline network outages.
|
|
|
|
### Security Guarantees
|
|
1. **Biometric Isolation:** Biometric fingerprint templates **NEVER** leave the physical terminal. Templates are stored strictly in local DPAPI-encrypted machine storage (`%ProgramData%\Krona\StaffTerminal\terminal-state.dat`) and are matched on-device using the biometric matching engine. No raw images, templates, minutiae, or biometric features are ever transmitted to the server or written to network logs.
|
|
2. **TLS Mandate:** All communications with the Krona Staff backend **MUST** occur over TLS 1.3 or TLS 1.2 with strict certificate verification. Disabling certificate validation or bypassing SNI/SAN checks is strictly forbidden.
|
|
3. **Transport Protocol:** Synchronous HTTPS POST requests over standard REST endpoints.
|
|
|
|
---
|
|
|
|
## 2. Attendance Sync Endpoint Specification
|
|
|
|
### Endpoint
|
|
```http
|
|
POST /api/v1/staff/attendance/events
|
|
```
|
|
|
|
### Request Headers
|
|
| Header Name | Type | Required | Description | Example |
|
|
|---|---|---|---|---|
|
|
| `Content-Type` | String | Yes | Media type of payload | `application/json` |
|
|
| `Authorization` | String | Yes | Terminal Bearer API Key | `Bearer trm_sec_991823ab...` |
|
|
| `Idempotency-Key` | String | Yes | Unique idempotency key per event batch or event | `6ba7b810-9dad-11d1-80b4-00c04fd430c8` |
|
|
| `X-Request-Id` | String | Yes | Unique trace ID for telemetry and crash debugging | `req_01HV8G7P89J21...` |
|
|
| `User-Agent` | String | Yes | Terminal client identification | `KronaStaffTerminal/0.3.0 (Windows NT 10.0; Win64; x64)` |
|
|
|
|
---
|
|
|
|
## 3. Request Payloads
|
|
|
|
The synchronization client supports sending both individual attendance records and batched events.
|
|
|
|
### 3.1 Single Event Record Payload
|
|
```json
|
|
{
|
|
"eventId": "01J8R5QWXZ7M1P0T8C3D2E4F5G",
|
|
"employeeId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
|
|
"eventType": "CHECK_IN",
|
|
"occurredAtUtc": "2026-09-24T08:30:00.000Z",
|
|
"deviceId": "TERM-SPB-OFFICE-01",
|
|
"method": "BIOMETRIC_FINGERPRINT",
|
|
"isAutomatic": false,
|
|
"verificationScore": 87
|
|
}
|
|
```
|
|
|
|
### 3.2 Batch Sync Payload
|
|
When draining the offline sync queue after network recovery, the client posts an array of queued events:
|
|
```json
|
|
{
|
|
"deviceId": "TERM-SPB-OFFICE-01",
|
|
"batchId": "01J8R5R2H0K5N2P9Q7R1S3T4U5",
|
|
"events": [
|
|
{
|
|
"eventId": "01J8R5QWXZ7M1P0T8C3D2E4F5G",
|
|
"employeeId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
|
|
"eventType": "CHECK_IN",
|
|
"occurredAtUtc": "2026-09-24T08:30:00.000Z",
|
|
"method": "BIOMETRIC_FINGERPRINT",
|
|
"isAutomatic": false,
|
|
"verificationScore": 87
|
|
},
|
|
{
|
|
"eventId": "01J8R6A1B2C3D4E5F6G7H8J9K0",
|
|
"employeeId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
|
|
"eventType": "CHECK_OUT",
|
|
"occurredAtUtc": "2026-09-24T17:30:00.000Z",
|
|
"method": "SCHEDULED_AUTO",
|
|
"isAutomatic": true,
|
|
"verificationScore": null
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
### Field Definitions
|
|
- **`eventId`** (`string`, ULID or UUIDv4): Client-generated immutable identifier of the attendance event.
|
|
- **`employeeId`** (`string`, UUIDv4): Server-recognized unique ID of the employee.
|
|
- **`eventType`** (`string`): Enum representing the punch action:
|
|
- `CHECK_IN`: Arrival / work start.
|
|
- `CHECK_OUT`: Departure / work end.
|
|
- `BREAK_START`: Rest break start.
|
|
- `BREAK_END`: Rest break end.
|
|
- **`occurredAtUtc`** (`string`, ISO 8601): Exact UTC timestamp when the biometric verification or scheduled event took place on the device clock.
|
|
- **`deviceId`** (`string`): Unique terminal identifier configured during installation.
|
|
- **`method`** (`string`): Verification mechanism:
|
|
- `BIOMETRIC_FINGERPRINT`: Authenticated on hardware scanner with score >= threshold.
|
|
- `MANUAL_PIN`: Authenticated via administrator override PIN.
|
|
- `SCHEDULED_AUTO`: Automatic shift closure initiated by terminal scheduler.
|
|
- **`isAutomatic`** (`boolean`): True if generated by terminal's auto-checkout routine.
|
|
- **`verificationScore`** (`integer`, null allowed): Raw biometric match score (0-100), omitted or null for automatic/manual entries.
|
|
|
|
---
|
|
|
|
## 4. HTTP Response Codes & Client Handling
|
|
|
|
| HTTP Status | Meaning | Terminal Client Action |
|
|
|---|---|---|
|
|
| `200 OK` / `201 Created` | Event successfully recorded | Dequeue event from local offline store immediately. |
|
|
| `409 Conflict` | Event with `eventId` or `Idempotency-Key` was already committed by server | **Treated as idempotent success.** Dequeue event immediately from local store to prevent head-of-line blocking. |
|
|
| `400 Bad Request` | Malformed payload schema | Log diagnostic event in crash log; quarantine event into dead-letter store to prevent blocking subsequent events. |
|
|
| `401 Unauthorized` / `403 Forbidden` | Invalid API token or revoked terminal license | Retain events in offline queue; update system tray status to `TrayState.Error` (`401 Auth Error`); prompt administrator. |
|
|
| `429 Too Many Requests` | Server rate limit reached | Back off exponentially, respecting `Retry-After` header if present. |
|
|
| `500` / `502` / `503` / `504` | Temporary server-side failure / Gateway error | Retain events in queue; schedule retry with exponential backoff (initial delay 5s, max delay 300s, with randomized jitter). |
|
|
| Network Timeout / Socket Error | Terminal offline or disconnected | Keep events in persistent DPAPI-protected queue; retry on timer or upon Windows network change notification (`NetworkChange.NetworkAddressChanged`). |
|
|
|
|
---
|
|
|
|
## 5. Offline Queue Mechanics
|
|
|
|
1. **Storage Location:** `%ProgramData%\Krona\StaffTerminal\terminal-state.dat`.
|
|
2. **Protection:** Windows DPAPI `DataProtectionScope.LocalMachine` with restricted ACL (SYSTEM, Administrators, Users).
|
|
3. **Queue Discipline:** Strict FIFO ordering by `occurredAtUtc`.
|
|
4. **Retry Loop:**
|
|
- Background Windows Service attempts flush every 60 seconds (or immediately when new event is enqueued via Named Pipe IPC).
|
|
- If server is unreachable, delay multiplies by 1.5x up to 5 minutes cap.
|
|
- Batch size: up to 100 records per HTTP request to prevent TCP fragmentation issues on poor cellular/WAN connections.
|