Terminal Firmware Integration Guide

This guide describes the API integration for scale terminal firmware. The terminal is a remote self-service scale device that communicates with the server to manage weighing sessions and orders.

Base URL: /functions/v1 Authentication: All terminal endpoints require the x-terminal-key header.

x-terminal-key: your-terminal-api-key

Architecture Overview

Key Concepts

• Terminal — Remote self-service scale device running firmware
• Scale — Server-side entity representing the scale’s state
• Session — A lock mechanism to prevent concurrent access to the scale
• Order — A completed weighing transaction with payment
• Scale Command — Server-initiated actions for the terminal to execute
• WebSocket Realtime — Used for unidirectional state synchronization from server to terminal

State Synchronization

Direction	Mechanism
Terminal → Server	PATCH /api/terminal/scales/{scaleId}
Server → Terminal	scale_commands INSERT events via WebSocket

The terminal subscribes to WebSocket for:

• scales table UPDATE events (detect session changes)
• scale_commands table INSERT events (receive new commands)

Order Creation Flows

There are two distinct flows — see order-flows for full details.

Flow	Trigger	Use case
Terminal-Driven	Terminal controls entire process	Walk-up kiosk
User/Mobile-Driven	Mobile app initiates, terminal responds to commands	Remote-triggered weighing

Scale State Synchronization

Terminal Push (Heartbeat)

Terminal should periodically update its state even without commands:

Endpoint: PATCH /api/terminal/scales/{scaleId}

{
  "stableWeight": 25000,
  "status": "IDLE"
}

Get Full Scale State

Endpoint: GET /api/terminal/scales/{scaleId}

Best Practices

Idempotency

• Always check command status before executing
• Handle already-completed commands gracefully
• Use unique order IDs generated by terminal

State Synchronization

• Subscribe to WebSocket updates immediately on startup
• Poll for commands on reconnection
• Use scaleSeq to detect missed commands

Session Management

• Prolong sessions regularly (every 2–3 minutes if 5-minute duration)
• Always end sessions explicitly
• Handle session timeouts gracefully

Error Recovery

• Retry failed operations with exponential backoff
• Mark commands as FAILED with descriptive errors
• Log all API interactions for debugging

Photo Upload

• Compress images before upload (target: < 1 MB per photo)
• Upload photos immediately after order creation
• Retry failed uploads

Database Schema (Reference)

Key Tables

Table	Purpose
scales	Scale state and configuration
scale_sessions	Active and historical sessions
scale_commands	Server-to-terminal commands
orders	Completed orders
order_photos	Photos associated with orders
scale_cameras	Cameras associated with each scale

Important Fields

scales table: id, name, number, enabled, status, stableWeight, truckNumber, truckTrailerNumber, axis1–axis12, activeSessionId

scale_commands table: id, scaleId, name, status, payload, scaleSeq, createdAt, ackedAt, endedAt

scale_sessions table: id, scaleId, userId, lockedBy, lockedUntil, status (ACTIVE/ENDED/EXPIRED), reason

Related

• order-flows — terminal-driven vs user-driven flows
• scale-commands — command types and status flow
• websocket-realtime — WebSocket connection details
• known-scales — production and test scale IDs