Tham chiếu API

7 phút đọc

Tài liệu tương tác chính thức của Ferry được sinh trực tiếp từ hệ thống máy chủ và cập nhật liên tục tại giao diện Scalar UI. Trang này hướng dẫn bạn cách mở tài liệu, hiểu cách gom nhóm các API nghiệp vụ và cách thử nghiệm gọi API trực tiếp.

Scalar UI — Tài liệu API đối tác Tra cứu lược đồ dữ liệu chi tiết, tham số yêu cầu và thử nghiệm gọi API trực tiếp trên trình duyệt.

Swagger Admin — Tài liệu quản trị hệ thống Dành riêng cho đội ngũ vận hành và quản trị viên hệ thống của Ferry (yêu cầu quyền quản trị).

Ba cổng tài liệu API của Ferry

Hệ thống cung cấp ba cổng tài liệu tương tác phục vụ từng đối tượng tích hợp khác nhau:

Cổng tài liệu	Dành cho ai	Giao diện	Đặc điểm xác thực
`/docs`	Đối tác tích hợp và tra cứu danh mục công khai	Scalar UI	Trộn cả route công khai lẫn route cần API Key
`/internal/docs`	Dashboard Ferry và Dashboard đại lý	Scalar UI	Đòi hỏi JWT người dùng; API Key đối tác không gọi được
`/admin/docs`	Đội ngũ vận hành hệ thống Ferry	Swagger UI	Đòi hỏi quyền quản trị viên nội bộ

Các cổng tài liệu nằm ngay sau tên miền máy chủ API của từng môi trường (ví dụ https://api.ferry.vn/docs). Khi tích hợp trên môi trường thử nghiệm UAT, bạn mở cổng tài liệu trên tên miền UAT tương ứng; xem thêm tại Môi trường.

Vì sao giao diện /docs trộn hai tầng

Bộ tạo tài liệu của hệ thống dùng chung nhãn công khai cho cả tầng dữ liệu danh mục (không cần xác thực) và tầng nghiệp vụ đối tác (cần API Key).

Hệ quả đối tác cần lưu ý trên Scalar:

Không có phân biệt thị giác: Giao diện không có biểu tượng ổ khóa riêng hoặc chia nhóm riêng để nhận biết route nào cần khóa API và route nào mở tự do. Đối tác đối chiếu tại Tổng quan bề mặt tích hợp để nắm ranh giới chính xác.
Thấy trên Scalar chưa chắc gọi được: Một số route hiển thị trên /docs (như nhóm gửi Zalo ZNS) sẽ luôn trả về HTTP 403 đối với khóa API do chưa được cấp quyền cho vai khóa API.
Không thấy trên Scalar chưa chắc không tồn tại: Một số endpoint nếu bị quên gắn nhãn tài liệu có thể vắng mặt trên giao diện nhưng máy chủ vẫn tiếp nhận và xử lý bình thường.

Cách đọc nhóm API trên Scalar

Thay vì tra cứu endpoint rời rạc, bạn nên điều hướng theo các nhóm nghiệp vụ (tag) hiển thị ở mục lục bên trái của Scalar:

Tra cứu chuyến và ghế trống: Nhóm Voyages (tìm chuyến theo bến và ngày, lịch chạy), Boat Layout (sơ đồ ghế và tình trạng từng ghế), Voyage Counts (số lượng chỗ còn trống), Routes (danh mục tuyến), Locations (danh mục bến), Operators (danh sách hãng tàu).
Giá vé và ưu đãi: Nhóm Ticket Price Additions (phụ phí, markup đại lý, kiểm tra phụ phí theo chuyến), Vouchers (kiểm tra và áp dụng mã giảm giá).
Đặt vé và hành khách: Nhóm Bookings (tạo booking mới, xác nhận xuất vé, xem chi tiết booking), Customers (thông tin khách hàng gắn với đơn).
Đơn hàng và vé điện tử: Nhóm Orders (tra cứu thông tin chi tiết từng chặng đơn bên trong booking), Bookings (tải lại tệp vé điện tử đã xuất).
Thanh toán và số dư: Nhóm Transactions (nhật ký biến động số dư và giao dịch), Debt Ledgers (theo dõi công nợ tổ chức), Organizations (hạn mức tín dụng và phương thức nạp tiền).
Hủy vé và hoàn tiền: Nhóm Cancel Ticket Requests (tạo và theo dõi yêu cầu hủy vé).

Xử lý nút Authorize và gọi thử trên Scalar

Mọi endpoint nghiệp vụ dành cho đối tác đều yêu cầu xác thực bằng API Key qua header:

Authorization: Bearer <API_KEY>

Bốn bước xử lý vòng qua khi gặp lỗi xác thực trên Scalar:

Thử nghiệm trên nhóm Voyages trước: Điền khóa vào nút Authorize rồi gọi thử một endpoint tra cứu chuyến. Nếu thành công, khóa API của bạn hoàn toàn chính xác.
Điền header thủ công tại endpoint: Tại các mục bị lỗi 401 (như Bookings), chuyển đến phần Headers của chính endpoint đó trên giao diện Scalar và tự thêm header Authorization với giá trị Bearer <API_KEY>.
Chuyển sang công cụ HTTP độc lập: Sử dụng các công cụ như Postman hoặc mã nguồn client của bạn với header Authorization chuẩn để kiểm tra hành vi thực tế của máy chủ.
Báo Ferry để cập nhật khai báo: Thông báo cho đội ngũ hỗ trợ của Ferry để điều chỉnh lại nhãn bảo mật trên giao diện tài liệu.

Giới hạn của giao diện Scalar

Giới hạn	Thực tế trên giao diện	Hướng dẫn cho đối tác
Tải tệp mô tả OpenAPI	Nút tải tệp đặc tả (JSON/YAML) bị tắt	Liên hệ Ferry nếu cần tệp schema để sinh mã client tự động (SDK)
Tự động sinh mã client	Nút sinh mã mẫu trên giao diện bị tắt	Xây dựng client HTTP dựa trên cấu trúc trường được mô tả
Ghi nhớ phiên làm việc	Tính năng lưu khóa bị tắt ngoài môi trường phát triển	Cần nhập lại API Key mỗi khi tải lại trang trình duyệt

Sai lầm thường gặp

Hiểu nhầm	Thực tế	Hệ quả
Nhập khóa vào Authorize bị 401 nghĩa là khóa hỏng	Tên lược đồ bảo mật bị khai lệch ở nhóm `Bookings`	Yêu cầu cấp lại khóa vô ích, mất thời gian tích hợp
Không thấy endpoint trên Scalar là hệ thống không có	Endpoint quên gắn nhãn tài liệu sẽ vắng mặt trên UI	Đánh giá sai năng lực hệ thống; hãy hỏi trực tiếp Ferry
Thấy endpoint trên Scalar nghĩa là gọi được bằng API Key	Cổng `/docs` gom cả route cần quyền nội bộ đặc thù	Lệnh gọi trả về HTTP 403 do thiếu quyền vai khóa
Cổng `/internal/docs` có thể dùng cho đối tác	Cổng này phục vụ Dashboard và bắt buộc xác thực bằng JWT	Gọi bằng API Key luôn bị từ chối truy cập
Tải tệp OpenAPI spec trực tiếp từ Scalar để sinh SDK	Nút tải tệp đặc tả bị tắt trên giao diện	Cần yêu cầu Ferry cung cấp tệp schema trực tiếp

Đọc tiếp

Trang	Nội dung liên quan
Tổng quan bề mặt tích hợp	Phân biệt ranh giới giữa các tầng API và các nhóm chức năng
Xác thực bằng API key	Quy cách cấp phát, sử dụng và bảo mật API Key
Quy ước chung	Định dạng dữ liệu, phân trang, lọc và quy tắc gọi API
Tra chuyến và chỗ trống	Trình tự tra cứu chuyến và lấy sơ đồ ghế
Luồng đặt vé	Quy trình tạo booking và xác nhận xuất vé hoàn chỉnh