Reservation Service

Overview

The Reservation Service serves as the primary mechanism for the Push Integration of successful booking transactions. This integration represents the proactive synchronization flow where the PMS sends reservation data, including guest profiles, room assignments, and financial ledgers directly to external systems.

Request Specification

API Specification

• HTTP Method: POST
• Secure URL Path: {{external_base_url}}/api/reservation

Request Headers

• x-api-key : {{api_key}} Authorization token assigned to the connecting system. The API key is provided by GuestPro.
• Content-Type : application/json Explicitly defines the payload structure.

Payload Construction and Schema Definition

Primary Request Body

The root object contains the administrative and source metadata for the booking.

Field	Type	Required	Description	Example
company	object	Yes	Company information object (see below).	{...}
reservation_id	string	Yes	Unique reference ID for idempotency check.	8f708bc0-ebef-11f0-4d69ad00abaf
reservation_no	string	Yes	Human-readable reservation reference number.	jiwa-013738
reservation_date	string (date)	Yes	Reservation creation/business date in YYYY-MM-DD.	2026-01-07
reservation_group_id	string | null	No	Reservation group ID (if any).	null
agent_id	string	Yes	Booking agent/channel identifier.	2e5e-11ed-add0-350a581b5547
agent_name	string	Yes	Booking agent/channel display name.	Booking.com Pay at Agent 2
segment_code	string | null	No	Segment code (if any).	null
source	string	Yes	Booking source.	Online Travel Agent
payment_type	string	Yes	Payment methodology.	Channel Collect
total_of_room	number	Yes	Total rooms in this reservation.	1
booking_status	string	Yes	Current lifecycle state: NEW, MODIFY, or CANCELLED.	NEW
currencycode	string	Yes	3-letter ISO currency code.	IDR
created_at	string (datetime)	Yes	Creation timestamp (ISO-8601).	2026-01-08T01:37:38+08:00
updated_at	string (datetime)	Yes	Last update timestamp (ISO-8601).	2026-02-19T15:50:26+08:00
reservation_detail	array of object	Yes	List of room details and nightly rate breakdowns.	[{...}]
guest_profile	object	Yes	Guest contact information object.	{...}
payment	array	Yes	List of payments (may be empty).	[]

Company Object (company)

The company object identifies the property and its associated Revenue Management System (RMS) configuration. It is positioned at the top of the request body.

Field	Type	Required	Description	Example
id	string	Yes	Company ID from the PMS.	e6d64880-65a4-11ea-bf47
code	string	Yes	Company code from the PMS.	xxx_code_company
rms	object	Yes	Object for the 3rd party Revenue Management System.	{...}

RMS Object (company.rms)

Field	Type	Required	Description	Example
rms_key	string	Yes	Secret key for each 3rd party RMS.	key_rms
rms_code	string	Yes	Company code from the 3rd party RMS.	rms_company
use_rms	number	Yes	RMS usage flag (1 = enabled, 0 = disabled).	1

Reservation Detail Objects (reservation_detail)

Field	Type	Required	Description	Example
id	string	Yes	Reservation detail ID.	8fa96730-ebef-11f0-a33e
folio_no	number	Yes	Folio number.	33867
room_type_id	string	Yes	Room type ID (mapped identifier).	11ec-b26a-03aaaae40eb2
room_type_name	string	Yes	Room type name.	Premier Room Rice Field View
room_name	string	Yes	Room label/number.	101
booking_status	string	Yes	Booking status at room level.	NEW
reservation_status	string	Yes	Reservation status.	WAITING_LIST, TENTATIVE, DEFINITE, NO_SHOW, CHECK_IN, CHECK_OUT, CANCELLED
adult	number	Yes	Adult count.	2
child	number	Yes	Child count.	0
infra	number	No	Infant count.	0
rate_id	string	Yes	Rate ID.	0af63f80-4f1c6ca09b1e
arrival_date	string (date)	Yes	Check-in date in YYYY-MM-DD.	2026-03-17
departure_date	string (date)	Yes	Check-out date in YYYY-MM-DD.	2026-03-21
arrival_time	string	No	Arrival time (PMS-defined format).	00:00
departure_time	string	No	Departure time (PMS-defined format).	00:00
remark	string	No	Detail remark/notes (can be long).	smoking preference :: Non-Smoking
special_request	string	No	Special request (may contain HTML).	<p><strong>DOUBLE BED</strong></p>
total_room_rates	number	Yes	Total room charge amount.	4240743
total_include_product	number	No	Total included products/add-ons.	1000000
total_extra_charge	number	No	Total extra charge amount.	0
total_taxes_rates	number	No	Total taxes for room rates.	357323.36
total_service_rates	number	No	Total service for room rates.	324839.42
total_taxes_extra_charge	number	No	Total taxes for extra charges.	0
total_service_extra_charge	number	No	Total service for extra charges.	0
total_commission	number	No	Total commission amount.	1310186
nights	number	Yes	Number of nights.	4
open_availability	number	No	Open availability flag.	0
open_availability_start_date	string | null	No	Open availability start date.	null
open_availability_end_date	string | null	No	Open availability end date.	null
main_folio	string	Yes	Main folio ID.	8fa97320-1f90196e41ae
real_departure_date	string (date)	Yes	Actual departure date.	2026-03-21
reservation_folio	object	Yes	Folio summary (total payment/POS).	{...}
rates	array of object	Yes	Nightly breakdown.	[{...}]

Reservation Folio Object (reservation_folio)

Field	Type	Required	Description	Example
id	string	Yes	Folio ID.	8fa97320-1f90196e41ae
folio_no	number	Yes	Folio number.	33867
total_payment	number	Yes	Total payments.	0
total_pos	number	Yes	Total POS.	0

Rates Object (rates)

Field	Type	Required	Description	Example
id	string	Yes	Rate line ID (per night).	8fadad50-ebef-11f0-86c5
amount	number	Yes	Amount (gross per PMS definition).	1020483
dates	string (date)	Yes	Rate date in YYYY-MM-DD.	2026-03-17
name	string	No	Rate plan name.	RBF - A'LA CARTE
room_type_id	string	No	Room type ID for this rate line.	11ec-b26a-03aaaae40eb2
rates_id	string	No	Rate plan/rate mapping ID.	0af63f80-4f1c6ca09b1e
room_id	string	No	Room ID.	9f4fe000-0000-0000-0000
net_rates	number	No	Net rate.	1020483
taxes_amount	number	No	Taxes per night.	63896.56
service_amount	number	No	Service per night.	58087.78
commission_amount	number	No	Commission per night.	317620.81
total_pos	number	No	POS total for this night.	0
total_pos_taxes	number	No	POS taxes.	0
reservation_rates_type	string	No	Rate type (e.g., ROOM_CHARGE).	ROOM_CHARGE
remark	string	No	Rate line remark (e.g., Room Charge).	Room Charge
adult	number	No	Adult count for this rate line.	2
child	number	No	Child count for this rate line.	0
is_virtual_room	number	No	Virtual room flag (0/1).	0

Guest Profile Object (guest_profile)

Field	Type	Required	Description	Example
id	string	Yes	Guest profile ID.	8f70e7e0-ebef-11f0-bfdc
address	string | null	No	Address.	null
phone	string	Yes	Phone number.	+48 724
email	string	Yes	Email address.	jtolwi@guest.com
countrycode	string	Yes	Country code.	and
first_name	string	Yes	First name.	Ja
last_name	string	Yes	Last name.	Tski
city	string	No	City.	null
zipcode	string	No	Zip/postal code.	null

Expected System Responses

Successful Execution

The external system must respond with an HTTP 200 OK or 201 Created.

{
  "status": "success",
  "message": "Reservation b3b24f0b-179b-4e9a-afa4-e3a1ef882a48 has been successfully ingested."
}

Failure Execution

When the external system provides a response other than success codes (200, 201), the external system delivers the following error response structure.

{
  "status": "error",
  "message": "<<error_detail>>"
}

Full Request Body

{
  "company": {
    "id": "e6d64880-65a4-11ea-bf47",
    "code": "xxx_code_company",
    "rms": {
      "rms_key": "key_rms",
      "rms_code": "rms_company",
      "use_rms": 1
    }
  },
  "reservation_id": "8f708bc0-ebef-11f0-4d69ad00abaf",
  "reservation_no": "jiwa-013738",
  "reservation_date": "2026-01-07",
  "agent_id": "2e5e-11ed-add0-350a581b5547",
  "reservation_group_id": null,
  "segment_code": null,
  "agent_name": "Booking.com Pay at Agent 2",
  "source": "Online Travel Agent",
  "payment_type": "Channel Collect",
  "total_of_room": 1,
  "booking_status": "NEW",
  "created_at": "2026-01-08T01:37:38+08:00",
  "updated_at": "2026-02-19T15:50:26+08:00",
  "currencycode": "IDR",
  "reservation_detail": [
    {
      "id": "8fa96730-ebef-11f0-a33e",
      "folio_no": 33867,
      "room_type_id": "11ec-b26a-03aaaae40eb2",
      "room_type_name": "Premier Room Rice Field View",
      "room_name": "101",
      "booking_status": "NEW",
      "reservation_status": "DEFINITE",
      "adult": 2,
      "child": 0,
      "infra": 0,
      "rate_id": "0af63f80-4f1c6ca09b1e",
      "arrival_date": "2026-03-17",
      "departure_date": "2026-03-21",
      "arrival_time": "00:00",
      "departure_time": "00:00",
      "remark": "smoking preference :: Non-Smoking | genius_rate : yes",
      "special_request": "<p><strong>DOUBLE BED</strong></p>",
      "total_room_rates": 4240743,
      "total_include_product": 1000000,
      "total_extra_charge": 0,
      "total_taxes_rates": 357323.36,
      "total_service_rates": 324839.42,
      "total_commission": 1310186,
      "nights": 4,
      "open_availability": 0,
      "main_folio": "8fa97320-1f90196e41ae",
      "real_departure_date": "2026-03-21",
      "reservation_folio": {
        "id": "8fa97320-1f90196e41ae",
        "folio_no": 33867,
        "total_payment": 0,
        "total_pos": 0
      },
      "rates": [
        {
          "id": "8fadad50-ebef-11f0-86c5",
          "amount": 1020483,
          "dates": "2026-03-17",
          "name": "RBF - A'LA CARTE",
          "net_rates": 1020483,
          "taxes_amount": 63896.56,
          "service_amount": 58087.78,
          "commission_amount": 317620.81,
          "reservation_rates_type": "ROOM_CHARGE",
          "adult": 2,
          "child": 0
        },
        {
          "id": "8fd1c570-ebef-11f0-b717",
          "amount": 1073420,
          "dates": "2026-03-18",
          "taxes_amount": 67505.9,
          "service_amount": 61369.0
        }
      ]
    }
  ],
  "guest_profile": {
    "id": "8f70e7e0-ebef-11f0-bfdc",
    "phone": "+48 724",
    "email": "jtolwi@guest.com",
    "countrycode": "and",
    "first_name": "Ja",
    "last_name": "Tski"
  },
  "payment": []
}