GRMS API 1

Version – 23/07/2025.

Scope

This API enables sending and receiving the following information between VConnect and the GRMS system:

	VConnect -> GRMS System	GRMS System -> VConnect
Reservation information	* Create * Cancel * Checkin * Checkout * Room move * Update.	–
Room information	* DND (optional) * MUR (optional) * RS (optional) * Presence (optional – available soon).	* DND (optional) * MUR (optional) * RS (optional) * Presence (optional – available soon).

Introduction

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

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

• From VConnect to GRMS
  • Reservation events (optional): VConnect can send to the GRMS an event a reservation is updated. On creation, cancellation, update, check-in, room move, stays dates changes and check-out. GRMS can use this information to control in-room energy consumption and temperature, etc.
  • Room events related to Guests “requests” (optional): VConnect can send to the GRMS events to report guest’s requests like “Do Not Disturb” or “Make Up Room”. These requests can be received from the PMS, a Guest APP, etc., and can be used by the GRMS to update in-room sensors/indicators.
• From GRMS to VConnect
  • Room events related to Guests “requests” (optional): GRMS cand send to VConnect events to report guest’s requests like “Do Not Disturb” or “Make Up Room”. VConnect will send these events to other systems like PMS, Housekeeping Apps,etc.
  • Room events related to information gathered by in-room sensors and buttons (optional): GRMS cand send to VConnect events detected by in-room sensors to report information like Person In Room, low battery levels, etc. VConnect will send these events to other systems like PMS, Housekeeping Apps, Preventive Maintenance Apps, etc.

VConnect supports two types of messages, Commands and Events (The communication between GRMS 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.

GRMS <–> VConnect communication protocol

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

From GRMS system to VConnect

• Communication flow used by the GRMS 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 GRMS 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 GRMS 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 GRMS system

• Communcation flow used by VConnect to send events and commands generated by other hotel systems to the GRMS. GRMS system will process an use the information received.
• GRMS 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 GRMS 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 GRMS to VConnect and From VConnect to GRMS 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 GRMS 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 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.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 GRMS.

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”

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.

Room

The GRMS 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.info payload

All room.event.* messages MUST include at least these attributes:

• “room”: room number

All other fields are optional.

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

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
    }
}

Postman VConnect API and Sandbox access