ITVDesk IPCam – POS Overlay API Manual

1. Overview

The POS Overlay API allows external systems (POS, ERP, scripts) to display receipt data directly on the screen and inside the video stream generated by ITVDesk IPCam.

This enables full POS-to-video synchronization, where each transaction is visually embedded into the recorded stream.

Typical workflow:

Open a receipt
Add item lines
Display total amount
Close the receipt (manually or automatically)

All displayed text is:

Shown live on screen
Embedded into the video recording
Time-synchronized with the stream

2. API Endpoint


POST http://<ITVDESK_IP>:7033/pos/push

ONVIF Protocol: HTTP
Method: POST
Content-Type: application/json

3. Required JSON Parameters

Parameter	Type	Description
`uri`	string	RTSP stream URI where text will be displayed
`token`	string	Authentication in `username:password` format
`cmd`	string	POS command (`open`, `item`, `total`, `close`)

4. Optional Parameters

Parameter	Type	Description
`title`	string	Cash desk / register name
`billid`	string	Receipt / transaction ID
`text`	string	Item or total text to display
`ttl`	integer	Time to live in milliseconds

Note:
ttl defines how long the overlay stays visible if close is not sent.

5. POS Commands (`cmd`)

5.1 `open` – Open Receipt Session

Initializes a new POS overlay session and opens the display window.


 
curl -i -X POST "http://192.168.68.82:7033/pos/push" \
  -H "Content-Type: application/json" \
  -d '{
    "uri":    "rtsp://192.168.68.82:5554/ipc1-stream1/screenlive",
    "token":  "admin:admin",
    "cmd":    "open",
    "title":  "CASH DESK 1",
    "billid": "2026-01-14-0330123",
    "ttl":    5000
  }'

Effect:

POS overlay window appears
Receipt session is started
TTL countdown begins

5.2 `item` – Add Receipt Item

Adds a new line to the active receipt.


curl -i -X POST "http://192.168.68.82:7033/pos/push" \
  -H "Content-Type: application/json" \
  -d '{
    "uri":    "rtsp://192.168.68.82:5554/ipc1-stream1/screenlive",
    "token":  "admin:admin",
    "cmd":    "item",
    "title":  "CASH DESK 1",
    "billid": "2026-01-14-0330123",
    "text":   "COFFEE 2.50",
    "ttl":    5000
  }'

Notes:

Can be called multiple times
Each call adds a new line
TTL is refreshed

5.3 `total` – Display Total Amount

Displays the final total of the receipt.


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

Effect:

Final total line is displayed
Overlay remains visible until closed or TTL expires

5.4 `close` – Close POS Overlay

Closes the POS overlay window immediately.


curl -i -X POST "http://192.168.68.82:7033/pos/push" \
  -H "Content-Type: application/json" \
  -d '{
    "uri":   "rtsp://192.168.68.82:5554/ipc1-stream1/screenlive",
    "token": "admin:admin",
    "cmd":   "close"
  }'

Effect:

Overlay disappears instantly
Receipt session ends

6. Automatic Close (TTL)

If close is not sent:

The overlay will automatically close after ttl expires
TTL acts as a safety fallback

Example:

ttl: 5000 → overlay closes after 5 seconds of inactivity

7. Recommended Call Sequence

open
item (repeat as needed)
total
close (or wait for TTL)

8. Common Use Cases

POS + Video synchronization
Cash register monitoring
Transaction verification
Fraud prevention
Retail and hospitality surveillance

9. Integration Notes

API is HTTP stateless, but stateful per RTSP stream
One active POS session per stream
Supports multiple streams simultaneously
Overlay text is embedded into recorded video

10. ONVIF Replay – Search & Playback by Receipt (billId)

10.1 Overview

ITVDesk extends standard ONVIF Replay functionality by enabling video search and playback based on POS receipt number (billId).

Each POS transaction is visually displayed on screen, embedded into the recorded video stream, and indexed internally using the provided billId. This allows exact transaction-to-video correlation without manual time searching.

10.2 How It Works

POS system sends billId using the existing /pos/push API
ITVDesk associates the billId with:
- RTSP stream URI
- Recording token
- Exact UTC timestamps (open / close)
Transaction data is stored as searchable metadata
Replay requests return an ONVIF-compatible replay stream

10.3 POS Recording Lifecycle

Action	Effect
`open`	Receipt session is started and timestamped
`item`	Receipt lines are appended as video metadata
`close`	Receipt is finalized and indexed for replay
Recording	Video contains POS overlay synchronized with the transaction

10.4 Search API – Find Recording by billId

Endpoint:

POST http://<ITVDESK_IP>:7000/pos/search

Request example:

{
  "uri":    "rtsp://192.168.68.76:554/ipc1-stream1/screenlive",
  "token":  "admin:admin",
  "billId": "2026-01-14-0330123"
}

Parameter	Type	Description
`uri`	string	RTSP stream associated with the POS transaction
`token`	string	Authentication in `username:password` format
`billId`	string	Receipt / transaction identifier

10.5 Search Response – Replay Information

Example response:

{
  "found": true,
  "billId": "2026-01-14-0330123",
  "utc": 1768601388,
  "recordingToken": "RecordingToken_16",
  "replayUrl": "rtsp://192.168.68.81:554/ipc1-stream1/screenlive/replay?earliest=1768601368&latest=1768601398"
}

Field	Description
`recordingToken`	ONVIF Recording token associated with the transaction
`startTime`	Transaction start time (UTC)
`endTime`	Transaction end time (UTC)
`replayUri`	RTSP replay URI usable by ONVIF clients and media players

10.6 Usage Scenarios

Instant video lookup by receipt number
Fraud investigation and transaction verification
POS-to-video audit trails
Retail and hospitality compliance review

10.7 Notes

Replay functionality is compatible with ONVIF Profile G
Search works with segmented and FIFO recordings
Replay URI can be opened in ONVIF-compliant VMS or RTSP players
Receipt search does not require manual timestamp input

How ONVIF Replay Works in ITVDesk

What is ONVIF Replay (Playback)

ONVIF Replay provides standardized access to recorded video (and audio) from ONVIF-compliant devices and recording systems. Unlike live streaming, replay allows playback from a specific point in the past, which is essential for event review, forensic analysis, and compliance.

ITVDesk fully supports ONVIF Replay (Profile G), ensuring compatibility with ONVIF VMS clients and RTSP players.

Key Capabilities

Playback from an exact UTC timestamp
Forward and reverse playback
Variable playback speeds
Keyframe-only playback for fast browsing
Accurate time-synchronized video review

Accurate Time Synchronization

ITVDesk uses ONVIF Replay timestamp mechanisms to ensure that each video frame is associated with its exact UTC creation time. This guarantees reliable reverse playback, correct stream startup on keyframes, and precise event correlation.

Transport and Reliability

For replay operations, RTSP over TCP is recommended to ensure reliable delivery, especially during fast-forward, rewind, and reverse playback. This provides stable and predictable replay behavior.

Replay Control

Replay is controlled using standard RTSP commands, allowing clients to:

Select exact time ranges using UTC timestamps
Adjust playback speed and direction
Request real-time or accelerated data delivery
Filter frames for efficient scanning

ONVIF Replay and POS Integration

ITVDesk uniquely integrates POS data with ONVIF Replay. Each receipt (billId) is visually embedded into the video, indexed with precise timestamps, and can later be retrieved automatically using replay search.

This allows instant video lookup by receipt number, without manual time searching.

Benefits for Customers

Faster investigations
Accurate POS-to-video correlation
Reduced manual work
ONVIF-standard interoperability
Professional audit and compliance workflows

ITVDesk IPCam – POS Overlay API Manual

1. Overview

2. API Endpoint

3. Required JSON Parameters

4. Optional Parameters

5. POS Commands (cmd)

5.1 open – Open Receipt Session

5.2 item – Add Receipt Item

5.3 total – Display Total Amount

5.4 close – Close POS Overlay

6. Automatic Close (TTL)

7. Recommended Call Sequence

8. Common Use Cases

9. Integration Notes

10. ONVIF Replay – Search & Playback by Receipt (billId)

10.1 Overview

10.2 How It Works

10.3 POS Recording Lifecycle

10.4 Search API – Find Recording by billId

10.5 Search Response – Replay Information

10.6 Usage Scenarios

10.7 Notes

How ONVIF Replay Works in ITVDesk

What is ONVIF Replay (Playback)

Key Capabilities

Accurate Time Synchronization

Transport and Reliability

Replay Control

ONVIF Replay and POS Integration

Benefits for Customers

5. POS Commands (`cmd`)

5.1 `open` – Open Receipt Session

5.2 `item` – Add Receipt Item

5.3 `total` – Display Total Amount

5.4 `close` – Close POS Overlay