Skip to main content

POS Overlay & ONVIF Replay API

Overview​

The POS Overlay API enables external systems such as POS terminals, ERP systems, and automation scripts to integrate with ITVDesk IPCam by sending transaction events that are synchronized with live video and recordings.

The API is designed to be simple to implement, audit-safe, and fully ONVIF-compatible.

Availability: POS integration is available in ITVDesk v8.9.3 and newer.

Key Capabilities​

  • Live POS overlay on video (OSD)
  • Optional silent mode (no on-screen overlay)
  • Accurate bill-based indexing (billId)
  • Search & replay by bill
  • ONVIF Profile G replay
  • Standard RTSP replay for third‑party players
tip

All POS requests are handled by the ONVIF HTTP port service. No separate POS service is required.

Typical POS Workflow​

open → item* → total → close → search → replay
  1. Open a bill (open)
  2. Add one or more items (item)
  3. Send total (total)
  4. Close the bill (close or TTL)
  5. Search by billId
  6. Replay the exact video segment

Endpoints​

POST /pos/push​

Controls POS sessions, overlay rendering, and bill lifecycle.

http://ITVDESK_IP:PORT/pos/push

POST /pos/search​

Searches for a closed bill and returns replay information.

http://ITVDESK_IP:PORT/pos/search
EXAMPLE Endpoints format
Endpoints format example

POS Push API​

Required Fields​

  • uri (string, required)
    RTSP stream URI (the virtual IP camera stream)

  • token (string, required)
    Authentication in username:password format

  • cmd (string, required)
    One of: open, item, total, close

Optional Fields​

  • title (string)
    Cash desk / register name

  • billId (string)
    Transaction ID (required for open)

  • billid (string)
    Legacy spelling, equivalent to billId (backward compatible)

  • text (string)
    Item line or total text

  • ttl (int)
    Time‑to‑live in milliseconds

  • silent (bool)
    When true, disables on‑screen overlay while keeping recording and indexing

Silent Mode​

When silent: true is provided:

  • No POS overlay is rendered on the video
  • Recording continues normally
  • Bill indexing and replay remain fully functional

This mode is recommended for:

  • Background auditing
  • Privacy‑sensitive installations
  • POS systems that do not require visible overlays

POS Commands Example​

Open Bill​

curl -X POST "http://192.168.68.83:7000/pos/push" \
-H "Content-Type: application/json" \
-d '{
  "uri": "rtsp://192.168.68.83:5554/ipc1-stream1/screenlive",
  "token": "admin:admin",
  "cmd": "open",
  "billId": "TEST-0001",
  "title": "CASH DESK 1",
  "ttl": 15000
}'

Effect

  • Bill start time is stored
  • POS session becomes active
  • TTL countdown starts
  • Recording behavior depends on selected recording mode

Add Item​

curl -X POST "http://192.168.68.83:7000/pos/push" \
-H "Content-Type: application/json" \
-d '{
  "uri": "rtsp://192.168.68.83:5554/ipc1-stream1/screenlive",
  "token": "admin:admin",
  "cmd": "item",
  "text": "COFFEE 2.50"
}'

Notes

  • Can be called multiple times
  • Order is preserved
  • TTL is refreshed on each call

Add Total​

curl -X POST "http://192.168.68.83:7000/pos/push" \
-H "Content-Type: application/json" \
-d '{
  "uri": "rtsp://192.168.68.83:5554/ipc1-stream1/screenlive",
  "token": "admin:admin",
  "cmd": "total",
  "text": "TOTAL 6.40"
}'

Close Bill​

curl -X POST "http://192.168.68.83:7000/pos/push" \
-H "Content-Type: application/json" \
-d '{
  "uri": "rtsp://192.168.68.83:5554/ipc1-stream1/screenlive",
  "token": "admin:admin",
  "cmd": "close",
  "billId": "TEST-0001"
}'

Behavior

  • Bill end time is stored
  • Replay becomes available
  • If close is not sent, TTL will auto‑close the bill

POS Search API​

curl -X POST "http://192.168.68.83:7000/pos/search" \
-H "Content-Type: application/json" \
-d '{
  "uri": "rtsp://192.168.68.83:5554/ipc1-stream1/screenlive",
  "token": "admin:admin",
  "billId": "TEST-0001"
}'

Response (Success)​

{
  "found": true,
  "billId": "TEST-0001",
  "startUtc": 1770248211,
  "endUtc": 1770248236,
  "status": "closed",
  "durationSec": 25,
  "recordingToken": "RecordingToken_7",
  "replayUrl": "rtsp://.../replay?earliest=1770248211&latest=1770248236"
}
About the examples (curl)

All request examples use curl for demonstration purposes only.

curl is a command-line HTTP client used here to clearly show the HTTP endpoint, required headers, and exact JSON payloads.

You do not need to use curl in production.
In real integrations, these HTTP POST requests are typically sent from POS software, ERP systems, backend services, automation scripts, or any system capable of sending JSON over HTTP (e.g. C/C++, C#, Java, JavaScript, Python, PHP, PLC/automation gateways).

Errors​

  • 409 — Bill still open
  • 404 — Bill not started
  • 410 — Recording removed (FIFO cleanup)

Recording Modes​

Recording control

POS Start & Stop Recording Trigger​

  • open → start recording and open a new segment
  • close → finalize segment and stop recording

Best for:

  • One bill = one video file

Auto Start Recording on Startup​

  • Recording starts with the application
  • POS defines bill boundaries only

Best for:

  • 24/7 IP camera behavior

Auto Start/Stop on Stream Connection​

  • Recording runs only while clients are connected
  • POS does not control recording lifecycle

Manual Start/Stop​

  • Controlled by the user
  • POS only provides indexing

POS-Based Motion Detection Trigger​

When ITVDesk IPCamera is connected to an external NVR / VMS recorder, POS events can be used to explicitly control motion detection signals.

Behavior​

  • POS open (bill opened)
    → Motion Detection ON (true)
    → Recorder receives a motion event indicating active transaction

  • POS close (bill closed)
    → Motion Detection OFF (false)
    → Recorder receives motion end / clear event

Purpose​

This allows POS activity to be treated as a logical motion source, even when there is no physical movement in the scene.

Typical use cases:

  • Transaction-based recording triggers
  • Faster event search on NVR timelines
  • Clear correlation between sales activity and video
  • Reduced false motion events

Notes​

  • This is a virtual motion event, generated by ITVDesk
  • Works alongside standard video-based motion detection
  • Supported only when an external recorder is connected to ITVDesk
  • Motion events follow the exact bill lifecycle (open → close)

Replay Compatibility​

Replay works in both modes:

  • ONVIF Profile G (standard search & playback)
  • Standard RTSP replay

replayUrl is a standard RTSP URL and can be opened by any RTSP / ONVIF client: VMS, NVR, VLC, FFmpeg, ffplay.

ffplay -rtsp_transport tcp "REPLAY_URL"
tip

ITVDesk VMS provides fast native browsing and control of recordings using ONVIF Profile G, including:

  • timeline‑based navigation
  • instant search by billId
  • play, pause, seek, and speed control
  • direct validation of POS‑to‑video synchronization

This makes ITVDesk VMS ideal for testing, verification, and daily operations.

Notes for Integrators​

  • POS API is HTTP‑based and stateless
  • State is maintained per RTSP stream
  • One active bill per stream
  • Replay is available only after bill close
  • FIFO cleanup may remove recordings (HTTP 410)
  • Default TTL: 300s (5 minutes)
  • Max TTL: 900s (15 minutes)
Last updated on