Booking API Specification¶

Overview¶

The Booking API provides endpoints for creating, confirming, reading, and managing travel bookings.

Base Path: /booking

Content Types: - Request: application/json - Response: application/json

Response Format¶

All endpoints return a TlinqApiResponse object:

{
  "apiStatus": {
    "errorCode": "OK",
    "errorMessage": "Success"
  },
  "apiData": { ... }
}

Date Format: All dates are returned in ISO 8601 format (yyyy-MM-dd'T'HH:mm:ss)

Endpoints¶

POST /booking/create¶

Creates a new booking from an existing sales order.

Request Body: | Field | Type | Required | Description | |-------|------|----------|-------------| | session | string | Yes | User session token | | orderNum | string | Yes | Sales order number to create booking from |

Request Example:

{
  "session": "user-session-token",
  "orderNum": "SO-2025-001234"
}

Response Structure:

{
  "apiStatus": { "errorCode": "OK", "errorMessage": "Success" },
  "apiData": {
    "bookingrequestid": 12345,
    "refnum": "BK-2025-001234",
    "rqdate": "2025-06-15T10:30:00",
    "reqstatus": "PENDING",
    "orderNum": "SO-2025-001234",
    "rqmoddate": "2025-06-15T10:30:00",
    "customerid": 5678,
    "accessCode": "ABC123XYZ",
    "accessMaxDate": "2025-07-15T23:59:59",
    "orderDate": "2025-06-15T10:00:00",
    "invoiceNum": "INV-2025-001234",
    "amount": 1500.00
  }
}

Error Codes: - MISSING_PARAMETER - Session ID or order number not provided

POST /booking/confirm¶

Confirms an existing booking request.

Request Body: | Field | Type | Required | Description | |-------|------|----------|-------------| | session | string | Yes | User session token | | requestId | integer | Yes | Booking request ID to confirm | | mobilePhone | string | No | Mobile phone for booking confirmation notification |

Request Example:

{
  "session": "user-session-token",
  "requestId": 12345,
  "mobilePhone": "+971501234567"
}

Response Structure:

href="#__codelineno-4-1">{ "apiStatus": { "errorCode": "OK", "errorMessage": "Success" }, "apiData": { "requestId": 12345, "referenceNumber": "BK-2025-001234", "completeResult": "OK", "completeMessage": "Completely successful", "accessCode": "ABC123XYZ", "ticketingResults": [ { "result": "OK", "statusCode": "CONFIRMED", "statusMessage": "Ticket confirmed successfully" }, { "result": "OK", "statusCode": "CONFIRMED", "statusMessage": "Hotel booking confirmed" } ] } }

Possible completeResult values: - OK - All items confirmed successfully - PARTIAL - Some items confirmed, some failed - FAILED - All items failed to confirm

Error Codes: - MISSING_PARAMETER - Session ID or request ID not provided

POST /booking/read¶

Retrieves booking details by email and reference number.

Request Body: | Field | Type | Required | Description | |-------|------|----------|-------------| | session | string | Yes | User session token | | email | string | Yes | Customer email address | | refnum | string | Yes | Booking reference number |

Request Example:

{
  "session": "user-session-token",
  "email": "customer@example.com",
  "refnum": "BK-2025-001234"
}

Response Structure:

{
  "apiStatus": { "errorCode": "OK", "errorMessage": "Success" },
  "apiData": [
    {
      "bookingReference": "BK-2025-001234",
      "bookingRequestId": 12345,
      "bookingRequestDate": "2025-06-15T10:30:00",
      "bookingRequestStatus": "CONFIRMED",
      "ticketingRequestStatus": "COMPLETED",
      "ticketingRequestId": 67890,
      "ticketingRequestResult": "OK",
      "ticketingRequestErrorCode": null,
      "ticketingRequestErrorMessage": null,
      "ticketItemId": 11111,
      "paxCount": "2",
      "unitId": 100,
      "unitName": "Desert Safari Tour",
      "itemDescription": "Premium Desert Safari with BBQ Dinner",
      "supplierBookingId": 99999,
      "isConfirmed": true
    }
  ]
}

POST /booking/readall¶

Retrieves all bookings for the current logged-in user.

Request Body: | Field | Type | Required | Description | |-------|------|----------|-------------| | session | string | Yes | User session token | | status | string | No | Filter by booking status (PENDING, CONFIRMED, CANCELLED) |

Request Example:

{
  "session": "user-session-token",
  "status": "CONFIRMED"
}

Response Structure:

{
  "apiStatus": { "errorCode": "OK", "errorMessage": "Success" },
  "apiData": [
    {
      "bookingrequestid": 12345,
      "refnum": "BK-2025-001234",
      "rqdate": "2025-06-15T10:30:00",
      "reqstatus": "CONFIRMED",
      "orderNum": "SO-2025-001234",
      "rqmoddate": "2025-06-16T14:20:00",
      "customerid": 5678,
      "accessCode": "ABC123XYZ",
      "accessMaxDate": "2025-07-15T23:59:59",
      "orderDate": "2025-06-15T10:00:00",
      "invoiceNum": "INV-2025-001234",
      "amount": 1500.00
    },
    {
      "bookingrequestid": 12346,
      "refnum": "BK-2025-001235",
      "rqdate": "2025-06-20T09:15:00",
      "reqstatus": "CONFIRMED",
      "orderNum": "SO-2025-001235",
      "rqmoddate": "2025-06-20T09:15:00",
      "customerid": 5678,
      "accessCode": "DEF456UVW",
      "accessMaxDate": "2025-07-20T23:59:59",
      "orderDate": "2025-06-20T09:00:00",
      "invoiceNum": "INV-2025-001235",
      "amount": 2500.00
    }
  ]
}

POST /booking/verifyAccess¶

Verifies user access to a specific booking.

Request Body: | Field | Type | Required | Description | |-------|------|----------|-------------| | session | string | Yes | User session token | | email | string | Yes | Customer email address | | refnum | string | Yes | Booking reference number |

Request Example:

{
  "session": "user-session-token",
  "email": "customer@example.com",
  "refnum": "BK-2025-001234"
}

Response Structure:

{
  "apiStatus": { "errorCode": "OK", "errorMessage": "Success" },
  "apiData": {
    "bookingRequestId": 12345,
    "accessCode": "ABC123XYZ",
    "maxAccess": "2025-07-15T23:59:59"
  }
}

POST /booking/cancel¶

Cancels an existing booking.

Request Body: | Field | Type | Required | Description | |-------|------|----------|-------------| | session | string | Yes | User session token | | requestId | integer | Yes | Booking request ID to cancel |

Request Example:

{
  "session": "user-session-token",
  "requestId": 12345
}

Response Structure:

{
  "apiStatus": { "errorCode": "NOT_IMPLEMENTED", "errorMessage": "Booking cancellation not yet implemented" },
  "apiData": null
}

Note: This endpoint is not yet fully implemented.

Error Codes: - NOT_IMPLEMENTED - Booking cancellation not yet implemented

POST /booking/getTickets¶

Retrieves tickets/vouchers for a confirmed booking.

Request Body: | Field | Type | Required | Description | |-------|------|----------|-------------| | session | string | Yes | User session token | | id | integer | Yes | Booking request ID | | code | string | Yes | Access code for the booking |

Request Example:

{
  "session": "user-session-token",
  "id": 12345,
  "code": "ABC123XYZ"
}

Response Structure:

{
  "apiStatus": { "errorCode": "OK", "errorMessage": "Success" },
  "apiData": [
    {
      "id": 1001,
      "requestId": 12345,
      "barcode": "1234567890123",
      "barcodeImage": "data:image/png;base64,iVBORw0KGgo...",
      "timeslot": "09:00 AM - 10:00 AM",
      "startDate": "2025-06-20T09:00:00",
      "endDate": "2025-06-20T18:00:00",
      "optionId": 500,
      "terms": "Valid for single use only. Non-refundable.",
      "supplierBookingId": 99999,
      "supplierBookingSubId": 1,
      "supplierReference": "SUP-REF-001",
      "supplierVoucher": "VOUCHER-123456",
      "supplierStatus": "CONFIRMED",
      "ticketDescription": "Desert Safari Premium Experience",
      "pickupLocation": "Dubai Mall Main Entrance",
      "extInfo1": "Driver will call 30 mins before pickup",
      "extInfo2": null,
      "extInfo3": null,
      "extInfo4": null,
      "extInfo5": null,
      "ticketUrl": "https://tickets.example.com/download/12345",
      "ticketValidity": "Valid on selected date only",
      "ticketPrintType": "MOBILE",
      "ticketResvName": "John Smith"
    }
  ]
}

Error Codes: - MISSING_PARAMETER - Request ID, session ID, or access code missing

GET /booking/voucher/{id}¶

Retrieves voucher information for a booking (alternative to getTickets).

Path Parameters: | Field | Type | Required | Description | |-------|------|----------|-------------| | id | string | Yes | Booking request ID |

Query Parameters: | Field | Type | Required | Description | |-------|------|----------|-------------| | session | string | Yes | User session token | | code | string | Yes | Access code for the booking |

Request Example:

GET /booking/voucher/12345?session=user-session-token&code=ABC123XYZ

Response Structure: Same as /booking/getTickets - returns array of CTicketConfirmation objects.

Data Models¶

CBookingRequest¶

Field	Type	Description
bookingrequestid	integer	Unique booking request ID
refnum	string	Booking reference number
rqdate	datetime	Request creation date
reqstatus	string	Request status (PENDING, CONFIRMED, CANCELLED)
orderNum	string	Associated sales order number
rqmoddate	datetime	Last modification date
customerid	integer	Customer ID
accessCode	string	Access code for retrieving tickets
accessMaxDate	datetime	Access code expiration date
orderDate	datetime	Original order date
invoiceNum	string	Associated invoice number
amount	number	Total booking amount

CBookingResult¶

Field	Type	Description
requestId	integer	Booking request ID
referenceNumber	string	Booking reference number
completeResult	string	Overall result (OK, PARTIAL, FAILED)
completeMessage	string	Human-readable result message
accessCode	string	Access code for ticket retrieval
ticketingResults	array	Array of CTicketingResult objects

CTicketingResult¶

Field	Type	Description
result	string	Individual item result (OK, FAILED)
statusCode	string	Status code from supplier
statusMessage	string	Status message from supplier

CBookingSearchResult¶

Field	Type	Description
bookingReference	string	Booking reference number
bookingRequestId	integer	Booking request ID
bookingRequestDate	datetime	Request date
bookingRequestStatus	string	Booking status
ticketingRequestStatus	string	Ticketing status
ticketingRequestId	integer	Ticketing request ID
ticketingRequestResult	string	Ticketing result
ticketingRequestErrorCode	string	Error code if failed
ticketingRequestErrorMessage	string	Error message if failed
ticketItemId	integer	Ticket item ID
paxCount	string	Number of passengers
unitId	integer	Product unit ID
unitName	string	Product name
itemDescription	string	Item description
supplierBookingId	integer	Supplier's booking ID
isConfirmed	boolean	Whether booking is confirmed

CBookingAccessAuth¶

Field	Type	Description
bookingRequestId	integer	Booking request ID
accessCode	string	Access code
maxAccess	datetime	Access expiration date

CTicketConfirmation¶

Field	Type	Description
id	integer	Ticket confirmation ID
requestId	integer	Booking request ID
barcode	string	Ticket barcode value
barcodeImage	string	Base64-encoded barcode image
timeslot	string	Selected timeslot
startDate	datetime	Ticket validity start
endDate	datetime	Ticket validity end
optionId	integer	Product option ID
terms	string	Terms and conditions
supplierBookingId	integer	Supplier booking ID
supplierBookingSubId	integer	Supplier sub-booking ID
supplierReference	string	Supplier reference number
supplierVoucher	string	Supplier voucher code
supplierStatus	string	Supplier booking status
ticketDescription	string	Ticket description
pickupLocation	string	Pickup location details
extInfo1-5	string	Extended information fields
ticketUrl	string	URL to download ticket
ticketValidity	string	Validity description
ticketPrintType	string	Print type (MOBILE, PRINT)
ticketResvName	string	Reservation name

Cart-to-Booking Merge (M3.5)¶

POST /blm/cart/addToBooking¶

Merges cart items into an existing booking as new service lines.

Roles: agent, admin

Parameter	Type	Required	Description
session	string	yes	Session token
cartId	integer	yes	Cart to merge
bookingId	integer	yes	Target booking

Response: Updated CBooking object with merged service lines.

Validations: Cart must be ACTIVE with items. Booking must not be terminal, must be UNPAID, and must not have an active payment link. If cart has a customer, it must match the booking's customer.

POST /blm/booking/searchEligible¶

Searches for bookings eligible to receive cart items.

Roles: agent, admin

Parameter	Type	Required	Description
session	string	yes	Session token
keyword	string	no	Search by booking ref, customer name, email, or phone
customerId	integer	no	Filter by customer

Response: Array of CBooking objects (max 15, sorted by date desc). Filtered: UNPAID, no cartReference, not COMPLETED/CANCELLED/EXPIRED.

External Booking Integration (M3.5)¶

POST /offline/sale/reserveForCart¶

Reserves tickets for a BLM cart (lightweight — no ERP quote or payment link).

Roles: agent, admin

Parameter	Type	Required	Description
session	string	no	Session token
ticketIds	integer[]	yes	Ticket IDs to reserve
blmCartReference	string	yes	BLM cart reference for tracking

Response: Array of reserved COfflineTicket objects.

POST /cruise/booking/createBlmPayment¶

Creates a BLM booking from a cruise booking for payment processing.

Roles: agent, admin

Parameter	Type	Required	Description
session	string	yes	Session token
bookingId	integer	yes	Cruise booking ID
customerId	integer	no	ERP customer ID (if known)
customerName	string	no	Customer name (for search/create)
customerEmail	string	no	Customer email
customerPhone	string	no	Customer phone

Response: CBooking object (BLM booking in CONFIRMED/UNPAID state).

POST /cruise/booking/calculateTotal¶

Calculates cruise booking total with proper currency conversion for add-ons.

Roles: agent, admin

Parameter	Type	Required	Description
session	string	yes	Session token
bookingId	integer	yes	Cruise booking ID

Response: { totalAmount: number } — total in local currency with add-on amounts converted.