API Reference

The official interactive API documentation for Ferry is generated directly from the backend system and continuously updated on the Scalar UI. This page guides you through opening the documentation, navigating business API tags, and testing API calls directly.

Key points

• The primary reference interface for partners is Scalar UI at https://api.ferry.vn/docs.
• APIs are organized by business domain tags such as Voyages, Boat Layout, Bookings, Transactions, and others.
• The interface gathers both public routes and partner-facing routes; all partner business actions require an API key passed in the Authorization header.
• If the browser Authorize button does not automatically attach your key to certain sections, you can fill the Authorization header manually in each section or use an external HTTP tool.

Scalar UI — Partner API Reference Inspect detailed data schemas, required parameters, and test API calls directly in your browser.

Swagger Admin — System Operations Reference Reserved for Ferry operations and internal administrative personnel (requires administrative credentials).

Three Ferry API documentation portals

The system provides three interactive documentation portals tailored to distinct integration roles:

Documentation portal	Target audience	UI engine	Authentication characteristics
/docs	External integrating partners and public catalogue queries	Scalar UI	Combines unauthenticated public routes and API key-protected partner routes
/internal/docs	Ferry Dashboard and Agency Dashboard	Scalar UI	Requires user JWT credentials; partner API keys cannot call these routes
/admin/docs	Ferry operations and administration teams	Swagger UI	Requires internal administrator credentials

These portals are served directly on the API server domain for each environment (for example https://api.ferry.vn/docs). When integrating in the UAT testing environment, open the portal on the corresponding UAT hostname; see Environments.

Why the /docs interface combines two tiers

The backend documentation generator assigns a single public visibility tag to both public catalog routes (requiring no authentication) and partner business routes (requiring an API key).

Key consequences for partners navigating Scalar:

• No visual separation: The UI does not provide separate lock icons or partitioned sections to distinguish which routes require an API key and which are public. Consult the Integration surface overview to verify the exact boundary.
• Visible on Scalar does not mean callable: Certain routes displayed on /docs (such as the Zalo ZNS messaging endpoints) consistently return HTTP 403 when called with an API key because the key role lacks permission.
• Missing on Scalar does not mean non-existent: Any endpoint that lacks the documentation tag will be omitted from the UI even though the backend server handles it normally.

Navigating API tags on Scalar

Rather than browsing detached endpoints, you should navigate by business domain tags located in the left sidebar of Scalar:

• Voyage lookup and seat availability: The Voyages group (search voyages by pier pair and date, timetable), Boat Layout (seat map and individual seat statuses), Voyage Counts (available seat counts), Routes (route catalogue), Locations (pier catalogue), Operators (ferry operator directory).
• Pricing and promotions: The Ticket Price Additions group (surcharges, partner markup, checking applicable additions), Vouchers (validating and applying voucher codes).
• Booking and passengers: The Bookings group (create booking, confirm ticket issuance, get booking details), Customers (passenger and buyer information attached to bookings).
• Orders and e-tickets: The Orders group (details of individual legs within a booking), Bookings (download issued electronic ticket files).
• Payments and balances: The Transactions group (balance change logs and ledger entries), Debt Ledgers (organization debt tracking), Organizations (credit limits and top-up instructions).
• Cancellation and refunds: The Cancel Ticket Requests group (creating and tracking ticket cancellation requests).

Handling the Authorize button and testing on Scalar

All business endpoints for partners require authentication via an API key passed in the request header:

Authorization: Bearer <API_KEY>

Authorize button returns 401 on several business groups

The OpenAPI specification registers a default security scheme name. The Voyages group correctly references this scheme, so the Authorize button operates as expected there.

However, several primary business groups including Bookings, Organizations, Debt Ledgers, and Cancel Ticket Requests reference an undeclared scheme name in the OpenAPI definition. This mismatch may prevent Scalar from attaching the header after you click Authorize, resulting in HTTP 401 Unauthorized. The behavior has not been verified on the live interface; compare with an independent HTTP client before concluding that the key is invalid.

Four workaround steps when testing calls on Scalar:

1. Test against the Voyages group first: Enter your key into the Authorize modal and call a voyage lookup endpoint. If successful, your API key is entirely valid.
2. Manually input headers per endpoint: For sections returning 401 (such as Bookings), expand the Headers section of that specific endpoint on the Scalar UI and add the Authorization header with Bearer <API_KEY>.
3. Use an external HTTP client: Use external tools such as Postman or your own backend HTTP client with standard Authorization headers to verify server behavior independently.
4. Report the declaration to Ferry: Notify Ferry technical support to update the security scheme references in the OpenAPI definition.

Limitations of the Scalar UI

Limitation	Behavior on UI	Integration guidance
Downloading OpenAPI spec	The spec download button (JSON/YAML) is disabled	Contact Ferry if you require raw schema files for SDK generation
Automated client code generation	The code snippet generation feature is disabled	Construct your HTTP client directly against documented field schemas
Session credential persistence	Auth persistence is disabled outside development environments	You must re-enter your API key upon every browser reload

Common misconceptions

Misconception	Reality	Consequence
Authorize returning 401 means the API key is broken	Security scheme names are mismatched on Bookings	Requesting redundant key re-issuance wastes integration time
If an endpoint is missing from Scalar, Ferry does not have it	Untagged routes disappear from documentation UI	Incorrect assessment of capabilities; confirm directly with Ferry
If an endpoint is listed on Scalar, my API key can call it	The /docs portal includes routes requiring internal roles	Calls return HTTP 403 due to missing role permissions
The /internal/docs portal is usable by partners	This portal serves Dashboards and strictly requires user JWT	Calling it with an API key always results in unauthorized access
Download OpenAPI specs directly from Scalar for SDK generation	The specification download button is disabled on the UI	Request the schema definition file directly from Ferry

Read next

Page	Related topic
Integration surface overview	Understand the boundaries between API tiers and capabilities
Authentication with an API key	Issuing, using, and securing your API keys
General conventions	Data formats, pagination, filtering, and API calling rules
Voyage search and remaining seats	Sequential flow for searching voyages and retrieving seat maps
The booking flow	Complete end-to-end booking and confirmation lifecycle