Tài liệu dành cho Nhà phát triển

4 phút đọc

Khu vực này dành cho lập trình viên và đối tác kỹ thuật tích hợp hệ thống bán vé tàu thuỷ Ferry qua API. Bạn sẽ tìm thấy các hướng dẫn kết nối, quy ước tích hợp, quy trình nghiệp vụ và đường dẫn tới tài liệu API tham chiếu.

Lộ trình đọc tài liệu

Tuỳ theo mục tiêu công việc, bạn có thể tra cứu nhanh các trang tương ứng trong bảng dưới đây:

Mục tiêu tích hợp	Trang nên đọc	Nội dung chính
Hiểu phạm vi và năng lực API	Tổng quan bề mặt tích hợp	Các nhóm nghiệp vụ mở cho đối tác, quyền hạn của API key và ranh giới tích hợp
Bắt đầu tích hợp từ số 0	Bắt đầu: từ số 0 tới booking đầu tiên	Checklist từng bước từ khi nhận key đến khi xuất vé đầu tiên thành công
Cấu hình môi trường kết nối	Môi trường	Địa chỉ kết nối, lưu ý kiểm thử trên UAT và danh sách hãng tàu hỗ trợ
Xác thực và quản lý API key	Xác thực bằng API key	Cách gửi key, định dạng key, quy trình xoay key an toàn và xử lý lỗi xác thực
Nắm vững quy ước kỹ thuật chung	Quy ước chung	Phân trang con trỏ, giới hạn tải, định dạng ngày giờ, tiền tệ và xử lý trùng lặp
Tra cứu schema và gọi thử endpoint	API Reference	Cổng kết nối tới tài liệu tương tác Scalar sống của hệ thống Ferry
Tra cứu lịch chạy và chỗ trống	Tra cứu chuyến	Tìm chuyến theo tuyến và ngày, lấy sơ đồ ghế và kiểm tra số chỗ còn trống
Tính toán giá vé và chiết khấu	Giá và markup	Cấu trúc giá vé, phụ thu, chiết khấu và quy tắc áp dụng voucher
Triển khai luồng đặt vé	Luồng đặt vé	Vòng đời đơn từ tạo booking đến xác nhận xuất vé và chốt trạng thái
Quản lý số dư và thanh toán	Thanh toán và số dư	Theo dõi số dư ký quỹ đại lý, hạn mức công nợ và lịch sử giao dịch
Xác nhận xuất vé điện tử	Xuất vé	Quy trình xác nhận xuất vé với hãng tàu và nhận file vé điện tử
Xử lý huỷ vé và hoàn tiền	Huỷ vé và hoàn tiền	Quy trình gửi yêu cầu huỷ vé và chính sách hoàn tiền
Nhận thông báo tự động	Webhooks	Đăng ký webhook để nhận sự kiện thay đổi trạng thái đơn hàng theo thời gian thực
Xử lý mã lỗi và sự cố	Lỗi và cách xử lý	Bảng mã lỗi chuẩn và chiến lược thử lại khi gặp sự cố mạng
Tuân thủ giới hạn tần suất gọi	Giới hạn	Hạn mức gọi API và cách xử lý khi chạm ngưỡng
Chuẩn bị đưa hệ thống vào vận hành	Trước khi chạy thật	Checklist kiểm tra an toàn kỹ thuật trước khi chuyển sang môi trường Production

Tài liệu API tương tác (Scalar)

Đặc tả kỹ thuật chi tiết của từng endpoint, cấu trúc dữ liệu yêu cầu/phản hồi và công cụ thử nghiệm trực tiếp trên trình duyệt được cung cấp tại cổng tài liệu Scalar UI — Ferry VN API.

Các nhóm nghiệp vụ chính trên Scalar tương ứng với tài liệu gồm: Voyages (tra cứu chuyến), Boat Layout (sơ đồ ghế), Bookings (đặt vé), Transactions và Debt Ledgers (dòng tiền và công nợ), Organizations (cấu hình tổ chức và webhook).

Tài liệu liên quan

Tài liệu dành cho Đại lý: Hướng dẫn thao tác giao diện Dashboard dành cho nhân viên bán vé và quản trị viên đại lý.
Developer Documentation (English): Bản tiếng Anh dành cho lập trình viên và đối tác quốc tế.