PUBLIC API

Version – 23/07/2025.

Scope

• Explicación funcional
• Bla, bla, bla…

Introduction

This document describes the public HTTP API of VConnect for sending and receiving messages (events and commands) from external systems, both PMS and other types of hotel systems.

The categories of messages supported by this connector are:

• Reservation
• Room
• Wake
• Call
• Charge
• Keycard

VConnect supports two types of messages, Commands and Events. Below we describe what an event and a command are:

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.

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.

External system <–> VConnect communication protocol

The diagram below describes the communication flows to and from the External System.

From External System to VConnect

• Communication flow used by the External System to send events to VConnect. VConnect will process the events, and will distribute them to other hotel systems (PMSs, etc).
• VConnect public API acts as an HTTP server and the External System 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 message is encoded as “application/json”.
• VConnect technicians will provide URLs and Authentication values to be used by the External System.
• VConnect provides unique endpoints for each external system of a subscription. If a single subscription/hotel has two external systems of the same type, different endpoints will be provided for each of the external systems.

There will be one endpoint for commands and another for events:

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

The base URL for all public endpoints will be:

https://api.vconnect.vingcard.com/publicapi/v1/{{chainId}}/{{hotelId}}/{{**connector.id** }}

• chainId and hotelId can be decided by char or by the external system. By default, if not defined, they will be “nochid” and “nohid”.
• connector.id : unique ID for each connection with an external system. It will be automatically assigned by VConnect.

From VConnect to External System

• Communcation flow used by VConnect to send events and commands generated by other hotel systems to the External System. External System will process an use the information received.
• External System 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 External System must provide endpoints to which VConnect will send commands and 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]/command
POST [BASE_URL]/event

Message Flow

The communication From External System to VConnect and From VConnect to External System 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.

INTERNAL NOTE: list of error codes must be updated with errors defined at: https://gitlab.hmobile.systems/vconnect/vcconnectutil/-/blob/develop/errors/errors.go?ref_type=heads

List of actions by group/category

Reservation

An external system can choose one of these options to receive information about reservations:

1. Receive (send in the case of PMS) 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 (send in the case of PMS) 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 GRMS	From GRMS 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.	optional	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	optional	no
reservation.event.cancel	Sent when the reservation status is changed to “cancelled”	optional	no
reservation.event.checkin	Sent when the reservation status changes from “expected” to “checkedin”	optional	no
reservation.event.checkout	Sent when the reservation status changes from “checkedin” to “checkedout”	optional	no
reservation.event.room_move	Sent when a reservation with status “checkedin” has a room change.	optional	no
reservation.event.noshow	Sent when the reservation status is changed to “noshow”	optional	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.	optional	no

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

reservation.event.info

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

— 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 meesages will include a payload with complete reservation’s current information.

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”

The payload can include additional details that could be required or interesting for integrations with other systems.

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.

Room

The external system can choose one of these options to send and/or receive information about in-room buttons and sensors:

1. Receive/send ONLY room.event.info messages: in this case it will receive or send current values for all room attributes when any of the values is updated.
2. Receive/send diferent reservation events based on the sensor/button which status has changed.

Action	Description	From VConnect to GRMS	From GRMS to VConnect
OPTION 1 Receive current values for all reservation attributes when any of the values is changed.
reservation.event.info	AVAILABLE SOON It includes all current information for a room. Sent when any of the room value changes.	optional	optional
OPTION 2 Specific Events based on the operation that has been done in the PMS
room.event.dnd	Report a change in the Do Not Disturb status of a room	optional	optional
room.event.mur	Report a change in the Make Up Room status of a room.	optional	optional
room.event.rs	Report a change in the Cleaning/Housekiping Status of a room.	optional	optional
room.event.presence	AVAILABLE SOON Report a change in the Person In Room status of a room.	optional	optional

room.event.dnd payload

{
    "id": "string",
    "stamp": "YYYY-MM-ddTHH:mm:ssZ",
    "action": "room.event.dnd",
    "payload": {
        "room": "string",
        "property": "string",
        "do_not_disturb": boolean
    }
}

room.event.mur payload

{
    "id": "string",
    "stamp": "YYYY-MM-ddTHH:mm:ssZ",
    "action": "room.event.mur",
    "payload": {
        "room": "string",
        "property": "string",
        "make_up_room": boolean
    }
}

room.event.rs payload

{
    "id": string,
    "stamp": "YYYY-MM-ddTHH:mm:ssZ",
    "action": "room.event.rs",
    "payload": {
        "room": "string",
        "property": "string",
        "hsk_status": "string"
    }    
}

room.event.presence payload

{
    "id": string,
    "stamp": "YYYY-MM-ddTHH:mm:ssZ",
    "action": "room.event.rs",
    "payload": {
        "room": "string",
        "property": "string",
        "presence": boolean
    }
}

Wake

Actions related to wake-up calls. These kind of events are used to order a PBX to setup automatic wake-up calls for a room and to report the PMS or other system when a wake-up call has been executed or has failed.

There are 4 meesages related to wake-up calls. The use of this message may be different depending on the system which is using the integration with VConnect.

CASE1: PMS integration (or any other system that can generate orders to setup wake-up calls)

Action	Description	From PMS to VConnect	From VConnect to PMS
wake.event.set	Reports an order to setup a wake-up call	mandatory if PMS wants to send these orders to other systems	optional: only necessary if PMS wants to be informed of wake-up orders generated by other systems.
wake.event.clear	Reports an order to cancel a wake-up call	mandatory if PMS wants to send these orders to other systems	optional: only necessary if PMS wants to be informed of wake-up cancellation orders generated by other systems.
wake.event.executed	Reports the correct execution of a wake-up call	no	mandatory if PMS wants to receive information about wake-up calls execution
wake.event.fail	Reports the failed execution of a wake-up call	no	mandatory if PMS wants to receive information about wake-up calls execution

CASE2: PBX integration

Action	Description	From PMS to VConnect	From VConnect to PMS
wake.event.set	Reports an order to setup a wake-up call	mandatory	optional: only necessary if it is possible for a guest to request a wake-up call from the room’s telephone. In that case, the PBX can inform of this order to VConnect.
wake.event.clear	Reports an order to cancel a wake-up call	mandatory	no
wake.event.executed	Reports the correct execution of a wake-up call	no	mandatory
wake.event.fail	Reports the failed execution of a wake-up call	no	mandatory

wake.event.* payload (for PMS integration)

All wake.event meesages will include a payload with information about the wake-up call.

field name	type	description	set	clear	executed	fail
date	“YYYY-MM-ddTHH:mm:ssZ”	set/clear: UTC date when the order was generated in the PMS. executed/fail: UTC date when the order was executed by the PBX.	mandatory	mandatory	mandatory	mandatory
room	“string”	room name	mandatory	mandatory	mandatory	mandatory
property	“string”	hotel identifier in the PMS	optional	optional	optional	optional
“wake_date”	“YYYY-MM-ddTHH:mm:ssZ”	set/clear: UTC date and time when wake-up call must be executed. If “Z” is not specified, it will be assumed to be the local date time of the hotel executed/fail: same wake_date received in the original “set” message.	mandatory	mandatory	mandatory	mandatory
“wake_uid”	“string”	set: Wake-up’s Unique ID assigned by the system that orders wake-up creation. If set, it will be used in further messages (clear,executed,fail) related to the same original wake-up set order. If not provided, VConnect will use “room”+”wake_date” as “uid”. clear: ID of the wake-up to be cancelled. executed/fail: ID of the executed wake-up (ony if “uid” was included in the original “set” message).	optional	optional	optional	optional
“user”	“string” [“OPERATOR”/”GUEST”]	Type of user that generated the order. “OPERATOR”: ordered by hotel’s staff.”GUEST”: ordered by guest (some PBX or other systems allow the guest to setup wake-up calls).	optional	optional	no	no

wake.event.* payload (for PBX integration)

All wake.event meesages will include a payload with information about the wake-up call.

field name	type	description	set	clear	executed	fail
date	“YYYY-MM-ddTHH:mm:ssZ”	set/clear: UTC date when the order was generated in the PMS.executed/fail: UTC date when the order was executed by the PBX.	mandatory	mandatory	mandatory	mandatory
room	“string”	room name	mandatory	mandatory	mandatory	mandatory
address	“string”	id for the pbx extension / room terminal. To be used if the PBX does not “understand” the room value and need VConnect to do a “tranlation” between room and address.	optional	optional	optional	optional
property	“string”	hotel identifier in the PBX	optional	optional	optional	optional
“wake_date”	“YYYY-MM-ddTHH:mm:ssZ”	set/clear: UTC date and time when wake-up call must be executed. If “Z” is not specified, it will be assumed to be the local date time of the hotel executed/fail: same wake_date received in the original “set” message.	mandatory	mandatory	mandatory	mandatory
“wake_uid”	“string”	set: Wake-up’s Unique ID assigned by the system that orders wake-up creation. If set, it will be used in further messages (clear,executed,fail) related to the same original wake-up set order. If not provided by the PMS, VConnect will not include it in messages to PBX. clear: ID of the wake-up to be cancelled. executed/fail: ID of the executed wake-up (ony if “uid” was included in the original “set” message).	optional	optional	optional	optional

wake.event.set payload

{
    "id": "string",
    "stamp": "YYYY-MM-ddTHH:mm:ssZ",
    "action": "wake.event.set",
    "payload": {
        "date": "2025-02-09T12:34:56Z",
        "room": "100",
        "wake_date": "2025-02-10T08:00:00Z",
        "wake_uid": "20250209123456",
        "user": "OPERATOR"
    }
}

wake.event.clear payload

{
    "id": "string",
    "stamp": "YYYY-MM-ddTHH:mm:ssZ",
    "action": "wake.event.clear",
    "payload": {
        "date": "2025-02-09T12:34:56Z",
        "room": "100",
        "wake_date": "2025-02-10T08:00:00Z",
        "wake_uid": "20250209123456",
        "user": "OPERATOR"
    }
}

wake.event.executed payload

{
    "id": "string",
    "stamp": "YYYY-MM-ddTHH:mm:ssZ",
    "action": "wake.event.executed",
    "payload": {
        "date": "2025-02-10T08:01:00Z",
        "room": "100",
        "address": "R100",
        "wake_date": "2025-02-10T08:00:00Z",
        "wake_uid": "20250209123456"
    }
}

wake.event.fail payload

{
    "id": "string",
    "stamp": "YYYY-MM-ddTHH:mm:ssZ",
    "action": "wake.event.fail",
    "payload": {
        "date": "2025-02-10T08:01:00Z",
        "room": "100",
        "address": "R100",
        "wake_date": "2025-02-10T08:00:00Z",
        "wake_uid": "20250209123456"
    }
}

Call

Actions related to phone calls. These kind of events are used to receive from a PBX information about phone calls and to report to the PMS or other system when a phone call has happened and details about the phone call.

There is one meesage related to phone calls. The use of this message may be different depending on the system which is using the integration with VConnect.

CASE1: PBX integration

Action	Description	From VConnect to PBX	From PBX to VConnect
call.event.post	PBX reports information about a phone call	no	mandatory

CASE2: PMS integration (or any other system that wants to receive information about phone calls)

Action	Description	From PMS to VConnect	From VConnect to PMS
call.event.post	VConnect reports information about a phone call processed by a PBX	no	mandatory

call.event.post payload (for PMS integration)

All call.event meesages will include a payload with information about the phone call.

In the table below we will differentiate between two type of integrations with PBX:

• pmslink LEGACY: publicapi used to connect with a PBX throught a legacy pmslink .dll using CONNserver.
• vconnect NATIVE: a new integration with a PBX that connects directly to our publicapi.

field name	type	description	pmslink LEGACY (poner?)	vconnect NATIVE
date	“YYYY-MM-ddTHH:mm:ssZ”	UTC date when the phone call was executed by the PBX.	mandatory	recommended: if not sent by the PBX, VConnect will use current date and time
room	“string”	room name. It can be a guest room or any other location of the hotel.	mandatory	optional: if not sent by the PBX, publicapi will use “address” as room or will apply configured translations from address to room
address	“string”	id for the pbx extension / room terminal. To be used if the PBX does not “understand” the room value and need VConnect to do a “tranlation” between address and room.	optional	mandatory
property	“string”	hotel identifier in the PBX	optional	optional
type	“string”	type of all: “O”: = Outbound: from internal extension to external phone number. “I”: Inbound: from external phone number to internal extension. “L”: Local: from internal extension to internal extension. pmslink 2.5 solo el tipo de llamadas soportadas por el dispositivo PMS>	mandatory	mandatory
caller	“string”	if type=”O” or “L”: extension numberi f type=”I”: caller phone number	mandatory	recommended
called	“string”	if type=”O” or “L”: destination number if type=”I”: extension number receiving the call	mandatory	recommended
duration	“string”	conversation duration as hh:mm:ss	mandatory	mandatory if VConnect has to calculate cost based on duration.
cost	“string”	call cost to be charged	mandatory	no
location_type	INTERNAL CHAR. Type of location for “O” calls. local, provincial, internacional. Calculated by pmslink. Lo calcula pmslink en base a las tarifas. Lo podemos obviar	optional	no
location	INTERNAL CHAR. Location for “O” calls. (country name, etc). Calculated by pmslink. Lo calcula pmslink en base a las tarifas. Lo podemos obviar	optional	no
account	“string”	INTERNAL CHAR. Will not be used with new integrations	optional	no
ringing	“string”	INTERNAL CHAR. Will not be used with new integrations	optional	no

INTERNAL examples

Call from reception “extension/addres 0” to room “address R100 – room 100)

"room": "0",
"address": "0",
"type": "L",
"caller": "0",
"called": "R100",

Call from +34900567567 to room “address R100 – room 100”

"room": "100",
"address": "R100",
"type": "I",
"caller": "900567567",
"called": "R100",

ejemplo json sacado de CONNserver. PENDING prepare example for third party PBX

{
    "id": "$#id#$",
    "stamp": "$#stamp*yyyy"-"mm"-"dd"T"hh": "nn": "ss"Z"ZULU*#$",
    "action": "call.event.post",
    "payload": {
        "date": "$#date*yyyy"-"mm"-"dd"T"hh": "nn": "ss"Z"ZULU*#$",
        "room": "$#room_name#$",
        "address": "$#address#$",
        "property": "$#property#$",
        "type": "$#type#$",
        "line": "$#line#$",
        "caller": "$#caller#$",
        "called": "$#called#$",
        "account": "$#account#$",
        "ringing": "$#ringing*hh": "nn": "ss*#$",
        "duration": "$#duration*hh": "nn": "ss*#$",
        "units": $#units#$,
        "cost": "$#cost#$",
        "net": "$#net#$",
        "total": "$#total#$",
        "location_type": "$#location_type#$",
        "location": "$#location_name#$"
    }
}

call.event.post payload (for PBX integration)

All call.event meesages will include a payload with information about the phone call.

field name	type	description
date	“YYYY-MM-ddTHH:mm:ssZ”	UTC date when the phone call was executed by the PBX.	mandatory
room	“string”	room name. It can be a guest room or any other location of the hotel.	mandatory
address	“string”	id for the pbx extension / room terminal. To be used if the PBX does not “understand” the room value and need VConnect to do a “tranlation” between address and room.	optional
property	“string”	hotel identifier in the PBX	optional
type	“string”	type of all: “O”: = Outbound: from internal extension to external phone number. “I”: Inbound: from external phone number to internal extension. “L”: Local: from internal extension to internal extension.	mandatory
caller	“string”	if type=”O” or “L”: extension number if type=”I”: caller phone number	mandatory
called	“string”	if type=”O” or “L”: destination number if type=”I”: extension number receiving the call	mandatory
duration	“string”	conversation duration as hh:mm:ss	mandatory
cost	“string”	call cost to be charged	mandatory

Charge

PENDING!!!!

Keycard

Action	Description	Notes
keycard.command.createKey	Create a Key. VConnect will order the key system to create the key and return the result to the PMS.	optional
keycard.command.readKey	Read a plastic Key. VConnect will order the key system to read a key and return the result to the PMS.	optional

keycard.command.createKey payload (plastic key card)

This command can be used by the PMS to send and order to create a plastic key card.

VConnect receives the command, sends it to the Door Lock System and returns the result of the execution of the command to the PMS.

The keycard.command.createKey payload MUST include at least this information:

• “key_type”: 2 (this value can change in other cases to create other type of keys like wallets, etc)
• “main”: <true/false> indicates creation of primary (true) or companion key (copy) (false)
• “room”: room.
• “arrival”: arrival date and time
• “departure”: departure date and time
• “card_encoder”: id of the Door Lock System encoder to be used to create the plastic key card.
• “card_encoder_provider”: 100 (this value will only be different if the Hotel is using a printer/encoder from a third party vendor)
• “extra_access”: array of additional allowed accesses. Can be empty.
• “extra_rooms”: array of additional allowed room. Can be empty.
• “reservation_id”: reservation ID from the PMS (only required if the DLS requires. Mandatory for Vostio v10)

keycard.command.createKey example:

{
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "stamp": "2025-02-09T12:34:56Z",
    "action": "keycard.command.createKey",
    "payload": {
        "key_type": 2,
        "main": true,
        "arrival": "2025-02-09T12:34:56Z",
        "departure": "2025-04-09T00:00:01Z",
        "name": "John Doe",
        "extra_rooms": [],
        "extra_access": [],
        "card_encoder_provider": 100,
        "card_encoder": "enc1",
        "cards_qty": 1,
        "reservation_id": "reservation-id2",
        "keytrack1": "track1",
        "keytrack2": "track2",
        "room": "102"
    }
}

keycard.command.createKey response payload with example (ok):

{
    "action": "keycard.command.createKey",
    "code": 0,
    "description": "ok",
    "end_user_message": "",
    "id": "40954fda-ba98-483c-9f46-f5fbf9d057a7",
    "payload": {
        "serialNumbers": [
            "test_serial_number"
        ],
    },
    "request_id": "123e4567-e89b-12d3-a456-426614174000",
    "stamp": "2025-07-01T07:44:00.289095+02:00"
}

keycard.command.createKey response payload with example (DLS returned and error):

{
    "action": "keycard.command.createKey",
    "code": 200,
    "description": "error sending order ReservationUpdate to Vostio: reservation update request returned != 200. Returned: 422 - {ErrorCode:INVALID_REQUEST Message:End date must be a future date Code:0 CausedBy:[]}",
    "end_user_message": "Unexpected error. Contact technical support",
    "id": "47cc29cc-a19d-49b2-805e-474da733ea96",
    "payload": {
    },
    "request_id": "123e4567-e89b-12d3-a456-426614174000",
    "stamp": "2025-07-01T07:35:58.438269+02:00"

}

keycard.command.readKey payload (plastic key card)

This command can be used by the PMS to send and order to read the information from a plastic key card.

VConnect receives the command, sends it to the Door Lock System and returns the result of the execution of the command to the PMS.

The keycard.command.readKey payload MUST include at least this information:

• “key_type”: 2
• “card_encoder”: id of rhe encoder in the Door Lock System to be used to read the plastic key card.
• “card_encoder_provider”: 100 (this value will only be different if the Hotel is using a printer/encoder from a third party vendor)

{
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "stamp": "2025-02-09T12:34:56Z",
    "action": "keycard.command.readKey",
    "payload": {
        "key_type":2,
        "card_encoder_provider":100,
        "card_encoder":"enc1"
    }
}

keycard.command.readKey response payload example (ok)

{
    "action": "keycard.command.readKey",
    "code": 0,
    "description": "ok",
    "end_user_message": "Key successfully read",
    "id": "6deb006d-c589-4eea-9485-d923df756b20",
    "payload": {
        "createdAt": "2025-06-30T07:47:56.657099+02:00",
        "createdAtUtc": "2025-06-30T05:47:56.657098Z",
        "doors": [
            {
                "code": 0,
                "description": "",
                "id": 0,
                "name": "test_door_name",
                "pms_id": "",
                "type": "test_door_type"
            }
        ],
        "id": "test_id",
        "media_card_uid": "test_card_uid",
        "validFrom": "2025-06-30T07:47:56.657098+02:00",
        "validFromUtc": "2025-06-30T05:47:56.657098Z",
        "validTo": "2025-07-02T07:47:56.657098+02:00",
        "validToUtc": "2025-07-02T05:47:56.657097Z"
    },
    "request_id": "123e4567-e89b-12d3-a456-426614174000",
    "stamp": "2025-07-01T07:47:56.6571+02:00"
}

Postman VConnect API and Sandbox access

Our Integrations Team will provide you with:

1. A Postman collection with detailed examples of events and commands following the VConnect API protocol.
2. A VConnect Sandbox environment and a Postman Environment file with information to use it.