The cart is empty

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

ParameterTypeDescription
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

ParameterTypeDescription
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

  1. open

  2. item (repeat as needed)

  3. total

  4. 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

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

10.3 POS Recording Lifecycle

ActionEffect
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"
}
ParameterTypeDescription
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"
}
FieldDescription
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