POS Overlay & POS-to-Video Synchronization (ITVDesk IPCam)

1. OverviewThe POS Overlay API enables real-time display of receipt data on video, ensuring that every transaction is visually and temporally synchronized with the recording.Typical workflow:

1. Open a receipt
2. Add item lines
3. Display the total amount
4. Close the receipt (manually or automatically)

All displayed POS data is:

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

2. API EndpointPOSTProtocol: HTTP
Method: POST
Content-Type: application/json3. Required JSON ParametersParameterTypeDescriptionuristringRTSP stream URI where the POS overlay will be displayedtokenstringAuthentication informatcmdstringPOS command (,,,) 4. Optional ParametersParameterTypeDescriptiontitlestringCash desk / register namebillidstringReceipt / transaction identifiertextstringItem or total textttlintegerTime-to-live in millisecondsNote:defines how long the overlay remains visible if thecommand is not sent.
 5. POS Commands5.1– Open Receipt SessionInitializes a new POS overlay session.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 starts
• TTL countdown begins
   

5.2– Add Receipt ItemAdds 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 appends a new line
• TTL is refreshed on each call

5.3– Display Total AmountDisplays the final total.

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 POS OverlayImmediately closes the POS overlay.

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)Ifis not sent:

• The overlay automatically closes 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 and 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
• Multiple streams are supported simultaneously
• Overlay text is embedded directly into recorded video

10. ONVIF Replay – Search & Playback by Receipt (billId)10.1 OverviewITVDesk extends standard ONVIF Replay (Profile G) by enabling video search and playback based on POS receipt number ().Each receipt is:

• Displayed on screen
• Embedded into the video recording
• Indexed internally with exact UTC timestamps

10.2 How It Works

1. POS system sends

   billId

   via

   /pos/push

2. ITVDesk associates it with:
   • RTSP stream URI
   • Recording token
   • Exact UTC timestamps (open / close)
3. Transaction data is stored as searchable metadata
4. Replay is returned as a standard ONVIF-compatible RTSP stream

10.3 POS Recording LifecycleActionEffectopenReceipt session starts and is timestampeditemReceipt lines appended as video metadatacloseReceipt finalized and indexedRecordingVideo contains synchronized POS overlay 10.4 Search API – Find Recording by billIdPOSThttp://<ITVDESK_IP>:7000/pos/searchRequest example:{
  "uri":    "rtsp://192.168.68.76:554/ipc1-stream1/screenlive",
  "token":  "admin:admin",
  "billId": "2026-01-14-0330123"
}

10.5 Search Response Example{
  "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"
}
11. ONVIF Replay & POS Integration Benefits

• Instant video lookup by receipt number
• Accurate POS-to-video correlation
• No manual timestamp searching
• ONVIF-standard interoperability
• Professional audit and compliance workflows

This feature is designed for retail, hospitality, and security environments where precise transaction-to-video correlation is critical.For further questions, integration support, or advanced use cases, please reply to this topic or contact ITVDesk support.Best regards,
ITVDesk Team