Tra chuyến và chỗ trống

8 phút đọc

Luồng tra cứu chuyến cung cấp thông tin lịch chạy giữa các bến theo ngày, số chỗ trống và sơ đồ ghế chi tiết để khách hàng lựa chọn trước khi đặt vé. Ferry trả về dữ liệu chuyến đã được đồng bộ định kỳ từ hãng tàu, do đó dữ liệu phản ánh ảnh chụp gần nhất thay vì trạng thái tức thời trên hệ thống của từng hãng.

Điều kiện cần trước khi bắt đầu

Điều kiện	Ý nghĩa nghiệp vụ	Tài liệu tham khảo
Khóa API hợp lệ	Các lệnh tìm chuyến, sơ đồ ghế và đếm chỗ yêu cầu xác thực đối tác	Xác thực bằng API key
Mã bến đi và bến đến	API tra cứu sử dụng mã định danh bến, không dùng tên dạng văn bản tự do	Xem danh mục bến công khai
Môi trường gọi API	Môi trường thử nghiệm UAT có danh sách hãng tạm tắt đồng bộ dữ liệu	Môi trường
Quy ước phân trang và ngày	Giới hạn 50 bản ghi mỗi trang; ngày gửi lên theo định dạng `YYYY-MM-DD`	Quy ước chung
Quy tắc tính giá	Giá kèm kết quả tra chuyến đã gồm các khoản markup của tuyến trên	Giá vé và markup nhiều cấp

Trình tự các bước thực hiện

Sơ đồ dưới đây cho thấy trình tự tương tác giữa hệ thống của bạn và Ferry trong luồng tra cứu:

sequenceDiagram
    autonumber
    participant P as "Hệ thống của bạn"
    participant F as "Ferry API"
    participant S as "Sơ đồ ghế"

    P->>F: "Lấy danh mục bến (công khai)"
    F-->>P: "Danh sách bến kèm mã bến"

    P->>F: "Tìm chuyến theo cặp bến và ngày"

    alt "Danh sách trả về rỗng"
        F-->>P: "Mảng rỗng kèm mã 200"
        Note over P,F: "Danh sách rỗng: hết chuyến hoặc gián đoạn dữ liệu"
        P->>P: "Đối chiếu ngưỡng cảnh báo"
    else "Có chuyến khả dụng"
        F-->>P: "Danh sách chuyến và giá cơ sở"
        P->>S: "Lấy sơ đồ ghế theo mã chuyến"
        S-->>P: "Sơ đồ ghế kèm trạng thái từng ghế"
        P->>F: "Đếm số chỗ còn lại"
        F-->>P: "Số lượng chỗ còn trống"
    end

Sơ đồ dưới đây thể hiện mối quan hệ giữa các bước tra cứu danh mục và tra cứu chuyến:

flowchart LR
    A["Nạp danh mục bến, tuyến<br/>(không cần API Key)"] --> B["Tìm chuyến theo bến và ngày<br/>(cần API Key)"]
    B --> C["Lấy sơ đồ ghế của chuyến<br/>(cần API Key)"]
    C --> D["Đếm số chỗ còn trống<br/>(cần API Key)"]
    D --> E["Chuyển sang luồng đặt vé"]
    A -.->|"Bộ nhớ tạm phía đối tác"| A
    B -.->|"Gọi lại khi đổi bến hoặc ngày"| B

Bảng dưới đây tóm tắt các thao tác theo từng bước:

Bước	Hệ thống của bạn	Phía Ferry	Lưu ý đối tác
1	Nạp danh mục bến và tuyến một lần	Trả danh mục dùng chung (không cần khóa)	Lưu bộ nhớ tạm phía bạn; không gọi lại ở mỗi lượt khách tìm
2	Tra cứu chuyến theo cặp bến và ngày	Trả danh sách chuyến từ dữ liệu đã đồng bộ	Kiểm tra mảng kết quả; nếu rỗng, tránh kết luận vội là hết chuyến
3	Lấy sơ đồ ghế của chuyến đã chọn	Trả cấu trúc ghế và trạng thái từng ghế	Ghế trống là ảnh chụp tại lần đồng bộ gần nhất
4	Đếm chỗ còn trước khi cho chọn ghế	Trả số lượng ghế còn khả dụng	So sánh số chỗ với số lượng khách cần đặt
5	Chuyển thông tin sang bước đặt vé	Chuẩn bị dữ liệu chuyến, ghế và hành khách	Xem tiếp Luồng đặt vé

Có thể tra chuyến theo dải ngày để dựng lịch tháng, không chỉ từng ngày; vẫn phải đọc đủ các trang kết quả.
Ngày YYYY-MM-DD được hiểu theo giờ địa phương của hãng, không có trường múi giờ kèm theo. Nếu máy chủ ở múi giờ khác, quy đổi về giờ Việt Nam trước khi tạo chuỗi ngày.
Danh mục tuyến và bến dùng chung cho mọi tổ chức, vẫn chịu giới hạn theo IP dù không cần khóa. Khuyến nghị làm mới cache danh mục mỗi ngày; chưa có cam kết tần suất thay đổi.

Chu kỳ đồng bộ và độ trễ dữ liệu

Ferry đồng bộ thông tin chuyến từ hãng tàu theo từng nhóm ngày:

Nhóm ngày	Phạm vi thời gian	Nhịp đồng bộ định kỳ
Ngày gần	Hôm nay đến 7 ngày tới	Mỗi 30 phút một lần
Ngày vừa	Từ 8 đến 14 ngày tới	Mỗi 2 giờ một lần
Ngày xa	Từ 15 đến 45 ngày tới	Mỗi 4 giờ một lần
Ngày rất xa	Từ 46 đến 90 ngày tới	3 lần mỗi ngày
Chuyến hết chỗ	Mọi ngày	Quét lại mỗi 40 phút
Chuyến bị hãng tạm dừng	Mọi ngày	Quét lại mỗi 4 giờ

Ba yếu tố ảnh hưởng đến độ trễ dữ liệu thực tế:

Rải tải tác vụ: Các tác vụ đồng bộ được rải đều trong cửa sổ 5 phút để tránh quá tải máy chủ hãng.
Bỏ qua lượt quét xa: Với các ngày xa, nếu dữ liệu lưu tạm chưa hết hạn, hệ thống sẽ bỏ qua lượt truy vấn hãng để tối ưu tài nguyên.
Cơ chế dự phòng khi hãng gián đoạn: Ferry có thể trả bản dữ liệu hợp lệ gần nhất trong tối đa 4 giờ thay vì báo lỗi. Phản hồi không có dấu hiệu cho biết đó là bản dự phòng; nếu số liệu đứng yên bất thường, hãy báo Ferry.

Khuyến nghị thiết kế cho đối tác: Đặt thời gian lưu bộ nhớ tạm (cache) phía bạn không quá 5 phút cho ngày gần, và luôn gọi lại sơ đồ ghế cùng số chỗ còn trống ngay trước khi khách chốt chọn chỗ.

Các bẫy nghiệp vụ cần lưu ý

Danh sách rỗng kèm mã 200: Truy vấn tìm chuyến trả về mảng rỗng khi không có chuyến hoặc khi xảy ra sự cố dữ liệu. Bạn nên thiết lập ngưỡng theo dõi bất thường trên các tuyến cố định.
Tham số sắp xếp bị bỏ qua: Yêu cầu sắp theo giờ khởi hành hoặc giá bị thay bằng sắp theo mã bản ghi, không có cảnh báo. Hãy đọc đủ các trang rồi sắp xếp tại ứng dụng của bạn.
Giới hạn số lượng bản ghi: Tra chuyến thông thường bị kẹp tối đa 50 bản ghi mỗi trang, không báo lỗi. Riêng bảng chuyến dạng HTML để nhúng vào web hoặc email có trần 100. Dùng con trỏ phân trang để đọc đủ dữ liệu.
Không có bước giữ chỗ trước: Xem sơ đồ hoặc tạo booking chưa giữ ghế trên hệ thống hãng tàu. Booking mới chỉ là bản ghi phía Ferry; chỗ và vé chỉ được xác nhận sau khi bước xác nhận xuất vé thành công.
Chuyến chưa hỗ trợ xuất vé tự động: Tra cứu trả về chuyến của 13 hãng tàu, nhưng hiện có 4 hãng chưa mở bộ nối xuất vé tự động qua API. Xem chi tiết tại Xuất vé và đơn hàng.

Lỗi thường gặp và cách xử lý

Triệu chứng	Nguyên nhân khả dĩ	Hướng xử lý	Có nên thử lại ngay
Mảng chuyến rỗng trên tuyến đang khai thác	Tuyến chưa mở bán hoặc kết nối hãng gặp sự cố tạm thời	Đối chiếu lịch chạy công bố; báo Ferry nếu kéo dài	Gọi lại sau một khoảng thời gian
Nhận tối đa 50 bản ghi dù yêu cầu nhiều hơn	Giới hạn phân trang tối đa 50 bản ghi mỗi trang	Dùng con trỏ phân trang để tải trang tiếp theo	Có, gọi trang tiếp theo
Kết quả không theo thứ tự giờ chạy mong muốn	Tham số sắp xếp được xử lý theo mã nội bộ	Sắp xếp dữ liệu tại ứng dụng phía bạn	Không, xử lý phía máy khách
Ghế còn trên sơ đồ nhưng tạo đơn báo hết chỗ	Chỗ đã được đặt bởi kênh khác trước khi tạo đơn	Làm mới sơ đồ ghế và mời khách chọn ghế khác	Có, sau khi làm mới sơ đồ
Nhận mã 403 khi gọi tra chuyến	Không phải thiếu quyền: tra chuyến, sơ đồ ghế và đếm chỗ chỉ yêu cầu khóa hợp lệ, không kiểm quyền riêng	Thử lại một lần; nếu vẫn lỗi hoặc xảy ra hàng loạt, báo vận hành Ferry	Có, một lần

Tra cứu trên Scalar

Để tra cứu lược đồ tham số chi tiết và thử nghiệm gọi trực tiếp, mở giao diện Scalar UI theo các nhóm nghiệp vụ:

Nội dung cần xem	Nhóm trên Scalar
Tra cứu chuyến theo bến và ngày, lịch chạy	`Voyages`
Sơ đồ ghế và trạng thái vị trí ngồi	`Boat Layout`
Đếm số lượng chỗ trống còn lại	`Voyage Counts`
Danh mục tuyến tàu (công khai)	`Routes`
Danh mục bến đón trả (công khai)	`Locations`
Danh sách hãng tàu (công khai)	`Operators`

Xem hướng dẫn đăng nhập và điền khóa API tại Tham chiếu API.

Đọc tiếp

Trang	Nội dung liên quan
Giá vé và markup nhiều cấp	Hiểu cơ chế tính giá và các khoản cộng thêm
Luồng đặt vé	Các bước tạo booking và quản lý vòng đời đơn
Quy ước chung	Chuẩn định dạng ngày, tiền tệ và cơ chế phân trang
Môi trường	Khác biệt dữ liệu giữa môi trường UAT và sản xuất
Xuất vé và đơn hàng	Quy trình xác nhận xuất vé điện tử