IPTV API 1 – Basic

Version – 08/09/2025.

Scope

With the scope of this integration, VConnect will be able to send the necessary information so that the guest can be shown their name on the TV in their room and the content in their language.

This API enables sending the following information from VConnect to the IPTV system:

	VConnect -> IPTV System	IPTV System -> VConnect
Reservation information	* Create * Cancel * Checkin * Checkout * Room move * Update.	–

Introduction

This document describes the public HTTP API of VConnect for receiving and sending messages (events and commands) from and to IPTV system that needs to integrate with PMS, Door Lock Systems or other third party systems supported by VConnect. In this case, for this scope,

The categories of messages that can be with the IPTV are the following:

• From VConnect to IPTV
  • Reservation events: VConnect can send to the IPTV an event a reservation is updated. On creation, cancellation, update, check-in, room move, stays dates changes and check-out. IPTV can use this information to control in-room energy consumption and temperature, etc.
• From IPTV to VConnect
  • –

VConnect supports two types of messages, Commands and Events (The communication between IPTV Systems and VConnect will use only Event messages). Below we describe what an event and a command are:

• Command: message generated by a System (S1), which passes through VConnect and has to be executed by another System (S2) and S1 waits for the result of the execution of S2. For example, an order to read a key card, arrives from a PMS, passes through VConnect, waits for the response from the Door Lock System and returns the result. Every command has a response.
• Event: message generated by a System (S1), which is delivered to VConnect and only waits for the ACK of that delivery. After responding with ACK, VConnect does whatever it has to do with it. By default, VConnect sends the event to all Systems that support receiving it.

IPTV <–> VConnect communication protocol

The diagram below describes the communication flows to and from the IPTV System. (In this case, it will be necessary to implement only “VConenct public api -> external system (IPTV)” flows):

From VConnect to IPTV system

• Communcation flow used by VConnect to send events and commands generated by other hotel systems to the IPTV. IPTV system will process an use the information received.
• IPTV acts as an HTTP server and the VConnect acts as an HTTP client sending messages to the server.
• The communication protocol is HTTPS with HTTP Basic authentication. Requests will be sent using HTTP POST Requests.
• The IPTV system must provide an endpoint to which VConnect will send events.

It must provide a BASE URL from which VConnect will use two endpoints, one to send Events and another one to send Commands:

POST [BASE_URL]/event
POST [BASE_URL]/command

Message Flow

The communication From IPTV to VConnect and From VConnect to IPTV will follow this flow.

• HTTP client -> HTTP server: sends POST request (to command or event url) + json payload body
• Response from HTTP server to HTTP client:
  • HTTP response CODE: will indicate the result at the HTTP link level: 200 OK (received), 404 unauthorized, etc.
  • If HTTP code 200, the response BODY will include a json with information about the processing of the message:
    • For event messages: the response body indicates the result of processing message by the receiver. VConnect response only indicates if there is any error in processing the received json, it will not indicate the result of sending that data to other systems.
    • For commands: will return the result of executing the command.

Request Payload

All messages (events and commands) will send a json containing:

• Identifying part (id, group, action, etc.)
• Payload: Dependent on the type of action being processed.

Name	Type	Description	Notes
action	string	See list below	[required]
payload	json request structure	Content will depend on each event/command.	[optional or required depending on type of message]
id	string	Unique Id to identify each request. It will be used in responses and to help tracing of requests for support purposes. VConnect will always send a unique ID in its request to other systems. It is not required for other systems to include this field in their requests to VConnect. VConnect will generate an unique ID if receives a request without it.	[optiontal]
stamp	YYYY-MM-ddTHH:mm:ssZ	Date time of the external system. It can be useful when dealing with supporte requests in order to look for specific logs in external system time.	[optiontal]

Response Payload

All responses (to events and commands) will include a json containing:

• Common part with result, identifiers, etc. (code, description, id, etc.)
• Payload: Dependent on the type of action being processed.

Name	Type	Description	Notes
code	string	Result code. “0”: OK, “1xx” error that requires retry (range 100-125), “2xx” non-recoverable error on retry (range 200-225)	[required]
payload	json response struct	Content will depend on each event/command	[optional/required depending on type of message]
description	string	Message with technical description in case of error	[recommended]
end_user_message	string	Message to be shown to end users. This is useful mainly for commands. For example, if a PMS sends a keycard.command.createKey. EndUserMsg will include a message to be shown to end user in the PMS UI.	[optional]
request_id	string	ID from the request message. VConnect will include this field when acting as server in order to help tracing at requester’s logs. VConnect does not require order systems to include this field in their responses.	[optional]
id	string	Unique ID for this response message. VConnect will include this ID in their responses. VConnect does not require order systems to include this field in their responses.	[optional]
action	string	Type of event/command of the original request.	[optional]
stamp	YYYY-MM-ddTHH:mm:ssZ	Date time of the external system. It can be useful when dealing with supporte requests in order to look for specific logs in external system time.	[optional]

List of result codes

Code	Description
0	OK
1xx	Event/command not accepted, retry later. To be used if the receiver had some kind of internal problem that requires the sender to keep the message in queue and send it again later.
201	event/command not accepted, don’t retry later.

List of actions by group/category

Reservation

The IPTV System can choose one of these options to receive information about reservations:

1. Receive ONLY reservation.event.info messages: in this case it will receive current values for all reservation attributes when any of the values is updated.
2. Receive diferent reservation events based on the operation that has been done in the PMS (create, cancel, checkin, checkout, room move or information update).

Action	Description	From VConnect to IPTV	From IPTV to VConnect
OPTION 1 Receive current values for all reservation attributes when any of the values is changed.
reservation.event.info	Message with current information about a reservation sent when any change occurs to the reservation.	mandatory	no
OPTION 2 Specific Events based on the operation that has been done in the PMS
reservation.event.create	Sent when a new reservation is created	mandatory	no
reservation.event.cancel	Sent when the reservation status is changed to “cancelled”	mandatory	no
reservation.event.checkin	Sent when the reservation status changes from “expected” to “checkedin”	mandatory	no
reservation.event.checkout	Sent when the reservation status changes from “checkedin” to “checkedout”	mandatory	no
reservation.event.room_move	Sent when a reservation with status “checkedin” has a room change.	mandatory	no
reservation.event.update	Sent when any reservation information changes. It is not sent if the change has generated a checkin, checkout,cancel or room move event.	mandatory	no

VConnect can be configured to send any combination of events desired by the IPTV.

reservation.event.info

When using OPTION 1 (only reservation.even.info messages), VConnect will send this message with current information about the reservation when any of these changes are done in the PMS:

— pre check-in — (not supported with all PMS systems)

• Create a reservation.
• Update information in an existing reservation.
• Cancel an existing reservation.

— during stay —

• Check-in of a reservation.
• Check-out of a reservation.
• Change room of a reservation (room move)
• Change stay dates of a reservation
• Change in any other information of a reservation. Guests information, notes, etc.

reservation.event.* payload

All reservation.event messages will include a payload with the current value for all reservation’s attributes.

The payload MUST include at least this information required for most integrated systems:

• “reservation_id”: reservation ID
• “status”: current reservation status. Possible values: “expected”|”canceled”|”checkedin”|”checkedout”|”noshow”
• “arrival”: arrival date and time
• “departure”: departure date and time
• “room”: current room. Only mandatory if status=”checkedin”
• “guest_firstname”.
• “guest_lastname”.
• “guest_language”.

The payload can include additional details that could be required or interesting for integrations with other systems (it will depend on the information provided by each PMS system).

reservation.event.info example:

{
    "id": "123e4567-e89b-12d3-a456-426614174003",
    "stamp": "2025-02-09T12:34:56Z",
    "action": "reservation.event.info",
    "payload": {
        "reservation_id": "reservation-id",
        "confirmation_id": "comfirmation-id",
        "status": "checkedin",
        "room": "103",
        "arrival": "2025-02-09T12:34:56Z",
        "departure": "2025-06-10T12:34:56Z",
        "pax": 2,
        "children": 1,
        "cos_pbx": "calls_allowed",
        "cos_tv": "tv_allowed",
        "cos_inet": "inet_allowed",
        "booking_guests": [
            {
                "guest_id": "guest-id",
                "guest_main": true,
                "guest_adult": true,
                "guest_title": "Mr.",
                "guest_firstname": "John",
                "guest_lastname": "Doe",
                "guest_language": "en",
                "guest_birth_date": "1980-01-01",
                "guest_email": "john.doe@example.com",
                "guest_phone": "+1234567890",
                "guest_allow_contact": true,
                "guest_passport": "passport-id",
                "guest_identity_card": "id-card",
                "guest_address": "123 Main St",
                "guest_city": "Anytown",
                "guest_postal_code": "12345",
                "guest_state": "CA",
                "guest_country": "US"
            }
        ],
        "notes_stay": "coming with two kids",
        "notes_preferences": "king size bed, please",
        "origin": "Spain",
        "agency": "Booking",
        "rate_plan": "AI"
    }
}

You can see detailed json examples in the the Postman Collection that VConnect technicians will provide.

Postman VConnect API and Sandbox access