Getting Started

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.

Each specific API endpoint URL will be appended to the base host to form the complete request URL on the TTN side.

INFO

For example, /json/shopping refers to BASE_HOST + /json/shopping.

All API requests require a SIGN field to verify the identity of the requester.
The PARTNER_ID and PARTNER_KEY are provided by the Partner and used by TTN to generate the SIGN for each request.

To calculate the signature, concatenate PARTNER_ID and PARTNER_KEY into a single string (without any separators) and compute the MD5 hash of the resulting value.

The Partner is responsible for validating the SIGN value on their side using the same logic.

Authentication Parameters Requirements

The PARTNER_ID and PARTNER_KEY are generated on the Partner’s side according to the rules described below. After generation, these values must be shared with the TTN side to enable request validation.

PARTNER_ID Format

• Length: 8 to 64 characters.
• Allowed characters: Alphanumeric (a-z, A-Z, 0-9), hyphens (-), and underscores (_).
• Restrictions: Spaces are not allowed.
• Example: "kL9-2PqX_7"

PARTNER_KEY Format

• Length: 32 to 128 characters.
• Requirements: Must be cryptographically secure and include at least one of each:
  • Uppercase letter (A-Z)
  • Lowercase letter (a-z)
  • Digit (0-9)
  • Special character (e.g., !@#$%^&*()_+={}[] | :;<>,.?/~)
• Example: "kR4jT0_YbA7#xP9@qL2$wM5%vA1^zN8"

TIP

Recommendation: Use reliable random string generators or cryptographic utilities (e.g., openssl rand -base64 32) to create the PARTNER_KEY. The key must be securely stored and used only for validating incoming requests.

SIGN Generation Example (JavaScript)

const PARTNER_ID  = "kL9-2PqX_7"
const PARTNER_KEY = "kR4jT0_YbA7#xP9@qL2$wM5%vA1^zN8"

PARTNER_ID + PARTNER_KEY
// 'kL9-2PqX_7kR4jT0_YbA7#xP9@qL2$wM5%vA1^zN8'

const SIGN = CryptoJS.MD5(PARTNER_ID + PARTNER_KEY).toString()
// 'fddd27c9f2b9de21dce4e840a5c1b182'

The generated SIGN value must be included in the authentication object of every request body.

Request body example:

{
  "authentication": {
    "partnerId": "{{PARTNER_ID}}",
    "sign": "{{SIGN}}"
  },
  "...": "..."
}

Postman Collection

To help you get started quickly and test the API endpoints, we have prepared a ready-to-use Postman collection. You can access and import it using the link below:

Goldfish API Postman Collection

TIP

Configuration Setup:

• Credentials: You can easily set your PARTNER_ID, PARTNER_KEY, and BASE_HOST directly in the collection's Variables section.
• Built-in Validation: The collection includes pre-configured validations. If an endpoint returns an incorrect parameter format or structure, Postman will automatically highlight the error to help you debug quickly.

Workflow

Below is the workflow diagram illustrating the booking process between the TTN and Partner sides.

HTTP Status Codes

When interacting with our API, all responses are returned using only three possible HTTP status codes. They indicate the general result of your request execution:

• 200 OK — The request was processed successfully. The response body contains the expected data in JSON format.
• 204 No Content — The request was successful, but there is no data to display (this code is used for the shopping method if it does not find and return any available flights based on your specified search criteria).
• 400 Bad Request — Client-side error. Your request contains invalid parameters, missing required fields, or has an incorrect format. Details about the error are usually provided in the response body.

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.

Сabin Class List

• Economy
• PremiumEconomy
• Business
• PremiumBusiness
• First
• PremiumFirst

Order Status List

Enum	Description
ISS_PRC	Ticket is issuing
ISSUED	Ticket issued
CNCL	Order Cancelled. Cancelled on the TTN side before the Payment
CLOSED	Order closed. Cancelled on the Partner side before the Payment
RSV_FAIL	Reservation failed. Cancelled on the Partner side after the Payment
HOLD	Order is holding manually, please contact customer service for further action
CHG_PRC	Change order is proceeding
REFD_PRC	Refund order is proceeding
VOID_PRC	Ticket is voiding
TO_BE_PAID	To be Paid
TO_BE_RSV	To be reserved
UNDER_REVIEW	Under review
CNCL_REIMED	Order Cancelled, and payment has been reimbused
CHG_RQ	Change Order is requested
CHG_TO_BE_PAID	Change Order is to be paid
CHG_REJ	Change Order is rejected
CHGD	Change Order is changed
REFD_RQ	Refund Order is under review
REFD_REJ	Refund Order is rejected
REFD_TO_BE_REIM	Refunded to be reimbursed
REFD_REIMED	Refunded and reimbursed
REFD	Refunded
VOID_REJ	Void request is rejected
VOID_TO_BE_REIM	Void to be reimbursed
VOID_REIMED	Void and reimbursed
VOID	Void

Price Breakdown Explanation

Individual Adult Price = Adult Ticket Fare [adtFare] + Adult Ticket Tax [adtTax] + Ticketing Fee [tktFee]

Individual Child Price = Child Ticket Fare [chdFare] + Child Ticket Tax [chdTax] + Ticketing Fee [tktFee]

Individual Infant Price = Infant Ticket Fare [infFare] + Infant Ticket Tax [infTax] + Ticketing Fee [tktFee]

Total Price = Individual Adult Price * adult passenger number [adults] + Individual Child Price * child passenger number [children] + Individual Infant Price * Infant passenger number [infant]