Bắt đầu: từ số 0 tới booking đầu tiên

9 phút đọc

Trang này là bản hướng dẫn từng bước (checklist) dành cho lập trình viên để triển khai tích hợp từ đầu đến khi hoàn tất đơn vé đầu tiên. Thực hiện tuần tự các bước dưới đây giúp bạn nhanh chóng thông luồng nghiệp vụ và tránh các sự cố gián đoạn dịch vụ.

Tiến trình 10 bước tích hợp

Sơ đồ dưới đây cho thấy tiến trình 10 bước từ khi chuẩn bị đến lúc xuất vé đầu tiên:

flowchart TB
    subgraph prep["Giai đoạn chuẩn bị"]
        s1["1. Xác định vị trí tổ chức trong chuỗi"]
        s2["2. Nhận API key từ quản trị viên"]
        s3["3. Lưu khoá bảo mật và gắn header"]
        s4["4. Chọn môi trường và nhận base URL"]
    end
    subgraph query["Giai đoạn đọc dữ liệu"]
        s5["5. Gọi thử lệnh tra cứu chuyến tàu"]
        s6["6. Tra cứu sơ đồ ghế và chỗ trống"]
        s7["7. Kiểm tra giá vé và voucher"]
    end
    subgraph trans["Giai đoạn giao dịch"]
        s8["8. Nạp đủ số dư ký quỹ đại lý"]
        s9["9. Tạo booking giữ chỗ"]
        s10["10. Xác nhận xuất vé và theo dõi trạng thái"]
    end
    s1 --> s2 --> s3 --> s4 --> s5 --> s6 --> s7 --> s8 --> s9 --> s10

Chi tiết từng bước thực hiện

Bước 1 — Xác định vị trí của tổ chức trong chuỗi đại lý

Việc cần làm: Trao đổi với đầu mối phụ trách của Ferry để xác nhận thông tin tổ chức đại lý của bạn trên hệ thống. Xác định rõ tổ chức cha trực tiếp trong chuỗi đại lý để nắm được chính sách giá, chiết khấu và đầu mối chuyển tiền nạp số dư.

Dấu hiệu hoàn tất: Bạn có mã tổ chức, biết rõ tổ chức cha trực tiếp và mức giá áp dụng cho đại lý của mình.

Bước 2 — Nhận API key từ quản trị viên đại lý

Việc cần làm: Đối tác không thể tự tạo khoá bằng API. Người dùng có vai trò quản trị viên (admin) của đại lý cần đăng nhập vào Dashboard, truy cập mục Cài đặt > API Keys để tạo mới khoá và chuyển chuỗi khoá an toàn cho đội ngũ kỹ thuật. Thao tác chi tiết xem tại Quản lý API Key trên Dashboard.

Dấu hiệu hoàn tất: Nhận được chuỗi API key hoàn chỉnh. Chuỗi khoá này chỉ hiển thị một lần duy nhất lúc tạo và không thể xem lại.

Khoá chỉ được cấp cho tổ chức đã có hợp đồng hợp tác. Khoá không tự hết hạn; thu hồi là xoá cứng, có hiệu lực tức thì và không hoàn tác được.

Bước 3 — Lưu khoá an toàn và cấu hình header xác thực

Việc cần làm: Lưu chuỗi API key vào kho quản lý biến môi trường bảo mật trên máy chủ backend của bạn. Cấu hình HTTP client gửi kèm header Authorization: Bearer <API_KEY> trong mọi yêu cầu gọi tới Ferry.

Dấu hiệu hoàn tất: Mã nguồn phía máy chủ đọc được khoá từ biến môi trường. Tuyệt đối không để chuỗi khoá xuất hiện trong kho lưu trữ mã nguồn (git) hoặc trong ứng dụng client.

Ferry chỉ đọc khoá qua Authorization; header X-API-Key không có tác dụng. Không để khoá xuất hiện trong log hoặc biến được nhúng vào bản build phía client.

Bước 4 — Chọn môi trường và xác nhận base URL

Việc cần làm: Yêu cầu đội ngũ Ferry cung cấp base URL chính thức bằng văn bản cho môi trường UAT. Đọc kỹ cảnh báo: môi trường UAT kết nối trực tiếp với cổng hãng tàu và xuất vé thật. Hãy thống nhất trước với Ferry về chuyến tàu thử nghiệm để tránh phát sinh chi phí ngoài ý muốn.

Dấu hiệu hoàn tất: Có base URL của môi trường kiểm thử và danh sách chuyến tàu được chỉ định để thử nghiệm.

Riêng CangSaKy vẫn đặt vé thật ngay cả khi chế độ xuất vé thật của môi trường bị tắt. Chốt trước với Ferry hãng, chuyến và bên chịu chi phí của mỗi lần thử.

Bước 5 — Gọi thử lệnh tra cứu chuyến tàu

Việc cần làm: Gửi yêu cầu GET tới nhóm Voyages để tìm kiếm chuyến tàu theo cặp bến xuất phát, bến đến và ngày khởi hành mong muốn.

Dấu hiệu hoàn tất: Nhận phản hồi HTTP 200 kèm danh sách các chuyến tàu thực tế. Nếu nhận lỗi 401, kiểm tra lại header Authorization và tiền tố Bearer.

HTTP 200 kèm danh sách rỗng có thể là lỗi hệ thống bị che, không chứng minh hết chuyến. Thử cặp bến và ngày chắc chắn có dữ liệu trước khi kết luận. Sắp xếp theo trường khác _id bị thay bằng _id giảm dần; xem Quy ước chung.

Bước 6 — Tra cứu sơ đồ ghế và số chỗ còn trống

Việc cần làm: Sử dụng mã chuyến tàu vừa tìm được để gọi nhóm Boat Layout lấy cấu trúc ghế ngồi và nhóm Voyage Counts để lấy số lượng ghế còn khả dụng theo từng khoang.

Dấu hiệu hoàn tất: Nhận được thông tin chi tiết về các vị trí ghế trống hợp lệ để chuẩn bị cho bước đặt chỗ.

Chỗ trống thay đổi liên tục. Gọi lại Ferry ngay trước khi tạo booking; không dựa vào sơ đồ đã cache lâu hoặc tự suy ra số chỗ còn.

Bước 7 — Kiểm tra giá vé và ưu đãi

Việc cần làm: Gọi nhóm Ticket Price Additions để kiểm tra các khoản phụ thu hoặc quy tắc cộng giá áp dụng, và nhóm Vouchers để kiểm tra mã giảm giá (nếu có).

Dấu hiệu hoàn tất: Xác định được giá bán cuối cùng thu của khách hàng và giá NET đại lý phải thanh toán cho tổ chức cha trực tiếp.

Bước 8 — Nạp đủ số dư ký quỹ đại lý

Việc cần làm: Kiểm tra số dư khả dụng qua nhóm Transactions hoặc Debt Ledgers. Tiến hành nạp tiền theo phương thức thanh toán của tổ chức cha để số dư khả dụng luôn lớn hơn hoặc bằng tổng giá trị đơn vé sắp tạo.

Dấu hiệu hoàn tất: Số dư khả dụng của đại lý đủ điều kiện để chi trả cho đơn hàng. Tiền sẽ được trừ tự động ở bước xác nhận xuất vé.

Bước 9 — Tạo booking giữ chỗ

Việc cần làm: Gọi nhóm Bookings với thông tin chuyến, danh sách vị trí ghế và thông tin hành khách để tạo đơn giữ chỗ.

Dấu hiệu hoàn tất: Lưu được mã booking, trạng thái Đã gửi yêu cầu (2), trạng thái thanh toán Chưa trả (1) và mốc payment_expired_at. Ghế mới được đánh dấu trong Ferry, chưa được giữ trên hệ thống hãng tàu.

Bước 10 — Xác nhận xuất vé và theo dõi trạng thái

Việc cần làm: Gọi POST /bookings/confirmToIssue/{id}, rồi poll GET /bookings/{id} để xác nhận kết quả. Webhook chỉ là tín hiệu: không có chữ ký, không gửi lại và hết thời gian chờ sau 2 giây; không dùng webhook thay cho polling.

Dấu hiệu hoàn tất: Booking chuyển sang Đã có vé (10); sau đó tải vé gửi khách.

Với một số hãng, xác nhận có thể mất 5–8 phút. Timeout không chứng minh thất bại; lỗi đang xử lý cũng không phải lý do huỷ đơn. Booking đã trả tiền có thể tự chuyển sang 10 sau vài phút nhờ đối chiếu nền. Không vội huỷ hoặc tạo đơn thay thế; xem Luồng đặt vé và Giới hạn tần suất trước khi gọi lại.

Bảng tổng hợp 10 bước

Bước	Nơi thực hiện	Nhóm API liên quan	Dấu hiệu hoàn thành
1	Trao đổi với Ferry	Không dùng API	Xác định được tổ chức cha và chính sách giá
2	Dashboard đại lý	Không dùng API	Nhận chuỗi API key hợp lệ
3	Máy chủ của bạn	Không dùng API	Khoá được lưu trong kho bí mật và gắn header Bearer
4	Trao đổi với Ferry	Không dùng API	Nhận base URL UAT và chuyến thử nghiệm được duyệt
5	Máy chủ của bạn	`Voyages`	Nhận danh sách chuyến tàu thực tế (HTTP 200)
6	Máy chủ của bạn	`Boat Layout`, `Voyage Counts`	Lấy được sơ đồ ghế và vị trí ghế trống hợp lệ
7	Máy chủ của bạn	`Ticket Price Additions`, `Vouchers`	Xác định giá khách trả và giá đại lý thanh toán
8	Chuyển khoản nạp tiền	`Transactions`, `Debt Ledgers`	Số dư ký quỹ khả dụng đủ chi trả cho đơn hàng
9	Máy chủ của bạn	`Bookings`	Booking được tạo thành công kèm thời hạn giữ chỗ
10	Máy chủ của bạn	`Bookings`	Trạng thái đơn hoàn tất và nhận thông tin vé điện tử

Sai lầm thường gặp

Hiểu nhầm	Thực tế	Cách xử lý đúng
Thử nghiệm xuất vé tự do trên UAT	UAT kết nối trực tiếp hãng tàu và trừ tiền thật	Chỉ thử xuất vé trên các chuyến đã thoả thuận trước với Ferry
Tự động thử lại khi tạo booking bị timeout	Lệnh tạo booking không tự động chống lặp	Tra cứu lại danh sách booking trước khi quyết định gọi lại
Chờ trừ tiền ngay khi tạo booking	Tiền chỉ bị trừ khi gọi lệnh xác nhận xuất vé	Đảm bảo số dư khả dụng đủ trước khi gọi lệnh xác nhận
Nhầm lẫn giữa giá bán lẻ và giá thanh toán đại lý	Hai mức giá khác nhau tuỳ theo cấu hình hoa hồng và phụ thu	Luôn đối chiếu giá qua API tính giá trước khi chốt đơn

Tra ở đâu trên Scalar

Các nhóm API cần thiết cho 10 bước được bố trí trên Scalar UI — Ferry VN API:

Bước trong quy trình	Nhóm chức năng trên Scalar
Bước 5: Tra cứu lịch chạy	`Voyages`
Bước 6: Sơ đồ ghế và chỗ trống	`Boat Layout`, `Voyage Counts`
Bước 7: Phụ thu và mã giảm giá	`Ticket Price Additions`, `Vouchers`
Bước 8: Dòng tiền và công nợ	`Transactions`, `Debt Ledgers`
Bước 9 và 10: Đặt chỗ và xuất vé	`Bookings`, `Orders`

Đọc tiếp

Trang	Nội dung nên đọc tiếp
Môi trường	Đọc chi tiết quy định và khác biệt hành vi trên môi trường UAT
Xác thực bằng API key	Quy chuẩn truyền khoá, vòng đời và cách xoay khoá an toàn
Tra cứu chuyến	Hướng dẫn chi tiết tìm kiếm lịch chạy và sơ đồ ghế
Luồng đặt vé	Chi tiết quy trình xử lý đơn hàng từ lúc tạo tới khi hoàn tất