Integration surface overview

This page defines the integration boundary between partner systems and the Ferry platform. You will understand which business groups can be called using an API key, which internal areas are closed to external calls, and the core authorization principles across the platform.

Key points

• The Ferry system divides its API surface into 4 tiers; external partners interact exclusively with the public tier (public) and the partner tier (partner).
• The partner tier exposes 86 business endpoints authenticated by an API key, covering schedule search, seat reservations, credit management, and webhook subscriptions.
• Partners cannot access the internal tier (internal), the administrative tier (admin), the real-time SSE stream, or key generation endpoints.
• An API key represents the entire agency organization and does not support granular permission scopes; it must be kept strictly confidential on your backend servers.

API tiers in the system

The Ferry backend partitions its API surface into 4 distinct tiers according to the caller identity and authentication mechanism:

API Tier	Caller	Authentication method	Partner availability
public	Website visitors, mobile applications, partners	No authentication required	Common catalogs: routes, locations, and operators
partner	B2B integration partners	API key in the Authorization header	Primary partner tier with 86 business routes
internal	Agency operations staff and Ferry employees	User session JWT	Not accessible via API key
admin	Ferry technical operations team	System administrator JWT	Not accessible via API key

The diagram below illustrates the API tiers and external partner access boundaries:

flowchart LR
    subgraph callers["Callers"]
        partner["B2B Partner<br/>with API key"]
        guest["Public User<br/>unauthenticated"]
        dashboard["Operations Staff<br/>with JWT"]
    end
    subgraph reachable["Partner Reachable Area"]
        tierpublic["Public Tier<br/>Shared catalogs"]
        tierpartner["Partner Tier<br/>86 business routes"]
    end
    subgraph blocked["Closed Internal Area"]
        tierinternal["Internal Tier<br/>Requires user JWT"]
        tieradmin["Admin Tier<br/>Requires admin JWT"]
    end
    guest --> tierpublic
    partner --> tierpublic
    partner --> tierpartner
    dashboard --> tierinternal

The partner tier declares 112 routes, but only 87 routes are configured with the API key authentication mechanism, with 1 route requiring higher internal administrative privileges. Therefore, exactly 86 routes form the actual callable surface for partners using an API key (the remaining routes serve internal Ferry maintenance tasks such as operator gate testing or forced synchronization).

The public tier consists of 9 routes requiring no authentication. Both tiers appear side-by-side on the public documentation interface at /docs. For shared catalogs such as routes, ferry terminals, and operators, the platform does not provide separate authenticated endpoints — partners must call the public routes directly without passing an API key.

Business areas open to partners

The 86 partner business routes are organised into the following core functional groups:

Business group	Core capabilities	Detailed guide
Schedule search	Search voyages by route and date, inspect schedules, get voyage details	Voyage and seat lookup
Seat layout and availability	Retrieve cabin layouts, check real-time seat availability per voyage	Voyage and seat lookup
Bookings and order management	Create seat-holding bookings, confirm electronic ticket issuance, query and update bookings	Bookings: the life cycle of one booking
Order inquiry (Orders)	List and inspect order details (read-only); do not create orders or issue tickets through this group	Ticket issuance and orders
Cancellations	Submit ticket cancellation requests and monitor approval status from operators	Cancellation and refunds
Customers and companies	Create customer profiles, update contact information, and manage company records	Inspect on Scalar, Customers group
Pricing and promotions	Verify price addition rules, pricing policies, and voucher eligibility	Fares and multi-level markup
Cash flow and credit	Check agency deposit balance, query the debt ledger, and view transaction history	Money: balance, credit limit and debt
Sub-organization management	Create, update, and manage sub-agencies with authority to delete child organizations	Authentication with an API key
Notifications and events	Register webhook URLs for status change notifications, trigger booking emails	Webhooks

Areas closed to external partners

To protect system integrity and operational safety, the following areas are strictly blocked from API key calls:

Blocked area	Technical reason	Alternative approach
Entire internal and admin tiers	Requires user authentication via JWT	Perform actions on the Dashboard interface
Real-time event stream (SSE)	Requires an active user JWT session	Use Webhooks or periodic polling
Electronic invoice management	Partner-tier endpoint is completely closed	Receive webhook notifications, inspect details on Dashboard
Booking Zalo ZNS messages	Always returns 403 Forbidden because permission schema lacks API key role	Send ZNS independently from partner’s system
Creating and issuing new API keys	Restricted to agency administrators on Dashboard	Agency administrators create keys under API Keys
Global system search	Restricted to operations staff on the interface	Query specific entities directly (voyages, bookings, customers)

Additional note: The booking listing endpoint (GET /api/v1/bookings) returns a deprecation warning header when passing dynamic filters; no replacement route is currently offered in the partner tier.

API key permissions and scope

A Ferry API key is bound to one specific agency organization. When invoking APIs with this key, all actions and generated data belong to that organization.

API keys do not have granular permission scopes

The system does not offer “read-only” keys or keys restricted to individual business modules. A valid API key possesses full administrative authority over the agency organization’s data.

Important security implications:

• Server-side secrecy: Never embed an API key into mobile app binaries, client-side browser JavaScript, or public repositories.
• Child-organization deletion risk: Key permissions include deleting child organizations within your agency hierarchy. A compromised key can be exploited to delete child organizations or manipulate transactions and customer data.
• Compromise response: If key exposure is suspected, immediately revoke the old key and create a new one on the Dashboard following the safe rotation workflow.

Common misconceptions

Misconception	Reality	Correct practice
Assuming all routes in the docs can be called with an API key	The public docs mix unauthenticated routes and administrative routes	Cross-reference with the 86 partner routes
Searching for authenticated endpoints for routes, locations, and operators	Shared catalogs exist only in the public tier without authentication	Call public routes directly without the Authorization header
Attempting to send Zalo ZNS via Ferry API	Always returns 403 Forbidden due to missing permissions for API keys	Implement independent ZNS delivery from your own system
Attempting to inspect invoice details via API after receiving webhooks	Partner-tier invoice endpoint is completely closed	Inspect invoice data through the Dashboard interface
Issuing tickets through the Orders group	The Orders group only supports reading order details	Perform complete booking and ticket issuance through the Bookings group
Embedding an API key inside end-user mobile apps	Anyone decompiling the mobile package can extract the key and delete child organizations	Route all Ferry calls through your secure backend server
Searching for an API endpoint to generate API keys programmatically	Key generation is restricted to the web Dashboard	An agency administrator creates keys manually in the Dashboard
Attempting to connect to the SSE stream using an API key	The SSE channel strictly requires a user JWT	Register a webhook endpoint to receive order status updates

Where to look in Scalar

This guide maps each functional group to the corresponding section on the Scalar UI — Ferry VN API interactive portal:

Business domain	Group name on Scalar
Voyages, seat layouts, and seat counts	Voyages, Boat Layout, Voyage Counts
Bookings and order details	Bookings, Orders
Price additions and vouchers	Ticket Price Additions, Vouchers
Payment transactions and debt ledgers	Transactions, Debt Ledgers
Customer, company, and organization profiles	Customers, Companies, Organizations
Public catalogs (routes, locations, operators)	Routes, Locations, Operators

Read next

Guide	Recommended next reading
Getting started: from zero to the first booking	10 practical steps from key setup to issuing your first ticket
Environments	Learn about the UAT and Production environments before calling endpoints
Authentication with an API key	Header format rules, key structure, and safe rotation procedures
General conventions	Guidelines on cursor pagination, timestamp standards, and error handling