Tổng quan bề mặt tích hợp

8 phút đọc

Trang này xác định phạm vi kết nối giữa hệ thống của đối tác và nền tảng Ferry. Bạn sẽ nắm rõ những nhóm nghiệp vụ nào có thể gọi bằng API key, các khu vực nội bộ không thể truy cập, và nguyên tắc phân quyền trên toàn hệ thống.

Các tầng API trong hệ thống

Hệ thống backend của Ferry phân tách bề mặt API thành 4 tầng riêng biệt tuỳ theo đối tượng gọi và phương thức xác thực:

Tầng API	Đối tượng sử dụng	Phương thức xác thực	Phạm vi đối tác
`public`	Khách truy cập web, ứng dụng di động, đối tác	Không yêu cầu xác thực	Gọi được danh mục tuyến, bến và hãng tàu
`partner`	Đối tác B2B tích hợp hệ thống	API key trong header `Authorization`	Tầng chính dành cho đối tác với 86 route nghiệp vụ
`internal`	Nhân viên vận hành đại lý và nhân viên Ferry	JWT của tài khoản đăng nhập	Không truy cập được qua API key
`admin`	Đội ngũ quản trị kỹ thuật hệ thống Ferry	JWT mang vai trò quản trị viên cấp cao	Không truy cập được qua API key

Sơ đồ dưới đây cho thấy các tầng API và phạm vi truy cập của đối tác:

flowchart LR
    subgraph callers["Chủ thể gọi"]
        partner["Đối tác B2B<br/>kèm API key"]
        guest["Khách vãng lai<br/>không xác thực"]
        dashboard["Nhân viên vận hành<br/>kèm JWT"]
    end
    subgraph reachable["Vùng đối tác truy cập"]
        tierpublic["Tầng public<br/>Danh mục dùng chung"]
        tierpartner["Tầng partner<br/>86 route nghiệp vụ"]
    end
    subgraph blocked["Vùng nội bộ đóng"]
        tierinternal["Tầng internal<br/>Yêu cầu JWT người dùng"]
        tieradmin["Tầng admin<br/>Yêu cầu JWT quản trị hệ thống"]
    end
    guest --> tierpublic
    partner --> tierpublic
    partner --> tierpartner
    dashboard --> tierinternal

Tầng partner khai báo 112 route, nhưng chỉ có 87 route được cấu hình cơ chế kiểm tra API key, trong đó 1 route yêu cầu thêm quyền quản trị viên nội bộ cấp cao. Vì vậy, chính xác 86 route là bề mặt đối tác thực sự có thể gọi bằng API key (các route còn lại là công cụ nội bộ của Ferry như kiểm tra cổng hãng tàu hay ép đồng bộ dữ liệu).

Tầng public gồm 9 route không yêu cầu xác thực. Cả hai tầng này đều xuất hiện trên giao diện tài liệu công khai tại /docs. Đối với các danh mục dùng chung như tuyến đường, bến tàu và hãng tàu, hệ thống không có endpoint riêng có xác thực — đối tác bắt buộc phải gọi trực tiếp vào các route công khai mà không truyền khoá.

Các nhóm nghiệp vụ mở cho đối tác

Toàn bộ 86 route nghiệp vụ dành cho đối tác được phân bổ vào các nhóm chức năng chính sau:

Nhóm nghiệp vụ	Năng lực chính	Hướng dẫn chi tiết
Tra cứu lịch chạy	Tìm chuyến theo tuyến và ngày, kiểm tra lịch tàu, lấy chi tiết chuyến	Tra cứu chuyến
Sơ đồ ghế và chỗ trống	Lấy sơ đồ khoang ghế, kiểm tra số lượng chỗ còn khả dụng theo chuyến	Tra cứu chuyến
Đặt vé và quản lý đơn	Tạo booking giữ chỗ, xác nhận xuất vé điện tử, tra cứu và cập nhật booking	Luồng đặt vé
Tra cứu đơn hàng (Orders)	Liệt kê và xem chi tiết đơn hàng (chỉ đọc); không tạo hay xuất vé qua nhóm này	Xuất vé
Huỷ vé	Tạo yêu cầu huỷ vé và theo dõi trạng thái tiếp nhận xử lý từ hãng	Huỷ vé và hoàn tiền
Khách hàng và công ty	Tạo hồ sơ khách hàng, cập nhật thông tin và quản lý danh sách công ty	Tra cứu tại Scalar, nhóm `Customers`
Giá vé và ưu đãi	Kiểm tra quy tắc phụ thu, chính sách giá và kiểm tra điều kiện áp dụng voucher	Giá và markup
Dòng tiền và công nợ	Kiểm tra số dư ký quỹ đại lý, tra cứu sổ công nợ và lịch sử giao dịch	Thanh toán và số dư
Quản lý tổ chức con	Tạo, cập nhật và có quyền xoá tổ chức con thuộc chuỗi đại lý	Xác thực bằng API key
Thông báo và sự kiện	Đăng ký địa chỉ webhook nhận thông báo trạng thái, gửi email đơn hàng	Webhooks

Các vùng không mở cho đối tác

Để đảm bảo an toàn vận hành, hệ thống khoá hoàn toàn các khu vực sau đối với yêu cầu gửi bằng API key:

Khu vực đóng	Lý do kỹ thuật	Phương thức thay thế
Toàn bộ tầng `internal` và `admin`	Yêu cầu xác thực phiên người dùng bằng JWT	Thao tác trên giao diện Dashboard
Kênh dữ liệu thời gian thực (SSE)	Yêu cầu phiên JWT của người dùng trực tuyến	Sử dụng Webhook hoặc cơ chế polling định kỳ
Quản lý hoá đơn điện tử	Endpoint tầng partner bị đóng hoàn toàn	Nhận webhook sự kiện, xem chi tiết qua Dashboard
Gửi tin nhắn Zalo ZNS cho booking	Luôn trả về 403 Forbidden do lược đồ phân quyền thiếu vai API key	Tự gửi tin qua Zalo OA của đối tác
Tạo mới và cấp phát API key	Chỉ tài khoản quản trị đại lý thao tác trên Dashboard	Quản trị viên đại lý tạo tại API Keys
Tìm kiếm toàn cục	Chỉ dành cho nhân viên vận hành trên giao diện	Tra cứu theo từng thực thể cụ thể (chuyến, đơn vé, khách)

Lưu ý thêm: Endpoint danh sách booking (GET /api/v1/bookings) trả về header cảnh báo sắp ngừng dùng khi truyền bộ lọc động và hiện chưa có route thay thế ở tầng partner.

Quyền hạn và phạm vi của API key

API key của Ferry gắn liền với một tổ chức đại lý cụ thể. Khi gọi API bằng khoá này, toàn bộ hành động và dữ liệu tạo ra đều thuộc quyền sở hữu của tổ chức đó.

Hệ quả quan trọng đối tác cần lưu ý:

Bảo mật phía máy chủ: Tuyệt đối không nhúng API key vào mã nguồn ứng dụng di động, giao diện web chạy trên trình duyệt hoặc các tệp tin công khai.
Rủi ro xoá tổ chức con: Quyền hạn của khoá bao gồm cả việc xoá các tổ chức con thuộc chuỗi đại lý. Một khoá bị lộ có thể bị kẻ xấu lợi dụng để xoá tổ chức con hoặc can thiệp sâu vào giao dịch và khách hàng.
Xử lý khi lộ khoá: Khi nghi ngờ khoá bị lộ, bạn cần lập tức thu hồi khoá cũ và tạo khoá mới trên Dashboard theo quy trình xoay khoá an toàn.

Sai lầm thường gặp

Hiểu nhầm	Thực tế	Cách xử lý đúng
Nghĩ rằng mọi route trên tài liệu đều gọi được bằng API key	Tài liệu công khai chứa cả route không cần xác thực và một số route yêu cầu quyền quản trị	Đối chiếu với danh mục 86 route của tầng partner
Tìm kiếm endpoint danh mục tuyến, bến, hãng tàu bằng API key	Danh mục dùng chung chỉ có ở tầng public không cần xác thực	Gọi trực tiếp các route public không kèm header `Authorization`
Cố gắng gửi tin nhắn Zalo ZNS qua API Ferry	Luôn nhận 403 Forbidden do chưa hỗ trợ vai trò API key	Tự xây dựng luồng gửi ZNS từ hệ thống của đối tác
Cố gắng đọc chi tiết hoá đơn qua API sau khi nhận webhook	Endpoint hoá đơn ở tầng partner bị đóng hoàn toàn	Theo dõi và tra cứu hoá đơn trên giao diện Dashboard
Xuất vé qua nhóm Tra cứu đơn (Orders)	Nhóm Orders chỉ hỗ trợ đọc thông tin đơn	Thực hiện toàn bộ quy trình đặt và xuất vé qua nhóm Bookings
Nhúng API key vào ứng dụng di động của người dùng cuối	Bất kỳ ai giải nén ứng dụng đều có thể lấy được API key	Mọi lệnh gọi tới Ferry phải đi qua máy chủ backend của đối tác
Tìm kiếm endpoint tạo API key bằng code	Quyền tạo khoá chỉ mở cho quản trị viên trên Dashboard	Quản trị viên đại lý tạo khoá thủ công trên Dashboard
Cố gắng kết nối vào luồng SSE bằng API key	Kênh SSE yêu cầu phiên JWT	Đăng ký webhook để nhận sự kiện đổi trạng thái đơn hàng

Tra ở đâu trên Scalar

Trang tài liệu này định vị các nhóm chức năng trên giao diện tài liệu tương tác Scalar UI — Ferry VN API:

Nhóm nghiệp vụ cần tra cứu	Tên nhóm hiển thị trên Scalar
Chuyến, sơ đồ ghế và số lượng chỗ	`Voyages`, `Boat Layout`, `Voyage Counts`
Đặt chỗ và chi tiết đơn hàng	`Bookings`, `Orders`
Phụ thu giá và mã giảm giá	`Ticket Price Additions`, `Vouchers`
Giao dịch thanh toán và công nợ	`Transactions`, `Debt Ledgers`
Hồ sơ khách hàng, đối tác và tổ chức	`Customers`, `Companies`, `Organizations`
Danh mục tuyến, bến và hãng tàu (công khai)	`Routes`, `Locations`, `Operators`

Đọc tiếp

Trang	Nội dung nên đọc tiếp
Bắt đầu: từ số 0 tới booking đầu tiên	10 bước thực hành từ chuẩn bị khoá đến xuất vé thành công
Môi trường	Tìm hiểu về môi trường UAT và Production trước khi gọi API
Xác thực bằng API key	Quy chuẩn truyền header, định dạng khoá và quy trình xoay khoá
Quy ước chung	Quy định về phân trang, định dạng thời gian và xử lý lỗi