Getting Started

• The Partner (from now on referred to as the Partner side) receives a link to the Jellyfish Bus documentation
• The Partner side implements the set of endpoints described in the API sections (Auth & Discovery, Search API, Order API, Cancellation API)
• Tickets Travel Network (from now on referred to as the TTN side), after the integration is completed, will send corresponding requests to the Partner side, expecting responses in the format specified in this documentation
• The workflow according to which the TTN side will send requests to the Partner side is illustrated in the “Workflow” section
• The Partner side provides access to a test environment and shares it with the TTN side: BASE_HOST (e.g. https://example_test_sandbox.com), LOGIN, and PASSWORD
• The TTN side verifies the correctness of the integration implementation using the test credentials; if everything is correct, it requests production credentials from the Partner side
• The Partner side provides the TTN side with production credentials: BASE_HOST (e.g. https://example_live_creds.com), LOGIN, and PASSWORD
• The TTN side enables content from the Partner side on live traffic

Introduction

All API requests must be sent to the specified base host (BASE_HOST).
The BASE_HOST is the Partner's API endpoint (host). It is not provided by TTN and must be supplied and maintained by the Partner.

The Partner must supply their own BASE_HOST (e.g., https://api.partner.com), and all API requests from TTN will be sent to this endpoint.

Base URL & Versioning

All paths are served under a /v{major} version prefix (currently /v1). The complete request URL is BASE_HOST + /v{major} + the endpoint path.

INFO

For example, /search refers to BASE_HOST + /v1/search.

The TTN side chooses the version prefix from the api_version it onboarded the Partner against (default 1.0), so a Partner stays pinned to the version it implemented.

• Backwards-compatible additions (new optional fields, new endpoints) bump the minor version on the same /v1 path.
• Breaking changes are published as /v2 and may coexist with /v1.

Authentication

Authentication is token-based. The Partner side issues a short-lived bearer token in exchange for credentials, and the TTN side sends that token on every other request.

Login

POST /v1/login exchanges the LOGIN and PASSWORD (provided by the Partner) for a bearer token.

Request Example:

{
  "login": "{{LOGIN}}",
  "password": "{{PASSWORD}}"
}

Response Example:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 3600
}

Using the token

All endpoints except /login require the token in the Authorization header:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

TIP

The TTN side caches the token until shortly before expires_in elapses and transparently re-logs-in (calls /login again) when a request returns 401 or 403. The Partner side must accept a freshly issued token at any time.

HTTP Status Codes

Code	Meaning
200 OK	The request was processed successfully. The response body contains the expected data in JSON format.
401 Unauthorized	The bearer token is missing, invalid, or expired. The TTN side will re-authenticate via /login and retry.
403 Forbidden	The token is valid but lacks permission for the operation. The TTN side will re-authenticate via /login and retry.
4xx / 5xx	Any other client or server error. The response body contains the error envelope described below.

Error Format

Every error response uses a single envelope:

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Order not found"
  }
}

Parameter	Type	Required	Description
└ error	Object	Yes	Error details
└ code	String	Yes	Machine-readable error code (e.g. NOT_FOUND, INVALID_PASSENGER)
└ message	String	Yes	Human-readable error message

Handling Optional Parameters

When returning optional parameters in API responses, if a parameter has no value, you must either:

• Return it as null (e.g., "parameter": null)
• Exclude the parameter entirely from the response

WARNING

Do not return optional parameters as empty strings (""), empty arrays ([]), or empty objects ({}) unless explicitly required by the endpoint documentation.

Locale List

The optional locale parameter (query or body, depending on the endpoint) localises human-readable fields. Supported values:

en, uk, ru, de, pl, fr, kk, es

Order Status List

Enum	Description
created	Order created (reserved/booked) but not yet paid
paid	Order confirmed and paid; tickets issued
canceled	Order cancelled
money_returned	Order cancelled and the refund has been reimbursed

Payment Method List

The payment_method field (used by Confirm Order) accepts:

Enum	Description
cash	Paid in cash
card	Paid by card
non_cash	Paid by non-cash / bank transfer

Passenger Types

The passenger type field accepts:

Enum	Description
adult	Adult passenger
child	Child passenger

Seat Type Legend

In Trip Details, each seats_map[].type describes what the cell on the coach plan represents:

Value	Meaning
0	Corridor
1	Free (selectable seat)
2	Unavailable
3	Driver
4	Door
5	WC
6	Luggage
7	TV

Workflow

Below is the lifecycle of a booking between the TTN side and the Partner side. Each step is a request from TTN to the Partner-implemented endpoint.