CLI ferry

7 phút đọc

ferry là công cụ dòng lệnh chính thức của Ferry cho người làm việc với API đối tác mà không muốn viết code: tra chuyến và giá, xem sơ đồ ghế, dựng booking từ danh sách hành khách trong Excel, rồi xuất vé hoặc gửi yêu cầu huỷ. CLI nằm trong repo mã nguồn mở ferry-vn/ferry-sdk, dùng chung lõi với SDK.

Cài đặt

CLI có trên npm và cần Node.js từ 22.12 trở lên:

npm install -g @ferryvn/cli

Muốn chạy một lần mà không cài, dùng npx @ferryvn/cli <lệnh>. Kiểm tra bằng ferry --version: lệnh in phiên bản CLI kèm phiên bản SDK bên trong, ví dụ 1.0.0 (sdk 1.0.0). Lệnh tra bến như ferry locations "phu quoc" chạy được ngay cả khi chưa đăng nhập, vì danh mục bến là dữ liệu công khai.

Đăng nhập và hồ sơ

ferry login yêu cầu dán API key (không hiện trên màn hình), kiểm tra key với Ferry rồi lưu vào hồ sơ. Key do quản trị viên đại lý tạo trong Dashboard; xem Xác thực bằng API key.

ferry login
ferry whoami --check
ferry doctor

ferry whoami --check xác nhận key còn dùng được; ferry doctor kiểm tra cấu hình, kết nối và key.

Để làm việc với UAT, tạo hồ sơ thứ hai bằng một key UAT và chọn hồ sơ khi chạy lệnh:

ferry login --profile uat --env uat
ferry --profile uat voyages search --from "Rạch Giá" --to "Phú Quốc" --date tomorrow
ferry profiles use uat

UAT không phải sandbox: xuất vé ở đó vẫn đặt vé thật và trừ tiền thật; xem Môi trường. Thứ tự ưu tiên khi cấu hình chồng nhau: cờ dòng lệnh, rồi biến môi trường (FERRY_PROFILE, FERRY_ENV, FERRY_API_KEY), rồi hồ sơ, cuối cùng là production. Tránh dùng --api-key vì cờ này lưu lại trong lịch sử shell.

Quy trình làm việc chính

Luồng thường dùng đi từ tra cứu đến xuất vé. Các lệnh tra cứu chỉ đọc dữ liệu; tạo booking, xuất vé và huỷ vé thì ghi:

ferry voyages search --from "Rạch Giá" --to "Phú Quốc" --date tomorrow
ferry calendar --from "Rạch Giá" --to "Phú Quốc" --days 14
ferry prices --from "Rạch Giá" --to "Phú Quốc" --date 2026-11-01 --live 3
ferry seats <voyageId>
ferry customers --search 0901234567
ferry booking draft --customer 1001 --orderer-name "Nguyễn Văn A" --email a@example.com \
  --voyage <voyageId> --seats A1,A2 --passengers khach.csv --out booking.json
ferry booking create --file booking.json
ferry booking issue <id>

Tra chuyến, lịch và giá: voyages search tìm chuyến; calendar cho thấy số chuyến mỗi ngày; prices hiện giá bán theo chuyến, hạng ghế và loại vé (--live 3 tính lại giá 3 chuyến đầu từ sơ đồ ghế, nếu không giá có thể trễ so với hãng).
Xem ghế và khách hàng: seats liệt kê ghế trống của chuyến; customers --search tìm khách theo chuỗi bạn gõ, ví dụ số điện thoại, và cho ra mã khách hàng (--customer) dùng ở bước dựng booking.
Dựng booking nháp: booking draft nhận tên ghế và danh sách hành khách, chọn loại vé theo tuổi bằng quy tắc của hãng, khớp giá, kiểm tra ghế và số CCCD trùng, rồi ghi ra booking.json. Chưa có gì được gửi.
Tạo booking: booking create --file booking.json gửi booking; hoặc thêm --create vào booking draft để làm cả hai bước. Có thể thêm --dry-run để chỉ kiểm tra. Tạo booking gắn ghế và hành khách vào booking, không trừ tiền; booking ở trạng thái Requested, chưa thanh toán, kèm hạn thanh toán (xem Đặt vé).
Xuất vé: booking issue <id> trừ số dư và hạn mức tín dụng rồi đặt vé thật với hãng. Lệnh đòi xác nhận: cờ --yes, hoặc gõ lại mã booking trên terminal tương tác; trước khi bạn xác nhận, CLI in tổng tiền và hạn mức tín dụng có thể dùng. Với hãng tự động, bước này có thể mất vài phút.
Huỷ vé: ferry cancel request --order <id> --positions 101,102 --reason "…" giữ ngay phí huỷ và đánh dấu vé đã huỷ; cũng đòi xác nhận như xuất vé.

Các lệnh còn lại gồm booking get, booking list, booking tickets, orders, cancel list, account, transactions, debts, vouchers và disruptions. Lệnh ferry api gửi yêu cầu thô bằng quyền của bạn và hỏi lại trước khi gửi lệnh ghi. Danh sách đầy đủ cờ nằm trong README của gói CLI.

File CSV hành khách

booking draft đọc file CSV xuất từ Excel hoặc Google Sheets, hoặc file JSON. Ví dụ file CSV:

name,date_of_birth,social_id,home_town,gender
Nguyễn Văn A,1990-05-01,079090000001,Cần Thơ,nam
Nguyễn Văn B,2018-03-02,079090000001,Cần Thơ,nam

Cột	Ý nghĩa
`name`	Họ tên hành khách (chấp nhận tiêu đề `ho_ten` hoặc `Họ tên`)
`date_of_birth`	Ngày sinh `YYYY-MM-DD` (chấp nhận `ngay_sinh` hoặc `Ngày sinh`)
`social_id`	Số CCCD hoặc hộ chiếu (chấp nhận `cccd` hoặc `Số CCCD`)
`home_town`	Quê quán (chấp nhận `que_quan`)
`gender`	`male` hoặc `female`, `nam` hoặc `nữ`, `1` hoặc `0` (chấp nhận `gioi_tinh`)
`national_id`	Tuỳ chọn; mặc định Việt Nam; xem giá trị bằng `ferry operators nationals`
`ticket_type_id`	Tuỳ chọn; mặc định chọn theo tuổi
`plate_number`, `passport_expired_at`	Tuỳ chọn; biển số xe và ngày hết hạn hộ chiếu

Khi xuất file từ Excel, chọn CSV UTF-8 để không vỡ chữ tiếng Việt; CLI từ chối file không phải UTF-8 và nhắc chọn đúng định dạng này. Dấu phân cách là ,, hoặc ; nếu dòng tiêu đề dùng dấu chấm phẩy (Excel bản tiếng Việt). Số CCCD phải khác nhau giữa các hành khách, trừ loại vé trẻ em mà hãng miễn kiểm tra.

Định dạng đầu ra

Cờ --output (viết tắt -o) nhận table, json, ndjson hoặc csv; --json là cách viết ngắn. Đầu ra CSV có dấu BOM UTF-8 nên Excel mở đúng tiếng Việt, và các ô bắt đầu như công thức được vô hiệu hoá để tránh chèn công thức độc hại. Ví dụ xuất danh sách booking chờ xử lý cho kế toán:

ferry booking list --status Requested --output csv > don.csv
ferry transactions --output csv > giao-dich.csv

Dùng --all để lấy hết các trang thay vì trang đầu. Các cờ chung khác: --timeout, --base-url và --debug (ghi log HTTP ra stderr, đã ẩn key).

Mã thoát

Mã	Ý nghĩa
0	Thành công
1	Lỗi API, máy chủ hoặc mạng (kể cả `doctor` có mục kiểm tra thất bại)
2	Dùng sai lệnh: cờ sai, dữ liệu không hợp lệ hoặc bạn chưa xác nhận
3	Xác thực hoặc quyền: 401, 403
4	Không tìm thấy: 404
5	Chạm giới hạn tần suất: 429

Nơi lưu cấu hình

Hồ sơ và key nằm trong file config.json với quyền 0600:

Hệ điều hành	Thư mục
Linux	`~/.config/ferry/` (theo `XDG_CONFIG_HOME` nếu có)
macOS	`~/Library/Application Support/ferry/`
Windows	`%APPDATA%\ferry\`

Đặt biến FERRY_CONFIG_DIR để dùng thư mục khác.

Sai lầm thường gặp

Hiểu nhầm	Thực tế	Cách làm đúng
Dùng chung một hồ sơ cho UAT và production	Hai môi trường cần hai key	`ferry login --profile uat --env uat` và chọn hồ sơ bằng `--profile`
UAT an toàn như sandbox	Xuất vé trên UAT đặt vé thật, trừ tiền thật	Chỉ xuất vé trên chuyến đã thoả thuận với Ferry
`booking draft` đã tạo booking	Mặc định chỉ ghi file nháp	Thêm `--create` hoặc chạy `booking create` khi đã kiểm tra
Lưu CSV từ Excel bằng bảng mã mặc định	Không phải UTF-8 thì CLI từ chối	Chọn CSV UTF-8 khi lưu
Chạy lại `booking create` sau lỗi mạng	API không có khoá chống lặp, có thể ra đơn thứ hai	Chạy `ferry booking list --search …` để kiểm tra trước
Gõ key bằng `--api-key`	Lịch sử shell lưu lại key	Dùng `ferry login` hoặc biến môi trường `FERRY_API_KEY`

Tra ở đâu

Danh sách đầy đủ lệnh và cờ nằm trong README của gói CLI trên GitHub; repo có sẵn file mẫu examples/passengers.csv và examples/booking.json. Tham chiếu HTTP gốc ở Scalar UI.

Việc cần tra	Nơi tra
Danh sách lệnh và cờ	README gói CLI trên GitHub
File CSV và JSON mẫu	Thư mục `examples` của repo `ferry-sdk`
Route và schema HTTP phía sau mỗi lệnh	Scalar, nhóm `Bookings`, `Voyages`, `Cancel Ticket Requests`

Đọc tiếp

Trang	Khi nào đọc
SDK TypeScript	Cùng logic dựng booking khi bạn muốn viết code
Luồng đặt vé	Hiểu trạng thái booking mà các lệnh tạo ra
Xuất vé	Hiểu điều gì xảy ra khi chạy `booking issue`
Huỷ vé và hoàn tiền	Hiểu hậu quả của `cancel request`