FR24 国际机票 MCP 接入指南

提供国际机票搜索、验价、下单、订单查询全流程能力，支持 Cursor、Claude Code、Codex、WorkBuddy、OpenClaw 等主流 AI Agent 接入。

一概述

标准预订流程必须按顺序调用，不可跳步：

① shopping
搜索航班

→

② pricing
锁定价格

→

③ booking
提交下单

→

④ orderDetail
查询订单

二联系我们（获取 CID 与密钥）

接入本服务需要 FR24 分配的 采购商 ID（X-Cid） 与 16 位采购密钥（X-Passkey）。请按以下步骤申请获取：

申请流程

1商务对接：通过下方任一联系方式与 FR24 商务团队取得联系，说明接入意向（公司名称、业务场景、预估请求量）。
2资质审核：提交企业资质材料，FR24 将在 1–3 个工作日内完成审核。
3发放凭证：审核通过后，专属商务经理将向您发送 X-Cid 与 X-Passkey（16 位密钥）。
4接入联调：使用发放的凭证参照第三节配置示例进行联调，可联系技术支持协助。

联系方式

📧

商务邮箱

bd@flightroutes24.com

💬

商务微信

🌐

B2B 平台

b2b.flightroutes24.com

🛠️

技术支持

tech@flightroutes24.com

⚠️ 密钥安全：X-Passkey 是核心鉴权凭证，请妥善保管，切勿提交到公共代码仓库或泄露给第三方。如密钥疑似泄露，请立即联系技术支持重置。

三接入配置

3.1 服务地址

环境	MCP Endpoint
生产环境	`https://mcp.fr24.ai/mcp`

3.2 鉴权方式

通过 HTTP Header 传入鉴权信息：

Header	说明	示例
`X-Cid`	采购商 ID（由 FR24 分配）	`FRG`
`X-Passkey`	采购密钥，必须是 16 位字符串（AES-128 加密 + SHA512 签名）	`your16charpasskey`

⚠️ passkey 必须恰好 16 个字节，长度不符将返回鉴权失败错误。

3.3 客户端配置示例

本服务支持所有兼容 MCP（Model Context Protocol）的 AI Agent 客户端，以下给出主流客户端的接入配置。所有客户端的鉴权信息一致：X-Cid 为采购商 ID，X-Passkey 为 16 位采购密钥。

① Cursor

在项目根目录创建或编辑 .cursor/mcp.json：

json.cursor/mcp.json

{
  "mcpServers": {
    "fr-flight-mcp": {
      "url": "https://mcp.fr24.ai/mcp",
      "headers": {
        "X-Cid": "YOUR_CID",
        "X-Passkey": "YOUR_16CHAR_PASSKEY"
      }
    }
  }
}

② Claude Code

Claude Code 使用 .mcp.json 配置文件（项目级或用户级 ~/.mcp.json）。通过命令行添加亦可：claude mcp add --transport http fr-flight-mcp https://mcp.fr24.ai/mcp -H "X-Cid:YOUR_CID" -H "X-Passkey:YOUR_16CHAR_PASSKEY"

json.mcp.json

{
  "mcpServers": {
    "fr-flight-mcp": {
      "type": "http",
      "url": "https://mcp.fr24.ai/mcp",
      "headers": {
        "X-Cid": "YOUR_CID",
        "X-Passkey": "YOUR_16CHAR_PASSKEY"
      }
    }
  }
}

③ Codex (OpenAI)

在 Codex 的 MCP 配置文件 ~/.codex/config.toml 中添加（HTTP 传输）：

toml~/.codex/config.toml

[mcp_servers.fr-flight-mcp]
transport = "http"
url = "https://mcp.fr24.ai/mcp"

[mcp_servers.fr-flight-mcp.headers]
X-Cid = "YOUR_CID"
X-Passkey = "YOUR_16CHAR_PASSKEY"

④ WorkBuddy

在 WorkBuddy 设置中心的「MCP 服务」中新增一个 HTTP 类型的 Server，或在配置文件 workbuddy.mcp.json 中添加：

jsonworkbuddy.mcp.json

{
  "servers": {
    "fr-flight-mcp": {
      "transport": "http",
      "endpoint": "https://mcp.fr24.ai/mcp",
      "headers": {
        "X-Cid": "YOUR_CID",
        "X-Passkey": "YOUR_16CHAR_PASSKEY"
      }
    }
  }
}

⑤ OpenClaw

在 OpenClaw 的 openclaw.config.json（或 ~/.openclaw/mcp_servers.json）中配置 streamable-http MCP 服务：

jsonopenclaw.config.json

{
  "mcpServers": {
    "fr-flight-mcp": {
      "transport": "streamable-http",
      "url": "https://mcp.fr24.ai/mcp",
      "headers": {
        "X-Cid": "YOUR_CID",
        "X-Passkey": "YOUR_16CHAR_PASSKEY"
      }
    }
  }
}

ℹ️ 以上 YOUR_CID 与 YOUR_16CHAR_PASSKEY 为占位符，请替换为 FR24 分配给您的真实凭证。获取方式见第二节联系我们。

四工具详解

shopping

搜索国际机票，支持 6 种搜索模式，最多返回 10 条航班。

必填参数

参数	类型	说明
`origin`	string	出发地 IATA 三字码，如 `PEK`（北京）、`HKG`（香港）
`destination`	string	目的地 IATA 三字码，如 `BKK`（曼谷）、`NRT`（东京）
`depDate`	string	出发日期，格式 `yyyy-MM-dd`

可选参数

参数	类型	说明
`adultNum`	integer	成人人数，默认 1
`childNum`	integer	儿童人数（2-12岁），默认 0
`infantNum`	integer	婴儿人数（不足2岁），默认 0
`retDate`	string	返程日期，单程不传
`searchMode`	string	搜索模式（见下表）
`departureTimeRange`	string	[TIME模式] 如 `06:00-12:00`
`priceRange`	string	[PRICE模式] 如 `500-2000`
`flightNo`	string	[FLIGHT模式] 如 `CA1234`
`cabin`	string	[CABIN模式] Y=经济 C=商务 F=头等 P=超经

searchMode 说明

值	说明	配合参数
不传	默认搜索，按价格排序	—
`TIME`	按出发时间段过滤	`departureTimeRange`
`PRICE`	按总价区间过滤	`priceRange`
`FLIGHT`	指定航班号搜索	`flightNo`
`TRANSFER`	只返回中转航班	—
`CABIN`	按舱位过滤	`cabin`

调用示例

json

// 默认搜索
{ "origin": "HKG", "destination": "BKK", "depDate": "2026-08-01" }

// 按时间段筛选（早班）
{ "origin": "PEK", "destination": "NRT", "depDate": "2026-08-10",
  "searchMode": "TIME", "departureTimeRange": "06:00-12:00" }

// 往返搜索
{ "origin": "SZX", "destination": "BKK",
  "depDate": "2026-08-15", "retDate": "2026-08-20" }

// 带儿童搜索
{ "origin": "HKG", "destination": "SIN", "depDate": "2026-08-01",
  "adultNum": 1, "childNum": 1 }

返回字段

字段	说明
`flightNo`	航班号
`airline`	航司名称
`cabin`	舱位（经济舱 / 商务舱 / 头等舱）
`depAirport`	出发机场，格式 `机场码(城市名)`，如 `HKG(香港国际机场)`
`depTime`	出发时间，格式 `MM-dd HH:mm`
`arrAirport`	到达机场，格式同上
`arrTime`	到达时间
`duration`	飞行时长，如 `3h45m`
`type`	直飞 / 中转
`priceDisplay`	总价含币种，如 `1200 CNY`
`remainingSeats`	剩余座位数
`seatsAlert`	剩余 ≤ 3 座时的紧张提示
`refundPolicy`	退改签政策

pricing

锁定选定航班的价格，有效期 30 分钟。必须在 shopping 之后、booking 之前调用。

⚠️ 带儿童/婴儿时，adultNum/childNum/infantNum 必须与 shopping 时传入的人数一致，否则验价失败。

必填参数

参数	类型	说明
`offerId`	string	shopping 返回的 offerId

可选参数

参数	类型	说明
`adultNum`	integer	成人人数，默认 1，需与搜索时一致
`childNum`	integer	儿童人数，默认 0
`infantNum`	integer	婴儿人数，默认 0

返回字段

字段	位置	说明
`priceDisplay`	顶层	锁定总价，含币种
`priceBreakdown`	顶层	分项价格明细（多人时展示）
`remainingSeats`	顶层	剩余座位
`msg`	顶层	提示信息
`meta.verifyOfferId`	meta	用于 booking 的 verifyOfferId
`meta.isInternational`	meta	是否国际航线
`meta.requiredPassengerFields`	meta	乘客必填字段，`cardType.allowedValues` 为允许的证件类型

requiredPassengerFields 示例

json

{
  "birthday": true,
  "gender": true,
  "cardNum": true,
  "cardType": {
    "required": true,
    "allowedValues": ["PP", "GA", "HX", "TB"]  // 国际航线不含 ID
  },
  "cardIssuedPlace": true,
  "cardExpiryDate": true,
  "nationality": true,
  "paxEmail": false,
  "paxMobile": false
}

ℹ️ allowedValues 国际航线不含 ID（身份证），境内航线含 ID。下单时 cardType 必须从此列表中选择。

booking

提交机票预订，支持多人（成人 + 儿童 + 婴儿）。

必填参数

参数	类型	说明
`verifyOfferId`	string	pricing 返回的 `meta.verifyOfferId`
`passengersJson`	string	乘客列表 JSON 数组字符串，见下方格式说明

可选参数

参数	类型	说明
`allowedCardTypes`	array	pricing 返回的 cardType.allowedValues，强烈建议传入
`departureDate`	string	出发日期，用于年龄校验（可从缓存自动获取）
`contactName`	string	联系人姓名（不填则用第一个乘客兜底）
`contactMobile`	string	联系人手机号
`contactEmail`	string	联系人邮箱
`idempotencyKey`	string	幂等键（UUID），24小时内相同 key 只下一次单
`partnerOrderNo`	string	合作方自定义订单号

passengersJson 乘客字段

字段	必填	说明
`name`	必填	姓/名，英文大写，如 `ZHANG/SAN`
`paxType`	必填	`ADT`=成人 / `CHD`=儿童 / `INF`=婴儿
`gender`	必填	`M`=男 / `F`=女
`birthday`	必填	出生日期，格式 `yyyy-MM-dd`
`cardType`	必填	证件类型，必须在 allowedValues 中选
`cardNum`	必填	证件号码，最长 20 位
`cardIssuedPlace`	按需	证件签发地，ISO 两字码，如 `CN`
`cardExpiryDate`	按需	证件有效期，格式 `yyyy-MM-dd`
`nationality`	按需	国籍，ISO 两字码，如 `CN`
`areaCode`	可选	手机区号，默认 `86`
`paxMobile`	可选	联系电话
`paxEmail`	可选	联系邮箱
`accompaniedPaxId`	CHD/INF必填	关联成人序号（从1起），如 `"1"`

证件类型 & 年龄规则

代码	说明	适用航线
`ID`	身份证	仅境内航线
`PP`	护照	国际/境内均可
`GA`	港澳通行证	国际/境内均可
`HX`	回乡证	国际/境内均可
`TB`	台胞证	国际/境内均可

paxType	出发时年龄	占座
`INF`（婴儿）	不足 2 岁	不占座
`CHD`（儿童）	2 岁（含）至 12 岁（不含）	占座
`ADT`（成人）	12 岁及以上	占座

⚠️ 国际航线禁止使用身份证（ID）。每成人最多携带 2名儿童 和 1名婴儿。

orderDetail

查询已下单的机票订单详情。

必填参数

参数	类型	说明
`orderNo`	string	booking 返回的订单号

返回字段

字段	说明
`orderNo`	订单号
`orderStatus`	订单状态
`priceDisplay`	总价
`createTime`	下单时间
`segments`	航班航段信息
`passengers`	乘客信息
`ticketNos`	出票票号（出票后才有）

五完整调用示例

以下为单成人预订香港→曼谷国际机票的完整四步流程：

搜索航班

json

{ "origin": "HKG", "destination": "BKK", "depDate": "2026-08-01" }

从返回的 flights 列表中选择 offerId 传给下一步。

验价锁定

json

{ "offerId": "21725576870629376120", "adultNum": 1 }

从返回的 meta 中取 verifyOfferId 和 requiredPassengerFields.cardType.allowedValues。

提交下单

json

{
  "verifyOfferId": "2172558470381977600",
  "passengersJson": "[{
    \"name\": \"ZHANG/SAN\",
    \"paxType\": \"ADT\",
    \"gender\": \"M\",
    \"birthday\": \"1990-01-01\",
    \"cardType\": \"PP\",
    \"cardNum\": \"E12345678\",
    \"cardIssuedPlace\": \"CN\",
    \"cardExpiryDate\": \"2030-12-31\",
    \"nationality\": \"CN\"
  }]",
  "allowedCardTypes": ["PP", "GA", "HX", "TB"]
}

返回 orderNo 和 payUrl，引导用户前往支付。

查询订单

json

{ "orderNo": "21725493286277120" }

六常见错误码

错误码	说明	处理建议
AUTH_FAILED	鉴权失败	检查 X-Cid 和 X-Passkey，passkey 必须恰好 16 位
PARAM_INVALID	参数校验不通过	查看 msg 字段了解具体原因（姓名格式/证件类型/年龄不符等）
10701298	offerId 已失效（之前验价失败）	重新调用 shopping 获取新的 offerId
20901997	验价失败	人数与搜索时不一致，或该航班不支持儿童票
OFFER_ID_EXPIRED	offerId 已过期（超30分钟）	重新搜索获取新 offerId
PASSENGER_NUM_DIFF	乘客人数与验价不一致	确保 booking 的乘客数量与 pricing 时一致
ACCOMPANIED_PAX_ID	accompaniedPaxId 无效	CHD/INF 的 accompaniedPaxId 必须指向列表中存在的 ADT

七注意事项

1流程顺序不可跳过：必须按 shopping → pricing → booking 顺序调用，不能直接 booking。
2验价有效期：pricing 锁价后 30 分钟内有效，超时需重新验价。
3儿童票搜索：搜索时即需传入 childNum，验价时人数必须与搜索时一致。
4国际航线证件：国际航线不支持身份证（ID），必须使用护照（PP）等国际证件。
5婴儿规则：INF 不占座；每成人只能携带 1 名婴儿，最多携带 2 名儿童。
6幂等下单：网络不稳定场景建议传入 idempotencyKey（UUID 格式），防止重复下单。
7支付入口：下单成功后通过 payUrl 跳转至 B2B 订单页面完成支付。

FR24 International Flights MCP Integration Guide

Full workflow for international flight search, price verification, booking, and order lookup — compatible with Cursor, Claude Code, Codex, WorkBuddy, OpenClaw, and other AI Agent clients.

1Overview

The standard booking flow must be called in sequence — steps cannot be skipped:

① shopping
Search flights

→

② pricing
Lock price

→

③ booking
Submit booking

→

④ orderDetail
Query order

2Contact (Get CID & Passkey)

Integration requires FR24-assigned Buyer ID (X-Cid) and 16-character secret (X-Passkey). Apply as follows:

Application Process

1Business contact: Reach FR24 business team via contacts below with your company, use case, and estimated volume.
2Qualification review: Submit company credentials; FR24 completes review within 1–3 business days.
3Credential issuance: After approval, your account manager sends X-Cid and X-Passkey (16-char secret).
4Integration testing: Configure using the Section 3 examples; contact technical support if needed.

Contact Information

📧

Business Email

bd@flightroutes24.com

💬

Business WeChat

🌐

B2B Platform

b2b.flightroutes24.com

🛠️

Technical Support

tech@flightroutes24.com

⚠️ Security: X-Passkey is a core credential. Never commit to public repos or share with third parties. Contact support immediately if compromised.

3Configuration

3.1 Endpoint

Environment	MCP Endpoint
Production	`https://mcp.fr24.ai/mcp`

3.2 Authentication

Pass credentials via HTTP Headers:

Header	Description	Example
`X-Cid`	Buyer ID (assigned by FR24)	`FRG`
`X-Passkey`	Buyer secret — must be exactly 16 characters (AES-128 + SHA512 signing)	`your16charpasskey`

⚠️ Passkey must be exactly 16 bytes. Incorrect length returns an authentication failure.

3.3 Client Configuration

This service supports all MCP-compatible AI Agent clients. Auth headers are consistent: X-Cid for buyer ID, X-Passkey for the 16-character secret.

① Cursor

Create or edit .cursor/mcp.json in your project root:

json.cursor/mcp.json

{
  "mcpServers": {
    "fr-flight-mcp": {
      "url": "https://mcp.fr24.ai/mcp",
      "headers": {
        "X-Cid": "YOUR_CID",
        "X-Passkey": "YOUR_16CHAR_PASSKEY"
      }
    }
  }
}

② Claude Code

Use .mcp.json (project-level or ~/.mcp.json). CLI alternative:claude mcp add --transport http fr-flight-mcp https://mcp.fr24.ai/mcp -H "X-Cid:YOUR_CID" -H "X-Passkey:YOUR_16CHAR_PASSKEY"

json.mcp.json

{
  "mcpServers": {
    "fr-flight-mcp": {
      "type": "http",
      "url": "https://mcp.fr24.ai/mcp",
      "headers": {
        "X-Cid": "YOUR_CID",
        "X-Passkey": "YOUR_16CHAR_PASSKEY"
      }
    }
  }
}

③ Codex (OpenAI)

Add to ~/.codex/config.toml (HTTP transport):

toml~/.codex/config.toml

[mcp_servers.fr-flight-mcp]
transport = "http"
url = "https://mcp.fr24.ai/mcp"

[mcp_servers.fr-flight-mcp.headers]
X-Cid = "YOUR_CID"
X-Passkey = "YOUR_16CHAR_PASSKEY"

④ WorkBuddy

Add an HTTP MCP Server in WorkBuddy settings, or in workbuddy.mcp.json:

jsonworkbuddy.mcp.json

{
  "servers": {
    "fr-flight-mcp": {
      "transport": "http",
      "endpoint": "https://mcp.fr24.ai/mcp",
      "headers": {
        "X-Cid": "YOUR_CID",
        "X-Passkey": "YOUR_16CHAR_PASSKEY"
      }
    }
  }
}

⑤ OpenClaw

Configure streamable-http MCP in openclaw.config.json (or ~/.openclaw/mcp_servers.json):

jsonopenclaw.config.json

{
  "mcpServers": {
    "fr-flight-mcp": {
      "transport": "streamable-http",
      "url": "https://mcp.fr24.ai/mcp",
      "headers": {
        "X-Cid": "YOUR_CID",
        "X-Passkey": "YOUR_16CHAR_PASSKEY"
      }
    }
  }
}

ℹ️ Replace YOUR_CID and YOUR_16CHAR_PASSKEY with credentials assigned by FR24. See Section 2 — Contact to apply.

4Tools Reference

shopping

Search international flights. Supports 6 search modes. Returns up to 10 results.

Required Parameters

Parameter	Type	Description
`origin`	string	Origin IATA code, e.g. `PEK` (Beijing), `HKG` (Hong Kong)
`destination`	string	Destination IATA code, e.g. `BKK` (Bangkok), `NRT` (Tokyo)
`depDate`	string	Departure date, format `yyyy-MM-dd`

Optional Parameters

Parameter	Type	Description
`adultNum`	integer	Adults, default 1
`childNum`	integer	Children (ages 2–12), default 0
`infantNum`	integer	Infants (under 2), default 0
`retDate`	string	Return date; omit for one-way
`searchMode`	string	Search mode (see table below)
`departureTimeRange`	string	[TIME mode] e.g. `06:00-12:00`
`priceRange`	string	[PRICE mode] e.g. `500-2000`
`flightNo`	string	[FLIGHT mode] e.g. `CA1234`
`cabin`	string	[CABIN mode] Y=economy C=business F=first P=premium economy

searchMode Reference

Value	Description	Companion Parameter
Omit	Default search, sorted by price	—
`TIME`	Filter by departure time window	`departureTimeRange`
`PRICE`	Filter by total price range	`priceRange`
`FLIGHT`	Search by flight number	`flightNo`
`TRANSFER`	Connecting flights only	—
`CABIN`	Filter by cabin class	`cabin`

Request Examples

json

// Default search
{ "origin": "HKG", "destination": "BKK", "depDate": "2026-08-01" }

// Filter by time window (morning)
{ "origin": "PEK", "destination": "NRT", "depDate": "2026-08-10",
  "searchMode": "TIME", "departureTimeRange": "06:00-12:00" }

// Round-trip search
{ "origin": "SZX", "destination": "BKK",
  "depDate": "2026-08-15", "retDate": "2026-08-20" }

// Search with child passenger
{ "origin": "HKG", "destination": "SIN", "depDate": "2026-08-01",
  "adultNum": 1, "childNum": 1 }

Response Fields

Field	Description
`flightNo`	Flight number
`airline`	Airline name
`cabin`	Cabin (economy / business / first)
`depAirport`	Departure airport, format `CODE(City)`, e.g. `HKG(Hong Kong Intl)`
`depTime`	Departure time, format `MM-dd HH:mm`
`arrAirport`	Arrival airport, same format
`arrTime`	Arrival time
`duration`	Duration, e.g. `3h45m`
`type`	Direct / connecting
`priceDisplay`	Total price with currency, e.g. `1200 CNY`
`remainingSeats`	Remaining seats
`seatsAlert`	Low-seat alert when ≤ 3 seats remain
`refundPolicy`	Refund/change policy

pricing

Lock the selected fare for 30 minutes. Must be called after shopping and before booking.

⚠️ When traveling with children/infants, adultNum/childNum/infantNum must match the shopping request.

Required Parameters

Parameter	Type	Description
`offerId`	string	offerId from shopping response

Optional Parameters

Parameter	Type	Description
`adultNum`	integer	Adults, default 1; must match search
`childNum`	integer	Children, default 0
`infantNum`	integer	Infants, default 0

Response Fields

Field	Location	Description
`priceDisplay`	top level	Locked total price with currency
`priceBreakdown`	top level	Price breakdown (multi-passenger)
`remainingSeats`	top level	Remaining seats
`msg`	top level	Message
`meta.verifyOfferId`	meta	verifyOfferId for booking
`meta.isInternational`	meta	Whether international route
`meta.requiredPassengerFields`	meta	Required passenger fields; `cardType.allowedValues` lists allowed ID types

requiredPassengerFields Example

json

{
  "birthday": true,
  "gender": true,
  "cardNum": true,
  "cardType": {
    "required": true,
    "allowedValues": ["PP", "GA", "HX", "TB"]  // international routes exclude ID
  },
  "cardIssuedPlace": true,
  "cardExpiryDate": true,
  "nationality": true,
  "paxEmail": false,
  "paxMobile": false
}

ℹ️ allowedValues excludes ID (national ID) on international routes. cardType must be chosen from this list when booking.

booking

Submit a flight booking. Supports multiple passengers (adults, children, infants).

Required Parameters

Parameter	Type	Description
`verifyOfferId`	string	`meta.verifyOfferId` from pricing
`passengersJson`	string	Passenger list as JSON array string (see format below)

Optional Parameters

Parameter	Type	Description
`allowedCardTypes`	array	cardType.allowedValues from pricing — strongly recommended
`departureDate`	string	Departure date for age validation (may be auto-filled from cache)
`contactName`	string	Contact name (defaults to first passenger)
`contactMobile`	string	Contact mobile
`contactEmail`	string	Contact email
`idempotencyKey`	string	Idempotency key (UUID); same key within 24h creates only one order
`partnerOrderNo`	string	Partner custom order number

passengersJson Passenger Fields

Field	Required	Description
`name`	Required	Surname/given name in UPPERCASE, e.g. `ZHANG/SAN`
`paxType`	Required	`ADT`=adult / `CHD`=child / `INF`=infant
`gender`	Required	`M`=male / `F`=female
`birthday`	Required	Date of birth, format `yyyy-MM-dd`
`cardType`	Required	ID type; must be in allowedValues
`cardNum`	Required	ID number, max 20 chars
`cardIssuedPlace`	Conditional	ID issuing country, ISO 2-letter code, e.g. `CN`
`cardExpiryDate`	Conditional	ID expiry date, format `yyyy-MM-dd`
`nationality`	Conditional	Nationality, ISO 2-letter code, e.g. `CN`
`areaCode`	Optional	Mobile area code, default `86`
`paxMobile`	Optional	Contact phone
`paxEmail`	Optional	Contact email
`accompaniedPaxId`	Required for CHD/INF	Linked adult index (from 1), e.g. `"1"`

ID Types & Age Rules

Code	Description	Applicable Routes
`ID`	National ID	Domestic routes only
`PP`	Passport	International and domestic
`GA`	HK/Macau travel permit	International and domestic
`HX`	Home Return Permit	International and domestic
`TB`	Taiwan Compatriot Permit	International and domestic

paxType	Age at departure	Seat
`INF` (Infant)	Under 2 years	No seat
`CHD` (Child)	2 years (inclusive) to under 12 years	Seat
`ADT` (Adult)	12 years and above	Seat

⚠️ National ID (ID) is not allowed on international routes. Max 2 children and 1 infant per adult.

orderDetail

Query details of a submitted order.

Required Parameters

Parameter	Type	Description
`orderNo`	string	Order number from booking

Response Fields

Field	Description
`orderNo`	Order number
`orderStatus`	Order status
`priceDisplay`	Total price
`createTime`	Booking time
`segments`	Flight segments
`passengers`	Passenger info
`ticketNos`	Ticket numbers (after ticketing)

5Full Example

Complete four-step flow for one adult, HKG → BKK:

Search flights

json

{ "origin": "HKG", "destination": "BKK", "depDate": "2026-08-01" }

Pick an offerId from the flights list for the next step.

Verify & lock

json

{ "offerId": "21725576870629376120", "adultNum": 1 }

Take verifyOfferId and requiredPassengerFields.cardType.allowedValues from meta.

Submit booking

json

{
  "verifyOfferId": "2172558470381977600",
  "passengersJson": "[{
    \"name\": \"ZHANG/SAN\",
    \"paxType\": \"ADT\",
    \"gender\": \"M\",
    \"birthday\": \"1990-01-01\",
    \"cardType\": \"PP\",
    \"cardNum\": \"E12345678\",
    \"cardIssuedPlace\": \"CN\",
    \"cardExpiryDate\": \"2030-12-31\",
    \"nationality\": \"CN\"
  }]",
  "allowedCardTypes": ["PP", "GA", "HX", "TB"]
}

Returns orderNo and payUrl for payment.

Query order

json

{ "orderNo": "21725493286277120" }

6Common Error Codes

Error Code	Description	Resolution
AUTH_FAILED	Authentication failed	Check X-Cid and X-Passkey; passkey must be exactly 16 chars
PARAM_INVALID	Invalid parameters	See msg field for details (name format, ID type, age mismatch, etc.)
10701298	offerId invalid (previous verify failed)	Run shopping again for a new offerId
20901997	Price verification failed	Passenger count mismatch or flight does not support child fares
OFFER_ID_EXPIRED	offerId expired (>30 minutes)	Search again for a new offerId
PASSENGER_NUM_DIFF	Passenger count differs from verify step	Ensure booking passenger count matches pricing
ACCOMPANIED_PAX_ID	Invalid accompaniedPaxId	accompaniedPaxId for CHD/INF must reference an ADT in the list

7Important Notes

1Do not skip steps: call shopping → pricing → booking in order; do not book directly.
2Price lock from pricing is valid for 30 minutes; re-verify after timeout.
3Child fares: pass childNum at search time; verify must use the same counts.
4International routes do not accept national ID (ID); use passport (PP) or other international documents.
5Infants (INF) have no seat; max 1 infant and 2 children per adult.
6For unstable networks, pass idempotencyKey (UUID) to prevent duplicate bookings.
7Payment: after booking, complete payment via payUrl on the B2B order page.