API Ferry VN là REST API để OTA và đối tác công nghệ tra chuyến, tạo booking, xuất vé và nhận webhook của hãng tàu cao tốc qua một giao diện. Kèm SDK TypeScript, CLI và MCP server cho AI agent trên npm.
- hãng tàu
- 15+
- route nghiệp vụ dành cho đối tác
- 86
- trạng thái của một booking
- 8
- mã sự kiện webhook đăng ký được
- 50+
- gói npm: SDK, CLI, MCP
- 3
Số liệu tính đến 11/2026
Đặt vé qua REST API gồm những bước nào?
Bốn bước: tìm chuyến, xem sơ đồ ghế, tạo booking, rồi xác nhận xuất vé. Tạo booking chỉ giữ ghế; tiền chỉ bị trừ theo giá NET khi bạn xác nhận xuất vé.
- POST /bookings tạo booking, POST /bookings/confirmToIssue/{id} xuất vé
- Trạng thái 2 là đã gửi yêu cầu, 10 là đã có vé
- GET /bookings/{id} trả kết quả; một số hãng mất 5–8 phút
- Không có khoá chống lặp: sau timeout, liệt kê booking trước khi tạo lại
- Booking qua API hiện trong Đơn hàng trên Dashboard
API tính giá nhiều cấp và trừ số dư thế nào?
Mỗi đơn có ba mức giá: giá gốc của hãng, giá NET đại lý trả cấp trên và giá khách cuối. Tiền bị trừ tự động theo giá NET, tính lại ngay khi xác nhận xuất vé.
- Phụ phí phần trăm cộng dồn luỹ kế: ba cấp cùng 10% thành 33,1%
- Voucher chỉ giảm giá khách cuối, không giảm giá NET
- POST /ticket-price-additions/check và /vouchers/check-aplicability kiểm tra trước khi tạo booking
- Khả năng chi gồm số dư và hạn mức, kiểm tra cả cấp trên
- Quy tắc phụ phí đặt được trên Dashboard, mục Phí Và Ưu Đãi
Webhook của Ferry hoạt động ra sao?
Khi có sự kiện nghiệp vụ, Ferry gửi POST tới địa chỉ HTTPS bạn khai báo. Hãy coi webhook là tín hiệu: nhận xong, gọi lại API để lấy dữ liệu thật.
- Mã sự kiện như booking.issuedTicket nằm trong header x-event-type
- Hạn phản hồi 2.000 ms; không chữ ký số, không thử lại
- Trả 200 ngay, xếp hàng, khử trùng, đối chiếu định kỳ
- Lọc bằng 6 toán tử; cấu hình trên Dashboard hoặc API
- Bốn mã organization.* đăng ký được nhưng không được phát
SDK TypeScript và CLI ferry dùng như thế nào?
Dùng SDK TypeScript để gọi API trong code, hoặc CLI ferry để tra chuyến và dựng booking từ dòng lệnh. Cả hai dùng API key do quản trị viên đại lý tạo trên Dashboard.
- npm install @ferryvn/sdk; CLI: npm install -g @ferryvn/cli
- SDK chạy trên Node.js 20+, Bun, Deno, Workers; CLI cần Node.js 22.12+
- bookingDrafts kiểm tra loại vé, giá và ghế trống trước khi tạo
- CLI dựng booking từ CSV, xuất vé có xác nhận, xuất báo cáo CSV
- Key hiện một lần, toàn quyền tổ chức; SDK không chạy trên trình duyệt
MCP server cho AI agent làm được và không làm được gì?
AI agent như Claude dùng API key của bạn để tìm chuyến, xem giá, đọc booking và yêu cầu huỷ vé. Mặc định chỉ đọc; xuất vé và thanh toán không bao giờ mở cho agent.
- Ba công cụ ghi chỉ xuất hiện khi đặt FERRY_MCP_ENABLE_WRITES=true
- Mỗi thao tác ghi cần con người xác nhận
- Booking do agent tạo dừng ở trạng thái chưa thanh toán
- Mặc định 20 lệnh ghi mỗi tiến trình, có nhật ký kiểm toán
- Claude Desktop cài bằng .mcpb; Claude Code chạy npx -y @ferryvn/mcp
Sáu bước theo checklist tích hợp.
- 01
Nhận API key
Quản trị viên đại lý tạo key ở Cài Đặt, tab API Keys; chỉ tổ chức đã có hợp đồng hợp tác mới được cấp. Lưu key ở máy chủ, gửi trong header Authorization: Bearer.
- 02
Chọn môi trường
Production là https://api.ferry.vn, endpoint dưới /api/v1/. Ferry cấp base URL UAT bằng văn bản; UAT xuất vé thật và trừ tiền thật, nên chỉ thử xuất vé trên chuyến đã thoả thuận trước.
- 03
Tra chuyến và giá
Tìm chuyến theo bến và ngày, lấy sơ đồ ghế và số chỗ còn, kiểm tra phụ phí và voucher. Gọi lại sơ đồ ghế ngay trước khi tạo booking vì chỗ trống thay đổi liên tục.
- 04
Tạo booking
POST /bookings trả mã booking, trạng thái 2 và hạn thanh toán payment_expired_at. Chưa có khoản tiền nào bị trừ ở bước này.
- 05
Xác nhận xuất vé
POST /bookings/confirmToIssue/{id}, rồi đọc GET /bookings/{id} cho đến khi booking sang trạng thái 10 và tải vé gửi khách.
- 06
Bật webhook và đối chiếu
Khai báo địa chỉ HTTPS trả 200 trong dưới 2 giây, và chạy tác vụ đối chiếu hằng ngày trước khi chạy thật. Checklist đầy đủ có ở trang go-live.
Tìm chuyến và tạo booking nháp bằng @ferryvn/sdk
Tra bến, tìm chuyến, tìm khách hàng và tạo booking nháp; chưa có bước nào trừ tiền. Mã dừng trước bước xuất vé vì UAT cũng đặt vé thật.
Mở API reference (Scalar)import { FerryClient } from '@ferryvn/sdk';
const ferry = new FerryClient({ apiKey: process.env.FERRY_API_KEY, environment: 'uat' });
const [from] = await ferry.locations.find('Rạch Giá');
const [to] = await ferry.locations.find('phu quoc');
const { data: voyages } = await ferry.voyages.search({ date: '2026-11-10', departureId: from.id, destinationId: to.id });
const [customer] = await ferry.customers.search('0901234567');
const { booking, draft } = await ferry.bookingDrafts.create({
customerId: customer.id,
ordererName: 'Nguyễn Văn A',
contactEmail: 'a@example.com',
depart: {
voyageId: voyages[0].voyage.id,
seats: ['A1'],
passengers: [{ name: 'Nguyen Van A', dateOfBirth: '1990-05-01', socialId: '079090000001', homeTown: 'Cần Thơ' }],
},
});
draft.estimatedTotalVnd; // tiền vé + phí bến − voucher| Tự tích hợp từng hãng tàu | Ferry VN API | |
|---|---|---|
| Kết nối hãng | Mỗi hãng có cổng đặt vé và phiên đăng nhập riêng, bạn tự duy trì từng kết nối. | Ferry giữ kết nối với các hãng; bạn gọi một REST API dưới /api/v1/. |
| Lịch và chỗ trống | Tự đồng bộ lịch chạy và sơ đồ ghế của từng hãng. | Ferry đồng bộ định kỳ, ví dụ mỗi 30 phút cho 7 ngày gần nhất; bạn gọi lại sơ đồ ghế trước khi chốt. |
| Hành khách và loại vé | Tự áp quy tắc loại vé theo tuổi, quốc tịch và độ dài thông tin của từng hãng. | SDK bookingDrafts áp quy tắc của hãng ngay trên máy và báo mọi vấn đề trước khi gửi. |
| Giá và tiền | Tự dựng giá nhiều cấp và đối soát số dư. | Giá NET và giá khách cuối theo từng cấp đại lý; tiền trừ tự động khi xác nhận xuất vé. |
Câu hỏi thường gặp
Làm sao để có API key?
Quản trị viên đại lý nhấn Thêm mới ở Cài Đặt, tab API Keys trên Dashboard; không tạo được key bằng API. Key chỉ cấp cho tổ chức đã có hợp đồng hợp tác, hiện một lần và không tự hết hạn.
API key có phân quyền chỉ đọc không?
Không. Key đại diện cả tổ chức và không chia nhỏ quyền, kể cả tạo, sửa, xoá tổ chức con, nên chỉ lưu ở máy chủ. Muốn đổi key, tạo key mới, triển khai xong rồi xoá key cũ.
Môi trường UAT có phải sandbox không?
Không. UAT kết nối thẳng cổng hãng tàu, nên xác nhận xuất vé ở đó vẫn đặt vé thật và trừ tiền thật. Giai đoạn đầu hãy dừng ở bước tạo booking, chỉ thử xuất vé trên chuyến đã thoả thuận trước với Ferry.
Webhook có chữ ký và có gửi lại khi lỗi không?
Không cả hai: không chữ ký số, không thử lại, hạn phản hồi 2.000 ms, nên sự kiện rơi là mất. Trả 200 ngay, xếp hàng, gọi lại API lấy dữ liệu thật và đối chiếu định kỳ. SDK có hàm đọc gói tin.
Giới hạn tần suất gọi API là bao nhiêu?
Ferry đếm theo IP nguồn, không theo API key: 50 lệnh mỗi 100 mili-giây, khoảng 500 lệnh mỗi giây. Riêng xác nhận xuất vé chỉ cho 5 lệnh trong 60 giây. Khi gặp 429, lùi dần từ 1 đến 30 giây rồi thử lại.
Booking bị timeout thì có gọi lại được không?
Đừng gọi lại ngay: không có khoá chống lặp, nên hai lần tạo booking sẽ ra hai booking. Hãy liệt kê booking theo số điện thoại, mã chuyến, ngày đi; nếu đã có, xác nhận xuất vé bằng mã đó, chỉ tạo mới khi chưa có.
MCP server có thể xuất vé hoặc thanh toán không?
Không. Xuất vé và thanh toán không bao giờ mở cho AI agent. Máy chủ mặc định chỉ đọc; công cụ ghi phải bật riêng và mỗi lần cần con người xác nhận. Booking của agent dừng ở trạng thái chưa thanh toán.
Có SDK cho ngôn ngữ khác ngoài TypeScript không?
Hiện SDK chính thức chỉ có TypeScript. Ngôn ngữ khác gọi thẳng REST API bằng API key; xem schema từng endpoint trên Scalar tại api.ferry.vn/docs. Đặc tả OpenAPI đã lọc có trong repo SDK trên GitHub.
Tài liệu nhà phát triển
Dành cho
Bạn là OTA hoặc đối tác công nghệ?
Trang này mô tả sản phẩm kỹ thuật. Muốn biết cách hợp tác, nhận quyền UAT và được đội kỹ thuật Ferry VN đi cùng đến go-live, xem trang dành cho đối tác API.
Trang dành cho đối tác APICác sản phẩm khác của Ferry VN
FOMHệ thống để hãng tàu vận hành toàn bộ hoạt động kinh doanh: tuyến, lịch chạy, sơ đồ ghế, kênh bán và đối soát doanh thu.
B2B DashboardCông cụ để đại lý bán vé nhiều hãng tàu, quản lý khách hàng, công nợ và mạng lưới đại lý nhiều cấp.
Đặt vé trực tuyếnHành khách đặt vé qua Web, App hoặc Telegram/Zalo Mini App và nhận vé tức thì 24/7.
Cập nhật lần cuối:
Cho chúng tôi biết hệ thống của bạn. Kỹ sư Ferry VN sẽ liên hệ để trao đổi phạm vi tích hợp.