Trước khi chạy thật

Trước khi chuyển sang môi trường vận hành thực tế (Production), hệ thống của đối tác cần hoàn thành các tiêu chí nghiệm thu về kết nối, kiểm thử nghiệp vụ, phòng ngừa rủi ro dữ liệu và giám sát vận hành. Trang này cung cấp danh sách kiểm tra súc tích, có thể hành động ngay, giúp đối tác tự đánh giá mức độ sẵn sàng trước ngày mở kết nối.

Điểm chính

• Môi trường UAT của Ferry thực hiện xuất vé thật và trừ tiền thật trên tài khoản đại lý; kiểm thử trên UAT có giá trị nghiệm thu thực tế cao.
• Ferry không có cơ chế khoá chống lặp (idempotency key); đối tác bắt buộc phải tự cài đặt lớp chặn gửi trùng và kiểm tra trước khi gọi lại sau timeout.
• Webhook không có chữ ký số và không có thử lại; đối tác phải dùng HTTPS, phản hồi dưới 2 giây và duy trì tác vụ đối chiếu định kỳ hàng ngày.
• Bốn cửa nghiệm thu cần hoàn thành lần lượt: Kết nối an toàn, Luồng nghiệp vụ trọn vẹn, Cơ chế chống lỗi, và Giám sát cảnh báo từ ngày đầu.

Bốn cửa nghiệm thu

Bốn cửa đi theo thứ tự tuần tự. Cửa sau chỉ có ý nghĩa khi cửa trước đã hoàn thành: kết nối thông suốt mới thử được nghiệp vụ, hiểu rõ nghiệp vụ mới biết cách phòng chống sai sót, và có cơ chế chống sai thì giám sát mới phát huy tác dụng.

Sơ đồ dưới đây cho thấy bốn cửa nghiệm thu tuần tự trước khi đưa hệ thống vào chạy thật:

flowchart LR
    K["Cửa 1 — Kết nối"] --> K1["Khoá thật chỉ lưu trong kho bí mật"]
    K --> K2["Base URL chốt bằng văn bản"]
    K1 --> N["Cửa 2 — Nghiệp vụ"]
    K2 --> N
    N --> N1["Chạy trọn 1 đơn thật trên UAT"]
    N --> N2["Nắm danh sách hãng xuất vé tự động"]
    N1 --> C["Cửa 3 — Chống sai"]
    N2 --> C
    C --> C1["Chặn tạo trùng phía bạn"]
    C --> C2["Kiểm tra trạng thái khi timeout"]
    C1 --> G["Cửa 4 — Giám sát"]
    C2 --> G
    G --> G1["Đối chiếu định kỳ mỗi ngày"]
    G --> G2["Cảnh báo im lặng bất thường"]

Danh sách kiểm tra nghiệm thu

Cửa 1 — Kết nối và bảo mật

• Bảo vệ khoá bí mật: Khoá API môi trường thật chỉ lưu trong kho bí mật (Secret Manager / biến môi trường bảo mật), không lưu trong mã nguồn, không đưa vào file build client.
• Xác nhận Base URL: Đã xác nhận chính thức địa chỉ Base URL môi trường thật từ văn bản của Ferry, không dùng phỏng đoán.
• Tách biệt cấu hình UAT và Production: Khoá API hai môi trường được gắn nhãn phân biệt rõ ràng trong cấu hình để tránh gọi nhầm môi trường.
• Quy trình xoay khoá: Đã diễn tập quy trình xoay khoá (tạo khoá mới, nạp vào hệ thống, kiểm tra lưu lượng chạy ổn định rồi mới yêu cầu thu hồi khoá cũ).

Khoá không có hạn dùng và không có thông báo trước khi bị thu hồi. Thu hồi có hiệu lực tức thì, không hoàn tác; thống nhất đầu mối xử lý sự cố khoá trước khi mở bán.

Cửa 2 — Luồng nghiệp vụ và hãng tàu

• Chạy trọn vẹn đơn thật trên UAT: Đã hoàn thành một vòng đời booking, gồm một tình huống lỗi có kiểm soát, và xác nhận vé thật trên hệ thống của đúng hãng đã thử.
• Nắm rõ danh sách hãng hỗ trợ xuất vé tự động: Xác định hãng tàu nào xuất vé tự động qua API và hãng nào yêu cầu quy trình hỗ trợ riêng.
• Xử lý tình huống xuất vé một phần: Ứng dụng phía bạn có cơ chế xử lý khi đơn hàng khứ hồi hoặc nhiều chặng chỉ xuất vé thành công một phần.
• Kiểm tra công thức tính giá: Đối chiếu công thức tính giá bán khách cuối và giá NET của đại lý, đảm bảo khớp hoàn toàn giữa hai hệ thống.

Cửa 3 — Phòng ngừa sai sót dữ liệu

• Chặn tạo đơn trùng lặp phía bạn: Đã thử gửi hai lần liên tiếp và xác nhận chỉ có một booking; không chỉ kiểm tra rằng nút bấm đã bị khoá.
• Quy trình xử lý timeout an toàn: Khi lệnh tạo đơn gặp sự cố timeout mạng, luôn gọi API tra cứu trạng thái trước thay vì gửi lệnh tạo mới ngay lập tức.
• Khử trùng lặp webhook: Điểm tiếp nhận webhook có cơ chế khử trùng lặp theo mã tài nguyên và loại sự kiện.
• Xử lý an toàn với danh sách rỗng: Không dùng kết quả danh sách rỗng từ API để tự động huỷ hay xoá dữ liệu trên hệ thống của bạn.

Cửa 4 — Giám sát và vận hành

• Bật tác vụ đối chiếu định kỳ: Thiết lập lịch chạy tự động đối soát trạng thái đơn hàng và giao dịch giữa hai hệ thống hàng ngày.
• Kiểm tra điểm nhận webhook: Điểm nhận webhook chạy HTTPS, phản hồi HTTP 200 dưới 2 giây và đã nhận thử thành công sự kiện thật.
• Cảnh báo im lặng bất thường: Đặt cảnh báo khi hệ thống không nhận được sự kiện hoặc đơn hàng nào trong khoảng thời gian dài bất thường.
• Lưu trữ mã truy vết (trace ID): Ghi mã truy vết, mã đơn và mã lỗi cho mọi yêu cầu thất bại; giữ tối thiểu một tháng để phục vụ tra soát.
• Cảnh báo danh sách rỗng bất thường: Báo động khi một truy vấn vốn luôn có dữ liệu bỗng trả rỗng, kể cả khi HTTP vẫn là 200.

Những thứ phải giám sát từ ngày đầu

Bốn tín hiệu vận hành đối tác bắt buộc phải theo dõi liên tục:

1. Trạng thái đơn hàng là chốt chặn: Webhook là tín hiệu báo tin, tra cứu API trạng thái đơn hàng là nguồn dữ liệu chuẩn. Tác vụ đối chiếu định kỳ sẽ tự động bù đắp các sự kiện webhook bị rơi rớt.
2. Đơn tự đổi trạng thái không qua lệnh gọi: Hệ thống nền của Ferry tự động quét các đơn đã thanh toán để đối soát với hãng tàu và cập nhật thành công. Đơn hàng có thể tự chuyển sang trạng thái đã xuất vé sau vài phút mà không cần lệnh gọi từ phía bạn.
3. Độ trễ khi xác nhận xuất vé: Quá trình kết nối xuất vé với một số cổng hãng tàu có thể kéo dài vài phút. Cần cấu hình timeout phía bạn đủ dài và theo dõi độ trễ thực tế để kịp thời phát hiện hãng tàu bị chậm.
4. Số dư và tỷ lệ lỗi nghiệp vụ: Giám sát số dư khả dụng của tổ chức và tỷ lệ phát sinh các mã lỗi sáu chữ số để nạp tiền kịp thời trước khi đơn hàng bị từ chối vì thiếu số dư.

Giới hạn tần suất chung tính theo địa chỉ IP, không có hạn mức riêng theo API key hoặc tổ chức. Theo dõi cả lỗi 429 và lỗi nghiệp vụ theo mã. Với một số hãng, xác nhận xuất vé có thể kéo dài 5–8 phút; không coi timeout là kết luận đơn thất bại.

Khác biệt giữa môi trường UAT và Thật

Hạng mục	Môi trường UAT	Môi trường Thật (Production)	Thao tác cần làm khi chuyển đổi
Base URL	Thường là api.ferryvn.net	api.ferry.vn	Đổi biến môi trường theo văn bản xác nhận chính thức từ Ferry
Kết nối hãng tàu	11 hãng bị chặn đăng nhập trên UAT	Không áp dụng danh sách chặn đăng nhập này	Kiểm thử các hãng cần dùng; có thể hẹn Ferry mở tạm trên UAT trước ngày chạy thật
Tác vụ cân đối công nợ	Chạy thử nghiệm không ghi sổ thật	Chạy tự động và ghi sổ thật	Bật tác vụ đối chiếu định kỳ trước ngày chạy thật để phát hiện lệch
Khoá API	Khoá UAT (cùng tiền tố ferry_)	Khoá thật (cùng tiền tố ferry_)	Phân tách rõ ràng khoá trong cấu hình bảo mật

Khác biệt lớn nhất giữa UAT và môi trường thật là quy mô và tiền thật

UAT của Ferry đã thực hiện xuất vé thật và trừ tiền thật trên tài khoản đại lý. Sự khác biệt lớn nhất khi lên môi trường thật là quy mô đơn hàng và tiền thật của hành khách.

Hai cơ chế phòng vệ không thể bỏ qua: chặn tạo đơn trùng lặp và duy trì tác vụ đối chiếu định kỳ. Nếu thiếu hai cơ chế này, sự cố gián đoạn mạng vào giờ cao điểm sẽ dẫn đến việc tạo đơn trùng hoặc bỏ sót trạng thái đơn hàng của khách.

Danh sách 11 hãng bị chặn đăng nhập trên UAT: mailinhexpress, superdong, phuquocexpress, lightning68, hoabinhship, phuquyexpress, greenlines, cangsaky, hangchautourist, chankhaluxury, saigonwatergo. Phân biệt danh sách chặn đăng nhập này với danh sách hãng chưa hỗ trợ xuất vé tự động.

Sai lầm thường gặp

Hiểu nhầm	Thực tế	Hệ quả
Môi trường UAT là sandbox giả lập	UAT đã xuất vé thật trên cổng hãng	Mỗi lần thử nghiệm sai tiêu tiền thật của đại lý
Lên thật chỉ cần thay Base URL	Danh sách hãng mở trên Production rộng hơn UAT	Lỗi kết nối hãng chỉ phát sinh khi lên thật nếu chưa kiểm thử trước
Chờ Ferry cung cấp khoá chống lặp	Ferry không có khoá chống lặp cho lệnh tạo đơn	Gửi lại sau timeout tạo hai đơn và trừ tiền hai lần
Webhook là nguồn dữ liệu duy nhất	Webhook không thử lại, quá 2 giây là mất	Đơn hàng bị treo trạng thái mà không ai phát hiện
Khoá API không có hạn dùng nên không cần xoay	Khoá có thể bị lộ mà không có cảnh báo tự động	Lỗ hổng bảo mật kéo dài không kiểm soát

Tra ở đâu trên Scalar

Giao diện tài liệu API tại https://api.ferry.vn/docs là công cụ kiểm tra cuối cùng trước khi chạy thật. Bạn nên dùng khoá thật gọi thử một lệnh đọc dữ liệu trên đúng tên miền môi trường thật:

Mục tiêu kiểm tra	Nhóm trên giao diện API
Gọi thử lệnh đọc để xác nhận khoá API thật hoạt động	Voyage
Tra cứu trạng thái booking để đối soát	Bookings
Tra cứu thông tin chi tiết đơn hàng khi đối chiếu	Order
Lịch sử giao dịch để đối soát số dư ví và thanh toán	Payment
Thông tin tổ chức liên kết với khoá API	Organizations

Đọc tiếp

Trang	Đọc khi nào
Tổng quan bề mặt tích hợp	Nắm rõ toàn cảnh các nhóm chức năng và ranh giới gọi API
Môi trường	So sánh chi tiết hai môi trường trước khi chuyển đổi cấu hình
Xác thực	Quy trình xoay khoá và phân quyền khoá API
Quy ước chung	Nhắc lại quy ước về dữ liệu và cơ chế xử lý trùng lặp
Lỗi và cách xử lý	Tra cứu bảng mã lỗi nghiệp vụ và hướng dẫn xử lý
Giới hạn	Cấu hình tần suất gọi và giám sát mã lỗi 429
Webhooks	Thiết lập điểm nhận sự kiện và xử lý bất đồng bộ
Đặt vé: vòng đời một booking	Rà soát toàn bộ vòng đời đơn hàng trước khi nghiệm thu

Điểm chưa xác định

• Cam kết chất lượng dịch vụ (SLA): Ferry chưa công bố văn bản cam kết thời gian khả dụng và thời hạn xử lý sự cố chính thức. Đối tác cần thỏa thuận kênh tiếp nhận sự cố khẩn cấp và khung giờ hỗ trợ kỹ thuật trước ngày mở bán.
• Xác nhận chính thức Base URL: Base URL cần được xác nhận bằng văn bản chính thức từ đại diện Ferry trước ngày kích hoạt lưu lượng thật.
• Ngưỡng thời gian cảnh báo im lặng: Ngưỡng cảnh báo X phút phụ thuộc vào lượng đơn hàng thực tế của từng đối tác; bạn nên thiết lập linh hoạt theo mùa cao điểm và thấp điểm.