Push & Pull Reservation Documentation

Architecture Diagram

The following is a visualization of the system workflow integration between Booking.com, API Service, Database, and Channel Manager (CM):

Component	Description
Service	OTA Integration (Booking.com)
Method Path	Push (Real-Time) & Pull (Scheduled)
Primary Repositories	ota (Processors), ota-cron (Schedulers)

---

Table of Contents

• 1. Integration Architecture
• 2. Main File Summary
• 3. Database Table Operations
• 4. Special Logic: Partial Cancellation
• 5. complete_invoice Endpoint

---

1. Integration Architecture

This system is designed with two primary paths operating symbiotically to ensure high data accuracy.

A. Push Path (Real-Time)

Used to process reservations immediately after a guest completes a booking.

• Primary File: recieve_booking_resa.php
• Location: Branch ota -> ota/ota_update/bookings/reservation
• Function: Acts as a listener or webhook for instant notifications.

B. Pull Path (Scheduled/Sync)

Functions as a fail-safe mechanism to retrieve missed data or perform bulk synchronizations.

• Executor File: booking_pull_reservation_cron_new.php (Repo: ota-cron)
• Processor File: recieve_pull_booking_resa.php (Repo: ota, Folder: ota/ota_update/bookings/reservation)
• Function: Fetches data periodically via cron jobs.

---

2. Main File Summary

File Name	Repository	Method	Primary Function
recieve_booking_resa.php	ota	PUSH	Acts as a passive webhook listener that catches real-time automatic notifications from Booking.com for new, modified, or cancelled bookings.
recieve_pull_booking_resa.php	ota	PULL	Processes raw XML data received from active syncs; contains specialized logic to detect Partial Cancellations by comparing incoming room data with existing database records.
booking_pull_reservation_cron_new.php	ota-cron	PULL	The main cron executor that triggers automated background tasks to fetch unstayed reservations from the Booking.com API.
bookingsFutureResv_xml.php	ota	PULL	Executes the manual or bulk "Pull Reservations Summary" feature to retrieve all unstayed reservations for a specific property to ensure database synchronization.

---

3. Database Table Operations

A. Main Reservation Tables

• Bookings
  • Action: INSERT / UPDATE
  • Data: Basic info (Guest name, check-in/out dates, status, total price).
• booking_all_tags
  • Action: INSERT / UPDATE
  • Data: Technical metadata, OTA commission, and XML details per room.

B. Logs & Metadata

• ota_RespLog: Raw XML response history for internal auditing.
• ota_taxes: Details on taxes and additional fees.
• external_status: Locking mechanism to prevent duplicate cron executions.
• booking_mail_log_v2: Notification email queue for hotels.

---

4. Special Logic: Partial Cancellation Detection

A critical feature within recieve_pull_booking_resa.php for handling the cancellation of specific rooms within a single multi-room order.

1. Comparison: The system compares the ota_room_id from the latest XML payload against the data stored in the Bookings table.
2. Identification: If a previously existing room ID is missing from the new XML payload, the system detects a cancellation.
3. Execution: The specific room status is updated to cancel in the database.
4. Inventory Update: Triggers an inventory update to the Channel Manager (CM) via the complete_invoice endpoint.

---

5. complete_invoice Endpoint

The crucial component for data synchronization after a reservation is processed.

5.1 Location & URL Structure

The endpoint is constructed dynamically:

• Base URL: Retreived from $this->utlFunc->envValue['PMS_BASE_URL']
• Path: index.php/bookingbutton/complete_invoice

5.2 Query Parameters

Parameter	Description	Format
checkin / checkout	Stay dates	dmy
roomid:rateid	Room ID & Rate Plan ID	ID:ID
propertycode	Property/Hotel ID	String
action	Inventory instruction	increment (cancel) / decrement (new)
bookingrowid	Unique Row ID from Bookings table	Integer
token	Security & Identification	String (Unique)

5.3 Implementation Example (PHP)

$siteURL = $this->utlFunc->envValue['PMS_BASE_URL'] . 
           'index.php/bookingbutton/complete_invoice?' . 
           'checkin=' . $checkin_date . 
           '&checkout=' . $checkout_date . 
           '&roomid:rateid=' . $room_id . ':' . $rateplan_id . 
           '&propertycode=' . $this->propertyId . 
           '&action=increment' . // or decrement
           '&bookingrowid=' . $id . 
           '&token=' . $id . '_' . uniqid();