Xuất vé và đơn hàng

8 phút đọc

Xác nhận xuất vé là bước biến booking tạm thời thành vé điện tử có giá trị thực tế trên hệ thống hãng tàu. Trước bước này, hệ thống hãng chưa ghi nhận đơn và hành khách chưa có chỗ chắc chắn; sau bước này, vé được phát hành thành công và hành khách đủ điều kiện lên tàu.

Lệnh xác nhận xuất vé (POST /bookings/confirmToIssue/{id}) thực hiện kiểm tra số dư đệ quy, trừ tiền theo giá NET đại lý và phát hành vé trên hệ thống hãng tàu.
Không thể tạo đơn trực tiếp qua nhóm API Orders; đối tác chỉ thao tác thông qua nhóm Bookings, nhóm Orders chỉ dùng để tra cứu chi tiết từng chặng đơn.
Với một số hãng tàu, quá trình xuất vé có thể mất từ 5 đến 8 phút; webhook đóng vai trò tín hiệu thông báo, trong khi tra cứu trạng thái booking định kỳ là căn cứ chốt cuối cùng.
Bốn hãng tàu chưa hỗ trợ xuất vé tự động qua API; đơn thuộc các hãng này cần được phát hiện sớm để tránh phát sinh lỗi sau khi đã tạo booking.

Đ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ệ	Toàn bộ các lệnh xác nhận xuất vé và tải vé yêu cầu xác thực đối tác	Xác thực bằng API key
Booking ở trạng thái chờ	Đơn hàng đã tạo thành công và đang ở trạng thái Đã gửi yêu cầu (2)	Luồng đặt vé
Số dư khả dụng đầy đủ	Số dư tài khoản hoặc hạn mức tín dụng toàn chuỗi phải đủ chi trả giá NET	Tiền: số dư, hạn mức và công nợ
Kiểm tra khả năng xuất vé	Xác định hãng tàu có hỗ trợ xuất vé tự động qua API hay không	Xem danh sách hãng tàu bên dưới
Cấu hình webhook sự kiện	Đăng ký URL nhận sự kiện vé đã xuất để cập nhật hệ thống kịp thời	Sự kiện gửi ra

UAT vẫn có thể đặt vé thật và phát sinh tiền thật. Có hãng luôn đặt thật trên cả UAT lẫn Production dù cấu hình tắt đặt vé. Kiểm tra Môi trường trước khi thử xác nhận xuất vé.

Chuỗi xử lý khi xác nhận xuất vé

Sơ đồ dưới đây minh họa các bước xử lý diễn ra bên trong hệ thống khi đối tác gọi lệnh xác nhận xuất vé:

sequenceDiagram
    autonumber
    participant P as "Hệ thống của bạn"
    participant API as "Ferry API"
    participant MONEY as "Kiểm tra số dư"
    participant OP as "Hãng tàu"
    participant WH as "Webhook"

    P->>API: "Xác nhận xuất vé (POST /bookings/confirmToIssue/{id})"
    API->>API: "Kiểm tra giới hạn 5 lần/60 giây và khóa 600 giây"
    API->>MONEY: "Kiểm tra số dư và hạn mức tín dụng"
    alt Thiếu tiền
        MONEY-->>API: "Không đủ số dư"
        API-->>P: "Lỗi 422 không đủ số dư"
    else Đủ tiền
        MONEY-->>API: "Giữ tiền theo giá NET đại lý"
        API->>OP: "Gửi lệnh đặt vé sang hãng tàu"
        alt Hãng xuất vé thành công
            OP-->>API: "Trả mã vé điện tử"
            API->>WH: "Phát sự kiện booking.issuedTicket"
            API-->>P: "Booking chuyển sang Đã có vé (10)"
        else Hãng từ chối hoặc lỗi
            OP-->>API: "Thông báo lỗi xuất vé"
            API->>MONEY: "Hoàn lại tiền đã giữ"
            API->>WH: "Phát sự kiện booking.issuedTicketError"
            API-->>P: "Booking chuyển sang Xuất vé lỗi (6)"
        end
    end

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	Gửi lệnh xác nhận xuất vé	Kiểm tra tần suất gọi (tối đa 5 lần/60 giây)	Tránh gọi dồn dập khi lệnh trước đang chạy
2	Chờ hệ thống giữ khóa xử lý	Kích hoạt khóa xuất vé theo booking (tối đa 600 giây)	Lệnh gọi trùng sẽ nhận lỗi 422 đang xử lý
3	Chờ kiểm tra số dư và giữ tiền	Khấu trừ số dư tạm thời theo giá NET đại lý	Thiếu tiền ở bất kỳ cấp nào cũng làm dừng lệnh
4	Chờ kết nối và đặt chỗ hãng tàu	Gọi API hãng tàu để đăng ký vé thực tế	Thời gian xử lý có thể kéo dài tùy hãng
5	Nhận phản hồi hoặc poll trạng thái	Chuyển booking sang trạng thái 10 khi thành công	Sử dụng polling làm chốt chặn cuối cùng
6	Tải tệp vé điện tử	Cung cấp đường dẫn tải vé điện tử của hãng	Gửi tệp vé hoàn chỉnh cho hành khách

Khóa theo booking ngăn nhiều tiến trình xuất vé đồng thời, nhưng không phải khóa idempotency cho toàn bộ lệnh. Hệ thống không báo trước khi khóa hết hạn. Nếu kiểm tiền thất bại, phần tiền đã giữ được nhả; khi xuất vé thất bại, không có cam kết thời gian hoàn tiền. Tác vụ đối chiếu nền bỏ qua booking đã ở trạng thái 10 nên việc chốt lại trạng thái này an toàn khi lặp.

Xác minh trạng thái vé phát hành

Sơ đồ dưới đây hướng dẫn quy trình xác minh kết quả xuất vé để đảm bảo tính chính xác:

flowchart TD
    A["Gọi lệnh xác nhận xuất vé"] --> B{"Kết quả trả về"}
    B -- "Thành công" --> C["Booking chuyển sang trạng thái 10"]
    B -- "Báo lỗi" --> D["Đọc mã lỗi để xử lý hoặc thử lại"]
    B -- "Timeout / Đang xử lý" --> E["Chuyển sang kiểm tra định kỳ"]
    E --> F["Nhận sự kiện webhook đã có vé"]
    E --> G["Poll API chi tiết booking"]
    F --> G
    G --> H{"Trạng thái booking"}
    H -- "Trạng thái 10" --> C
    H -- "Trạng thái khác" --> I["Chờ đối chiếu nền hoặc liên hệ Ferry"]
    C --> J["Tải tệp vé gửi hành khách"]

Quy tắc phối hợp giữa Webhook và Polling:

Webhook làm tín hiệu: Webhook mang thông tin tức thời khi vé xuất xong, giúp ứng dụng cập nhật giao diện nhanh chóng. Tuy nhiên webhook có thể thất lạc do sự cố mạng.
Polling làm căn cứ chốt: Gọi API xem chi tiết booking (GET /bookings/{id}) là nguồn sự thật đáng tin cậy nhất. Khi trạng thái đơn là 10 (Đã có vé), bạn chắc chắn vé đã được phát hành.
Tác vụ đối chiếu tự động: Nếu kết nối đứt giữa chừng trong lúc hãng đang xử lý, tác vụ đối chiếu nền của Ferry sẽ tự động xác minh lại với hãng và cập nhật trạng thái đơn sau vài phút.

Giới hạn và các bất biến nghiệp vụ

Xuất vé hỏng một phần ở booking nhiều chặng

Trong các booking khứ hồi hoặc nhiều chặng, có tình huống một chặng xuất vé thành công nhưng chặng tiếp theo bị hãng từ chối:

Booking không chuyển sang trạng thái 10 mà giữ trạng thái lỗi.
Số dư của bạn bị trừ một phần cho chặng đã xuất vé thành công; phần tiền của chặng lỗi được hoàn trả lại.
Quy trình xử lý: Kiểm tra chi tiết từng chặng đơn trong booking (GET /bookings/{id}) để xác định chặng nào đã có vé, rồi liên hệ Ferry kèm mã booking. Không tự tạo booking mới và không gọi lại xác nhận xuất vé để sửa lỗi một phần: lệnh xác nhận chạy lại toàn bộ chuỗi, không chỉ chặng còn thiếu.

Giá được tính lại tại thời điểm xuất vé

Hệ thống tính lại toàn bộ đơn giá tại thời điểm xác nhận xuất vé thay vì dùng giá lúc tra cứu. Nếu chính sách giá của hãng hoặc phụ phí thay đổi giữa hai thời điểm, số tiền thực trừ sẽ căn cứ theo giá mới nhất. Xem chi tiết tại Giá vé và markup nhiều cấp.

Nhóm API Orders chỉ hỗ trợ đọc dữ liệu

Ở tầng tích hợp đối tác, bạn không thể tạo hay xác nhận đơn trực tiếp qua nhóm API Orders. Toàn bộ quy trình đặt và xuất vé phải thực hiện qua nhóm Bookings. Nhóm Orders chỉ dùng để tra cứu chi tiết danh sách vé và thông tin từng chặng đơn.

Đối tác cũng chưa có API đọc hoá đơn, dù vẫn nhận được các sự kiện như invoice.created, invoice.updated, invoice.published và invoice.failed. Không thiết kế luồng nhận sự kiện hoá đơn rồi gọi API đối tác để tải chi tiết; xem Webhooks.

Chín hãng xuất vé tự động, bốn hãng chưa hỗ trợ

Hiện tại trong danh mục 13 hãng tàu kết nối với Ferry:

9 hãng xuất vé tự động hoàn chỉnh: Lệnh xác nhận xuất vé gọi sang hệ thống hãng và phát hành vé khi xử lý thành công. Một số hãng có thể mất 5–8 phút; tự động không có nghĩa là trả vé ngay.
4 hãng chưa mở cổng xuất vé tự động: Bình An Hà Tiên, Thạnh Thới, Hàng Châu Tourist và Saigon WaterGo. Booking thuộc 4 hãng này vẫn tạo được nhưng bước xác nhận xuất vé sẽ trả lỗi chưa triển khai. Đối tác cần lưu ý lọc các hãng này hoặc liên hệ đặt vé thủ công qua kênh vận hành.

Tải lại tệp vé điện tử đã xuất

Khi hành khách làm mất vé hoặc cần gửi lại vé qua email, bạn có thể gọi API tải lại tệp vé của booking (GET /bookings/{id}/tickets). Lệnh này chỉ lấy lại bản sao tệp vé đã phát hành, không tạo vé mới và không phát sinh thêm chi phí.

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
Lỗi 422 thông báo đang xử lý xuất vé	Khóa xử lý 600 giây đang được giữ cho booking này	Chờ vài phút rồi poll trạng thái đơn	Có, sau khi chờ
Lỗi tần suất gọi quá 5 lần/60 giây	Gửi lệnh xác nhận liên tiếp vượt ngưỡng bảo vệ	Chờ hết cửa sổ 60 giây trước khi thử lại	Có, sau 60 giây
Lỗi không đủ số dư khi xuất vé	Tài khoản đại lý hoặc cấp trên thiếu hạn mức	Nạp thêm tiền hoặc liên hệ cấp trên nâng hạn mức	Có, sau khi nạp tiền
Lỗi chưa triển khai bộ nối xuất vé	Chuyến tàu thuộc một trong bốn hãng chưa hỗ trợ	Hủy booking và đặt vé qua kênh vận hành Ferry	Không thử lại qua API
Lệnh gọi chạy rất lâu không phản hồi	Kết nối sang hãng tàu xử lý chậm (mất 5–8 phút)	Không ngắt đơn; chuyển sang poll định kỳ trạng thái	Không gọi lệnh mới
Booking lỗi nhưng số dư bị trừ một phần	Xuất vé hỏng một phần trên booking nhiều chặng	Xem chi tiết từng chặng đơn và liên hệ Ferry hỗ trợ	Không tạo booking trùng

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
Lệnh xác nhận xuất vé và tải lại tệp vé điện tử	`Bookings`
Tra cứu danh sách và chi tiết từng chặng đơn	`Orders`
Tra cứu thông tin hành khách gắn với vé	`Customers`

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
Luồng đặt vé	Các bước tạo booking và quản lý vòng đời đơn
Tiền: số dư, hạn mức và công nợ	Cơ chế trừ tiền và kiểm tra số dư chuỗi tổ chức
Sự kiện gửi ra	Nhận thông báo sự kiện vé xuất thành công qua webhook
Huỷ vé và hoàn tiền	Quy trình hủy vé sau khi đã xuất thành công
Môi trường	Sự khác biệt về hành vi xuất vé trên môi trường UAT