krona-staff/docs/TERMINAL-API-REQUIREMENTS.md

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

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.2 (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

{
  "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:

{
  "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.