Scanner App API — Version 1

v1 · stable · frozen

Binding interface specification for the Chainway C72 scanner app. This document is the single source of truth for the app developer. All changes are strictly additive (new optional fields, new endpoints). Breaking changes only appear under /api/scanner/v2/….

Single Source of Truth · Stability Guarantee

This page (/scanner-api-docs) is the only communication channel with the scanner app developer (Puru). Everything binding lives here — base URLs, endpoints, payloads, status values, auth, offline queue, error codes. Nothing is shared via chat, email or external docs. Once marked as v1, existing endpoints, paths, fields, types and status values will never change. Breaking changes only appear under /api/scanner/v2/….

Live Monitor — see your requests as they arrive

Open /scanner-monitor in any browser, paste your device Bearer token, and you'll see every request the server received — within 2 seconds, with full request/response body. No login required, the token is the only credential needed.

→ Open Live Monitor (/scanner-monitor)

The device is dumb. The server is smart.

The scanner only reads EPCs and sends them to the REST API.
No business logic on the device (no PO matching, no stock calculation, no inventory rules).
The server decides, based on the selected mode, what action to take.
No printer integration on the device. Label printing and re-tagging happen in the backoffice (browser).

Visual reference for the app developer: every screen shown here maps to a mode and one or more API endpoints below.

Device Specs & Global Behavior

Specs & Behavior

All screens

Resolution: 720 × 1440 px (Chainway C72)
Language switcher: DE / EN in top-right status bar on every screen. Persisted per device (LocalStorage). Default = German.
Antenna: only active while trigger is held.
Haptic feedback: vibration on every successful scan.
Color code: Green = OK, Yellow = Warning, Red = Error.
Offline pill: yellow badge with queue count, only visible when queue > 0.