Developer Documentation

This section is for developers and technical partners integrating with the Ferry ferry-ticketing system via API. You will find connection guides, integration conventions, business workflows, and links to the reference API documentation.

Key points

• Partners integrate through the partner-facing API tier (partner) and authenticate using an API key sent in the Authorization: Bearer <key> header.
• Core business workflows including voyage search, seat layouts, bookings, ticketing, payments, and webhooks are fully documented and supported with a test environment.
• This documentation focuses on business workflows and system behaviour; detailed endpoint schemas can be inspected directly on the interactive Scalar portal.

Reading roadmap

Depending on your integration objective, consult the corresponding guides in the table below:

Integration goal	Recommended page	Key highlights
Understand API scope and capabilities	Integration surface overview	Business groups open to partners, API key permissions, and integration boundaries
Start integration from scratch	Getting started: from zero to the first booking	Step-by-step checklist from receiving a key to issuing the first ticket
Configure environments	Environments	Connection endpoints, UAT testing cautions, and operator integration status
Authenticate and manage API keys	Authentication with an API key	Sending keys, key format, safe key rotation, and handling authentication errors
Understand general technical conventions	General conventions	Cursor pagination, payload ceilings, date-time formats, currency, and idempotency
Inspect schemas and test endpoints	API Reference	Gateway to the live interactive Scalar documentation for the Ferry system
Look up schedules and seat availability	Voyage and seat lookup	Finding voyages by route and date, retrieving seat layouts, and checking seat counts
Calculate fares and discounts	Fares and multi-level markup	Fare structure, price additions, markups, and voucher redemption rules
Implement booking workflows	Bookings: the life cycle of one booking	The order life cycle from booking creation through ticket confirmation to final status
Manage balances and payments	Money: balance, credit limit and debt	Tracking deposit balances, credit limits, and transaction history
Confirm electronic ticket issuance	Ticket issuance and orders	Confirming ticket issuance with operators and retrieving e-ticket files
Handle cancellations and refunds	Cancellation and refunds	Submitting ticket cancellation requests and understanding refund policies
Receive automated notifications	Webhooks	Subscribing to webhooks for real-time order state change events
Handle errors and unexpected issues	Errors and how to handle them	Standard error code directory and network retry strategies
Comply with rate limits	Rate limits	API invocation allowances and backoff patterns when rate-limited
Prepare for production rollout	Before going live	Final technical verification checklist before switching to the Production environment

Interactive API Reference (Scalar)

Detailed technical specifications for every endpoint, request/response schemas, and an interactive in-browser testing tool are available on the Scalar UI — Ferry VN API portal.

Core business groups in Scalar corresponding to this documentation include: Voyages (schedules and voyages), Boat Layout (seat layouts), Bookings (order placement), Transactions and Debt Ledgers (cash flows and credit ledger), and Organizations (organization settings and webhooks).

Related resources

• Agency Documentation: User guide for the operations Dashboard intended for agency ticketing staff and administrators.
• Developer Documentation (Vietnamese): Vietnamese edition of this developer documentation area.