Manage My Booking (MMB)

Quản lý và chỉnh sửa booking đã tồn tại.

📋 Overview

MMB operations cho phép user xem và chỉnh sửa booking sau khi đã tạo.

Available Operations:

List Bookings - Danh sách tất cả booking
Get Details - Xem chi tiết booking
Payment - Thanh toán (HOLD → ISSUED)
Update Services - Thêm hành lý, suất ăn
Buy Seat - Chọn/mua chỗ ngồi
Update Journey - Đổi chuyến bay
Send VJ Email - Gửi email itinerary từ VJ API
Cancel VJ Journey - Hủy hành trình VJ (từng chặng)
Add Journey - Thêm hành trình mới
Update Passenger - Đổi tên hành khách
Send SkyAgent Email - Gửi email qua Kafka queue
Download Itinerary PDF - Tải file PDF hành trình
Split Passenger - Tách hành khách ra PNR mới

🔄 MMB Flow Diagram

📚 Operations Guide

1. List Bookings

Doc: 01-LIST-BOOKINGS.md

API: GET /api/v1/services/booking/v1/danh-sach-ve

Purpose: Get all bookings for F2 account

Returns:

{
  "data": [
    { "id": 68, "pnr": "ABC123", "trang_thai": 0 },
    { "id": 67, "pnr": "XYZ789", "trang_thai": 1 }
  ]
}

Use id for next operations.

2. Get Details

Doc: 02-GET-DETAILS.md

API: GET /api/v1/services/booking/v1/thong-tin-ve/{ve_id}

Purpose: View complete booking information

Returns:

Booking info (ve)
Passengers (hanh_khach)
Flight segments (chang_bay)
Purchased services

Save these IDs:

ve_id - Booking ID
hanh_khach_id - Passenger ID
key_chang_bay - Flight segment key

3. Payment

Doc: 03-PAYMENT.md

API: POST /api/v1/services/booking/v1/thanh-toan

Purpose: Pay HOLD booking to issue ticket

Applies to: HOLD bookings only (trang_thai: 0)

Request:

{
  "ve_id": 68,
  "phuong_thuc": "wallet",
  "xac_nhan": "y"
}

Result: trang_thai: 0 → trang_thai: 1 (ISSUED)

4. Update Services

Doc: 04-UPDATE-SERVICES.md

APIs:

POST /danh-sach-phu-tro-dat-ve - Get available services
POST /cap-nhat-dich-vu - Confirm services

Purpose: Add baggage, food to existing booking

Applies to: Usually HOLD bookings

Services:

Baggage: 20kg, 30kg, 40kg, Oversize
Food: Combo meals

Request:

{
  "ve_id": 81,
  "dich_vu": [
    {
      "hanh_khach_id": 529,
      "uuid_dich_vu": "service-uuid",
      "index_chang_bay": 1,
      "index_hanh_trinh": 0
    }
  ],
  "xac_nhan": "y",
  "tong_tien": 439600
}

5. Buy Seat

Doc: 05-BUY-SEAT.md

APIs:

POST /danh-sach-phu-tro-dat-ve - Get seat map
POST /cap-nhat-cho-ngoi - Confirm seat

Purpose: Select and purchase seat

Applies to: Usually HOLD bookings

Seat Prices:

ECONOMY: ~54,000 VND (paid)
DELUXE/SKYBOSS: 0 VND (free)

Request:

{
  "ve_id": 94,
  "cho_ngoi": [
    {
      "hanh_khach_id": 542,
      "uuid_cho_ngoi": "seat-uuid",
      "index_chang_bay": 1,
      "index_hanh_trinh": 1
    }
  ],
  "xac_nhan": "y",
  "tong_tien": 54000
}

6. Update Journey

Doc: 06-UPDATE-JOURNEY.md

APIs:

POST /tim-chuyen - Search new flight (with ve_id)
POST /cap-nhat-hanh-trinh - Calculate fee & confirm

Purpose: Change to different flight

Applies to: Both HOLD and ISSUED bookings

⚠️ CRITICAL: Search must include ve_id:

{
  "sid": "socket-id",
  "chang_bay": [...],
  "ve_id": 94
}

Request:

{
  "ve_id": 94,
  "index_chang_bay_doi": 0,
  "loai_phi_dai_ly": "Nhập",
  "uuid_chuyen_bay": "new-flight-uuid",
  "index_chang_bay_moi": 0,
  "xac_nhan": "y",
  "tong_tien": 378000
}

9. Add Journey

Doc: 09-ADD-JOURNEY.md

APIs:

POST /tim-chuyen - Search new flight (with ve_id)
POST /them-hanh-trinh - Preview fee & confirm

Purpose: Add new journey (flight segment) to existing booking

Applies to: Both HOLD and ISSUED bookings

Use Cases:

Convert one-way → round-trip
Add connecting flight
Add return flight after initial booking

⚠️ CRITICAL: Search must include ve_id:

{
  "sid": "socket-id",
  "chang_bay": [...],
  "ve_id": 94
}

Request (Preview):

{
  "ve_id": 94,
  "loai_phi_dai_ly": "Nhập",
  "uuid_chuyen_bay": "new-flight-uuid",
  "index_chang_bay_moi": 0,
  "tong_tien": 0,
  "xac_nhan": ""
}

Request (Confirm):

{
  "ve_id": 94,
  "loai_phi_dai_ly": "Nhập",
  "uuid_chuyen_bay": "fresh-flight-uuid",
  "index_chang_bay_moi": 0,
  "tong_tien": 1086300,
  "xac_nhan": "y"
}

⚠️ Important: Must re-search to get fresh UUID before confirm (bookingKey expires in ~30s)

🎯 Decision Flow

⚠️ Important Rules

1. Payment Deadlines

HOLD bookings have payment deadline (~4 hours):

if (booking.trang_thai === 0) {
  const deadline = new Date(booking.ngay_het_han);
  const hoursLeft = (deadline - Date.now()) / (1000 * 60 * 60);

  if (hoursLeft < 0) {
    console.log("Booking expired!");
  }
}

2. Booking Status

trang_thai	Status	Description
`0`	HOLD	Giữ chỗ - Chưa thanh toán, có deadline
`1`	ISSUED	Đã xuất vé - Đã thanh toán

3. Index Conventions

API	Field	Indexing
Update Services	`index_chang_bay`	1-based
Buy Seat	`index_chang_bay`	1-based
Update Journey	`index_chang_bay_doi`	0-based

4. UUID Expiration

Services and seat UUIDs expire in ~5-10 minutes:

// Always get fresh UUIDs before confirm
const services = await getServices(ve_id);
// Immediately confirm (don't wait)
await confirmServices(services);

5. ve_id for Update Journey & Add Journey

When searching for update journey or add journey:

// Normal search
{ chang_bay: [...], hang_bay: ['VJ'] }

// Update/Add journey search - MUST include ve_id
{ chang_bay: [...], hang_bay: ['VJ'], ve_id: 94 }

6. Fresh UUID for Add Journey

Add Journey requires re-search before confirm:

// Step 1: Preview with initial UUID
const preview = await previewAddJourney({ uuid_chuyen_bay: initialUUID });

// Step 2: Re-search to get FRESH UUID (bookingKey expires in ~30s)
const freshSearch = await searchFlights({ ve_id: 94, ... });
const freshUUID = freshSearch.flights[0].uuid;

// Step 3: Confirm with FRESH UUID + PREVIEW fee
const confirm = await confirmAddJourney({
  uuid_chuyen_bay: freshUUID,  // Fresh UUID
  tong_tien: preview.data.tong_tien,  // Fee from preview
  xac_nhan: "y"
});

Prerequisites

../authentication/ - Login & get profile

Booking Flows

../booking-flows/ - Create new bookings

MMB Operations

01-LIST-BOOKINGS.md - List all bookings
02-GET-DETAILS.md - Get booking details
03-PAYMENT.md - Pay HOLD booking
04-UPDATE-SERVICES.md - Add baggage, food
05-BUY-SEAT.md - Select seat
06-UPDATE-JOURNEY.md - Change flight
07-SEND-VJ-EMAIL.md - Send email itinerary via VJ API
08-CANCEL-VJ-JOURNEY.md - Cancel VJ journey (individual journey)
09-ADD-JOURNEY.md - Add new journey to booking
10-UPDATE-PASSENGER.md - Update passenger name
11-SEND-SKYAGENT-EMAIL.md - Send email via Kafka queue

📝 Summary

Typical MMB Flow:

1. List → 2. Get Details → Check Status →
   - If HOLD: Payment / Add Services / Buy Seat / Add Journey
   - If ISSUED: Update Journey / Add Journey (with fee)

Key Requirements:

Get ve_id from list
Get hanh_khach_id from details
Check trang_thai before operations
Get fresh UUIDs for services/seats
Include ve_id in search for update journey / add journey
Re-search for fresh UUID before confirming Add Journey (bookingKey expires in ~30s)

📋 Overview​

🔄 MMB Flow Diagram​

📚 Operations Guide​

1. List Bookings​

2. Get Details​

3. Payment​

4. Update Services​

5. Buy Seat​

6. Update Journey​

9. Add Journey​

🎯 Decision Flow​

⚠️ Important Rules​

1. Payment Deadlines​

2. Booking Status​

3. Index Conventions​

4. UUID Expiration​

5. ve_id for Update Journey & Add Journey​

6. Fresh UUID for Add Journey​

🔗 Related Documentation​

Prerequisites​

Booking Flows​

MMB Operations​

📝 Summary​

📋 Overview

🔄 MMB Flow Diagram

📚 Operations Guide

1. List Bookings

2. Get Details

3. Payment

4. Update Services

5. Buy Seat

6. Update Journey

9. Add Journey

🎯 Decision Flow

⚠️ Important Rules

1. Payment Deadlines

2. Booking Status

3. Index Conventions

4. UUID Expiration

5. ve_id for Update Journey & Add Journey

6. Fresh UUID for Add Journey

🔗 Related Documentation

Prerequisites

Booking Flows

MMB Operations

📝 Summary