Giá vé và markup nhiều cấp

7 phút đọc

Một đơn hàng trong hệ thống Ferry mang ba con số giá khác nhau tùy thuộc vào góc nhìn: giá gốc hãng tàu, giá NET mà đại lý thanh toán cho cấp trên, và giá khách cuối cùng thanh toán. Phần chênh lệch giữa các con số này được tích lũy theo từng cấp trong cây tổ chức phân phối vé.

Ba tầng giá trong hệ thống

Sơ đồ dưới đây cho thấy ba góc nhìn tính giá và đối tượng thanh toán tương ứng cho cùng một đơn hàng:

flowchart LR
    O["Một đơn vé"]
    O --> G1["Giá gốc hãng tàu<br/>(loại bỏ phụ phí đại lý)"]
    O --> G2["Giá NET của đại lý<br/>(gồm phụ phí từ gốc đến bạn)"]
    O --> G3["Giá khách cuối<br/>(gồm toàn bộ phụ phí và markup)"]
    G1 --> X1["Khoản Ferry thanh toán hãng"]
    G2 --> X2["Bạn thanh toán cấp trên"]
    G3 --> X3["Khách hàng thanh toán bạn"]
    X3 --> V1["Áp dụng mã giảm giá và voucher"]
    G2 --> V2["Không áp dụng voucher"]
    G1 --> V3["Không áp dụng voucher"]

Ba con số này đại diện cho ba thỏa ước thương mại riêng biệt:

Giá gốc hãng: Mức giá cơ sở do hãng tàu niêm yết, không bao gồm bất kỳ khoản phụ phí hay hoa hồng nào của mạng lưới đại lý.
Giá NET của đại lý: Giá mà tổ chức của bạn phải thanh toán cho cấp trên trực tiếp. Con số này đã tích lũy toàn bộ các khoản markup của chuỗi tổ chức cấp trên.
Giá khách cuối: Tổng số tiền hành khách chi trả cho bạn, gồm các khoản markup và giảm giá áp dụng. Góc nhìn khách cuối dùng giá đã gồm thuế, còn góc nhìn đại lý dùng giá gốc chưa gồm thuế. Vì vậy, chênh lệch giữa giá khách cuối và giá NET không chỉ phản ánh markup của bạn.

Cơ chế cộng dồn phụ phí theo cây tổ chức

Sơ đồ dưới đây minh họa dòng chảy tích lũy phụ phí qua từng cấp đại lý trong hệ thống:

flowchart TD
    R["Tổ chức gốc"] -->|"Cộng phụ phí cấp gốc"| L1["Đại lý cấp 1"]
    L1 -->|"Cộng phụ phí cấp 1"| L2["Đại lý cấp 2"]
    L2 -->|"Cộng phụ phí cấp 2"| U["Tổ chức của bạn"]
    U -->|"Cộng phụ phí của chính bạn"| F["Giá khách cuối cùng"]
    F --> V["Khấu trừ voucher nếu có"]
    R -.->|"Loại bỏ mọi phụ phí"| N["Giá gốc hãng"]
    U -.->|"Chưa gồm phụ phí của bạn"| M["Giá NET của đại lý"]

Cộng dồn theo phương thức lũy kế: Khi một cấp tổ chức áp dụng phụ phí theo tỷ lệ phần trăm, mức tăng đó được tính trên giá đã bao gồm phụ phí của các cấp đứng trước.

Hệ quả quan trọng khi đối soát doanh thu: tổng tỷ lệ markup của toàn chuỗi không bằng tổng cơ học của các phần trăm cộng lại. Ví dụ, một chuỗi ba cấp đại lý, mỗi cấp thiết lập tăng 10%, sẽ tạo ra mức tăng lũy kế thực tế là 33,1% chứ không phải 30%. Khi số tiền thực trừ chênh lệch với dự tính, bạn nên kiểm tra lại cách tính lũy kế này trước tiên.

Trình tự kiểm tra giá trước khi đặt vé

Sơ đồ dưới đây thể hiện trình tự gọi API để xác thực giá và khuyến mãi trước khi tạo đơn:

sequenceDiagram
    participant P as "Hệ thống của bạn"
    participant F as "Ferry API"
    participant C as "Bộ tính giá"
    P->>F: "Kiểm tra phụ phí theo tình huống đơn"
    F->>C: "Tổng hợp phụ phí theo chuỗi tổ chức"
    C-->>F: "Giá khách cuối và giá NET đại lý"
    F-->>P: "Hai mức giá kèm phần chênh lệch"
    P->>F: "Kiểm tra điều kiện áp dụng voucher"
    alt Voucher hợp lệ
        F-->>P: "Mã hợp lệ và số tiền giảm trừ"
    else Không áp dụng được
        F-->>P: "Lý do từ chối, giữ nguyên giá gốc"
    end
    P->>F: "Tạo booking mới"
    F-->>P: "Mã booking và giá ghi nhận"

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	Xác định tình huống giá cụ thể	Đối chiếu tình huống với các quy tắc phụ phí	Nêu đúng mã chuyến, hạng ghế và số lượng khách
2	Gọi kiểm tra phụ phí (`POST /ticket-price-additions/check`)	Tính toán và trả về giá NET cùng giá khách cuối	Lệnh này không đòi hỏi quyền đặc biệt
3	Gọi kiểm tra voucher (`POST /vouchers/check-aplicability`)	Trả về trạng thái áp dụng và số tiền giảm	Lưu ý tên endpoint viết là `check-aplicability`
4	Đối chiếu lợi nhuận gộp	Xác định phần chênh lệch giữa giá khách cuối và giá NET	Đảm bảo biên lợi nhuận đủ bù chi phí vận hành
5	Tạo booking và xác nhận xuất vé	Ghi nhận đơn và thực hiện tính lại giá khi xuất vé	Giá trừ thực tế được chốt tại thời điểm xuất vé

Hai lệnh kiểm phụ phí và voucher chỉ cần khóa API hợp lệ, không cần quyền đặc biệt. Ngược lại, tạo phụ phí và tạo voucher yêu cầu quyền tạo tương ứng. Khi kiểm giá, dùng đúng chuyến, hạng ghế, số lượng và loại hành khách; phụ phí đã tạo có thể không áp dụng nếu điều kiện không khớp.

Quy tắc và bất biến về giá

Ferry tính lại giá tại thời điểm xác nhận xuất vé: Hệ thống tính toán lại toàn bộ đơn giá tại thời điểm thực hiện lệnh xuất vé thay vì dùng giá lúc tra cứu. Giá hiển thị khi tìm chuyến chỉ mang tính tham khảo.
Đơn vị tiền tệ chuẩn: Toàn bộ số tiền đều là số nguyên (VNĐ), không có phần thập phân và không có trường đơn vị tiền tệ kèm theo.
Tên endpoint kiểm tra voucher: Endpoint kiểm tra mã giảm giá có tên định danh chính xác là POST /vouchers/check-aplicability (một chữ p). Viết theo chính tả tiếng Anh thông thường sẽ nhận mã 404.
Voucher chỉ áp dụng cho giá khách cuối: Voucher không làm giảm giá NET đại lý phải thanh toán cho cấp trên.
Không có khóa chống lặp khi tạo phụ phí hoặc voucher: Gọi lại sau timeout có thể tạo bản ghi thứ hai. Hãy liệt kê và đối chiếu các bản ghi với dữ liệu vừa gửi; dùng bản ghi đã có, chỉ tạo lại khi không tìm thấy. Phụ phí trùng có thể bị cộng hai lần vào giá khách.
Góc nhìn mặc định là khách cuối: Khi không chỉ rõ góc nhìn, giá trả về phục vụ báo giá cho khách, không phải số tiền bạn thanh toán cấp trên.
Các số liệu đối tác đọc được: Tổng tiền khách cuối của booking, tổng giá NET của booking, tổng tiền gốc trước khi đổi vé, giá NET từng chặng đơn và số tiền NET được hoàn của đơn. Không suy ra mọi trường giá khác đều được mở cho API key; nếu thiếu trường đáng lẽ phải có, báo Ferry thay vì gọi lặp.
Không tự giả định công thức làm tròn: Thứ tự áp phụ phí, thuế, voucher và quy tắc làm tròn chưa được xác nhận đầy đủ. Dùng kết quả Ferry trả về để đối soát; khả năng nhận các trường cost, profit, revenue cũng cần Ferry xác nhận.

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
Giá khách cuối bằng giá NET đại lý	Bạn chưa tạo khoản phụ phí hoặc markup của riêng tổ chức mình	Thiết lập phụ phí đại lý trên giao diện hoặc API	Không, tạo phụ phí trước
Gọi kiểm tra voucher nhận mã 404	Gõ tên endpoint theo chính tả thông thường	Sử dụng chính xác đường dẫn `check-aplicability`	Có, sau khi sửa URL
Voucher báo không áp dụng được	Đơn hàng không thỏa mãn điều kiện ngày, tuyến hoặc hạng vé	Kiểm tra điều kiện voucher trả về trong phản hồi	Không, kiểm tra điều kiện
Tiền thực trừ khi xuất vé khác giá tra cứu	Hệ thống tính lại giá tại thời điểm xuất vé thực tế	Sử dụng giá tại kết quả xuất vé làm căn cứ đối soát	Không, đây là hành vi chuẩn
Phụ phí bị cộng hai lần sau sự cố mạng	Gửi lại lệnh tạo phụ phí mà không kiểm tra bản ghi cũ	Xóa bản ghi phụ phí thừa và kiểm tra lại giá	Không gọi tạo lặp lại

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
Thiết lập và kiểm tra phụ phí giá vé	`Ticket Price Additions`
Quản lý và kiểm tra tính hợp lệ của voucher	`Vouchers`
Xem trường giá và tổng tiền trên booking	`Bookings`
Tra cứu giá NET từng chặng đơn	`Orders`

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
Tra chuyến và chỗ trống	Tìm chuyến và các thông số ban đầu
Luồng đặt vé	Vòng đời booking và thời điểm thanh toán
Tiền: số dư, hạn mức và công nợ	Cơ chế trừ tiền và kiểm tra hạn mức tín dụng
Xuất vé và đơn hàng	Trình tự các bước xuất vé điện tử
Quy ước chung	Quy ước định dạng tiền tệ và xử lý timeout