Môi trường

7 phút đọc

Ferry cung cấp hai môi trường vận hành: Production phục vụ khách hàng thực tế và UAT dành cho đối tác thử nghiệm tích hợp. Trang này giải thích sự khác biệt giữa hai môi trường, các lưu ý quan trọng khi kiểm thử và danh sách hãng tàu hỗ trợ xuất vé tự động.

So sánh hai môi trường

Hệ thống của đối tác kết nối tới Ferry qua hai môi trường với thông số như sau:

Môi trường	Mục đích sử dụng	Địa chỉ kết nối (Base URL)	Đặc tả OpenAPI
Production	Vận hành thực tế cho khách hàng	`https://api.ferry.vn`	`https://api.ferry.vn/docs`
UAT	Thử nghiệm tích hợp hệ thống	Nhận bằng văn bản từ Ferry	`/docs` trên tên miền UAT

Một số nguyên tắc cấu hình cần ghi nhớ:

Tiền tố phiên bản: Toàn bộ route gọi nghiệp vụ có định dạng /api/v1/<tên-tài-nguyên>.
Tài liệu OpenAPI: Cổng Scalar tương tác được đặt trực tiếp tại đường dẫn /docs (không kèm tiền tố /api). Mở /docs trên tên miền nào sẽ xem tài liệu tương ứng của môi trường đó.
Xác nhận base URL UAT: Do hạ tầng kiểm thử có thể cập nhật tên miền, đối tác cần liên hệ đội ngũ kỹ thuật Ferry để nhận base URL chính thức trước khi triển khai.

UAT không phải sandbox mô phỏng

Điểm cốt lõi đối tác cần đặc biệt lưu ý: Ferry không có môi trường sandbox giả lập. Môi trường UAT là hệ thống chạy thật thứ hai, kết nối trực tiếp với cổng đặt vé của các hãng tàu.

Sơ đồ dưới đây cho thấy luồng xử lý đơn hàng giữa môi trường thử nghiệm và hãng tàu:

flowchart TB
    PROD["Môi trường Production<br/>api.ferry.vn"]
    UAT["Môi trường UAT<br/>Kiểm thử tích hợp"]
    CHECK{"Lệnh xác nhận xuất vé<br/>confirmToIssue"}
    PROD --> CHECK
    UAT --> CHECK
    CHECK -->|"Xác nhận"| REAL["Gọi cổng đặt vé hãng tàu<br/>Đặt vé thật"]
    REAL --> MONEY["Trừ tiền thật trong tài khoản đại lý"]
    CHECK -->|"Chỉ tạo booking"| SAFE["Giữ chỗ tạm thời<br/>Không mất phí"]

Hệ quả khi kiểm thử trên UAT:

Vé thật và tiền thật: Mỗi lần gọi lệnh xác nhận xuất vé (POST /api/v1/bookings/confirmToIssue/:id) trên UAT, hệ thống sẽ thực hiện đặt vé thật trên hệ thống của hãng tàu và trừ tiền trực tiếp trên tài khoản ký quỹ của đại lý.
Ngoại lệ hãng CangSaKy: Hãng CangSaKy kết nối trực tiếp vào hệ thống hãng và luôn tạo đơn thật bất kể cấu hình chặn thử nghiệm. Vé thử nghiệm của CangSaKy luôn phát sinh chi phí ngay lập tức.
Quy trình huỷ vé: Muốn huỷ các vé đã phát sinh trong quá trình thử nghiệm, bạn phải tuân thủ đúng quy trình huỷ vé và chịu phí phạt huỷ theo quy định của hãng tàu.
Thử nghiệm an toàn: Trong giai đoạn tích hợp ban đầu, đối tác nên dừng lại ở bước tạo booking giữ chỗ (POST /api/v1/bookings) để kiểm tra dữ liệu mà không tốn phí. Chỉ gọi lệnh xác nhận xuất vé khi đã thống nhất trước với Ferry về chuyến tàu và chi phí thử nghiệm.

Khả năng xuất vé tự động của các hãng tàu

Hệ thống Ferry tích hợp 13 hãng tàu phục vụ tra cứu chuyến và giá vé. Tuy nhiên, khả năng tự động hoá xuất vé điện tử qua API có sự khác biệt giữa các hãng:

Hãng tàu	Khả năng tra cứu	Xuất vé tự động qua API	Lưu ý vận hành
ChanKhaLuxury	Hỗ trợ	Hỗ trợ tự động	Xuất vé trực tiếp qua API
Greenlines	Hỗ trợ	Hỗ trợ tự động	Xuất vé trực tiếp qua API
HoaBinhShip	Hỗ trợ	Hỗ trợ tự động	Xuất vé trực tiếp qua API
Lightning68	Hỗ trợ	Hỗ trợ tự động	Xuất vé trực tiếp qua API
MaiLinhExpress	Hỗ trợ	Hỗ trợ tự động	Xuất vé trực tiếp qua API
PhuQuocExpress	Hỗ trợ	Hỗ trợ tự động	Xuất vé trực tiếp qua API
PhuQuyExpress	Hỗ trợ	Hỗ trợ tự động	Xuất vé trực tiếp qua API
SuperDong	Hỗ trợ	Hỗ trợ tự động	Xuất vé trực tiếp qua API
CangSaKy	Hỗ trợ	Hỗ trợ tự động	Kết nối trực tiếp hệ thống hãng
BinhAnHaTien	Hỗ trợ	Chưa hỗ trợ	Chỉ tra cứu lịch và giá
ThanhThoi	Hỗ trợ	Chưa hỗ trợ	Chỉ tra cứu lịch và giá
HangChauTourist	Hỗ trợ	Chưa hỗ trợ	Chỉ tra cứu lịch và giá
SaiGonWaterGo	Hỗ trợ	Chưa hỗ trợ	Chỉ tra cứu lịch và giá

Đối với 4 hãng tàu chưa hỗ trợ xuất vé tự động, lệnh xác nhận xuất vé sẽ trả về lỗi tính năng chưa được hỗ trợ. Phía đối tác nên chủ động lọc hoặc cảnh báo trên giao diện người dùng đối với các chuyến tàu thuộc nhóm này.

Khác biệt hành vi giữa Production và UAT

Đặc điểm	Môi trường UAT	Môi trường Production	Khuyến nghị cho đối tác
Dữ liệu kiểm thử	Hệ thống ghi log chi tiết payload để hỗ trợ gỡ lỗi	Ghi log bảo mật theo chuẩn	Tuyệt đối không dùng thông tin cá nhân nhạy cảm của khách hàng thật trên UAT
Cổng kết nối hãng	Đăng nhập của 11 hãng tàu có thể tạm tắt để tránh can thiệp	Mở kết nối toàn bộ hãng theo hợp đồng	Báo trước cho Ferry nếu bạn cần kiểm thử một hãng tàu cụ thể trên UAT (tránh lỗi tra chuyến trả về rỗng)
Chữa công nợ	Tiến trình đối soát công nợ chỉ chạy thử (dry-run)	Tự động đối soát và bù trừ số liệu	Lệch số dư trên UAT sau khi thử nghiệm sẽ không tự động phục hồi
Định dạng API key	Chuỗi khoá cấu hình theo môi trường, hình thức tương tự Production	Chuỗi khoá cấu hình theo môi trường Production	Tách riêng cấu hình biến môi trường của hai hệ thống để tránh gọi nhầm
Dữ liệu vé thử nghiệm	Xuất vé thật, cần chọn chuyến giá thấp để thử	Xuất vé thương mại cho khách hàng	Chỉ thử luồng xuất vé khi có sự giám sát và thống nhất chi phí giữa hai bên
Lưu xác thực trên Scalar	Không lưu khoá qua các lần tải lại trang	Không lưu khoá qua các lần tải lại trang	Cần dán lại API key vào nút Authorize sau mỗi lần tải lại trình duyệt

Sai lầm thường gặp

Hiểu nhầm	Thực tế	Cách xử lý đúng
Cho rằng UAT là môi trường giả lập không tốn tiền	UAT đặt vé thật trên hệ thống hãng tàu	Không đưa luồng xuất vé vào các bài kiểm thử tự động lặp lại
Dùng chung một API key cho cả UAT và Production	Mỗi môi trường có cơ sở dữ liệu và danh sách key riêng biệt	Lưu trữ hai bộ khoá riêng biệt trong cấu hình máy chủ
Nghĩ rằng mọi hãng tra cứu được đều xuất vé tự động được	4 hãng tàu chỉ hỗ trợ tra cứu chuyến và giá	Kiểm tra danh sách hãng hỗ trợ trước khi mở bán cho khách
Đưa thông tin khách hàng thật lên UAT	UAT bật chế độ ghi log chi tiết payload	Chỉ sử dụng dữ liệu hành khách giả lập trên môi trường kiểm thử
Tra chuyến trên UAT trả về rỗng là do hết chuyến	Đăng nhập hãng tàu có thể đang bị tắt trên UAT	Liên hệ Ferry để mở kết nối cho hãng cần thử nghiệm

Tra ở đâu trên Scalar

Mỗi môi trường sở hữu cổng tài liệu OpenAPI độc lập. Để tra cứu schema và gọi thử endpoint tương ứng:

Mục tiêu tra cứu	Cổng tài liệu
Tra cứu schema và thử nghiệm trên Production	Scalar UI — Ferry VN API
Tra cứu schema và thử nghiệm trên UAT	Mở `/docs` trên tên miền UAT được cấp

Đọc tiếp

Trang	Nội dung nên đọc tiếp
Xác thực bằng API key	Quy chuẩn truyền khoá và quản lý API key giữa các môi trường
Bắt đầu: từ số 0 tới booking đầu tiên	10 bước kiểm thử an toàn trên môi trường UAT
Xuất vé	Chi tiết quy trình xử lý xuất vé điện tử với các hãng tàu
Trước khi chạy thật	Checklist kiểm tra kỹ thuật trước khi chuyển sang Production