b450b512a2
- 添加 mipu-api 作为 git submodule (Claude Code Skill) - 迁移 API 文档源文件到 docs/ 目录统一维护 - 添加 Gitea Actions 工作流：tag推送自动打包docs并发布Release - Skill 运行时自动从 mipu-open Release 下载最新文档 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
145 lines
4.9 KiB
Markdown
145 lines
4.9 KiB
Markdown
<!-- mipuyun-api-doc: cache-search -->
|
||
# cache/search - 查询航司缓存数据
|
||
|
||
# 缓存票价搜索（cache/search）API 说明文档
|
||
|
||
## 用户使用场景
|
||
|
||
> 用户希望以低成本，高性能的模式获取航司的价格数据，该数据源为我司缓存库内容，非实时提取航司数据。
|
||
|
||
## 错误场景(不应该使用本接口的场景)
|
||
|
||
> 本接口不会与航司产生任何交互，无法保障在响应时刻价格/库存与航司完全一致。
|
||
|
||
## 性能指标
|
||
|
||
> - 航司路线&旅行日期覆盖率：按航司提供，平均值为180天内>90%。
|
||
> - 价格准确率（验价变价率）：<85%
|
||
|
||
## 请求说明
|
||
|
||
| **请求地址** | https://${endpoint}/cache/search |
|
||
| --- | --- |
|
||
| **请求方法** | POST |
|
||
| **注意事项** | Header必须带压缩请求。 |
|
||
|
||
## 请求参数
|
||
|
||
### Header
|
||
|
||
| **参数名称** | **类型** | **是否必选** | **示例值** | **说明** |
|
||
| --- | --- | --- | --- | --- |
|
||
| Content-Type | String | 是 | application/json | 固定值，指定请求体格式为 JSON |
|
||
| Accept-Encoding | String | 是 | gzip, deflate, br | 必须要填写，否则服务器会拒绝。 |
|
||
| client-key | String | 是 | xxxxx | 联系我们获取生产环境key |
|
||
| client-secret | String | 是 | xxxxx | 联系我们获取生产环境secret |
|
||
|
||
###
|
||
|
||
### 请求体
|
||
|
||
注灰色背景为高级特性，默认不不填写，根据需要进行开发。
|
||
|
||
```json
|
||
{
|
||
"journeyType": "OW",
|
||
"origin": "MIL",
|
||
"destination": "CAG",
|
||
"departureDate": "20251118",
|
||
"adults": 1,
|
||
"children": 0,
|
||
"infants": 0,
|
||
"agent": "u2web"
|
||
}
|
||
```
|
||
|
||
| **参数名称** | **类型** | **是否必选** | **示例值(默认值)** | **说明** |
|
||
| --- | --- | --- | --- | --- |
|
||
| journeyType | String | 是 | "OW" | 行程为单程还是往返程OW：单程OneWayRT：往返RoundTrip |
|
||
| origin | String | 是 | "CJJ" | 出发地，为IATA 3字码兼容城市或者机场3字码 |
|
||
| originAirport | String | 否 | | |
|
||
| destination | String | 是 | "SHA" | 到达地，为IATA3字码兼容城市或者机场3字码 |
|
||
| destinationAirport | String | 否 | | |
|
||
| departureDate | String | 是 | 20240326 | 出发日期，格式为 `YYYYMMDD`（如 2024 年 5 月 1 日为 20240501） |
|
||
| returnDate | String | 否 | 20240423（仅 RT 必填） | 返程日期，格式同 departureDate，仅当 journeyType=RT 时必传，OW 时可传空 |
|
||
| adults | Integer | 是 | 2 | 成人，乘机人数量 |
|
||
| children | Integer | 是 | 1 | 儿童，乘机人数量 |
|
||
| infants | Integer | 是 | 0 | 婴儿，乘机人数量 |
|
||
| agent | String | 是 | "F9-web" | 你自行定义的F9执行器编码（Agent Code） |
|
||
| proxy | String | 是 | | 本次获取航司数据采用的代理方式。如果需要指定代理国家请在代理用户后面加上国家二字码。如myproxy-USUS代表美国 |
|
||
| acceptCacheMinutes | Integer | 否 | 5 | 默认值：5**如无特殊情况，本参数不建议设置或调整。**为了避免频繁请求航司设置的缓存，用户可以指定缓存时长，不填写为5。 |
|
||
|
||
## 返回参数
|
||
|
||
探索一个返回参数json，https://jsonhero.io/j/XmTLWK94Ae5X
|
||
|
||
| 参数名称 | 类型 | 示例值 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| itineraries | Array<Itinerary> | - | 航线组合列表，包含不同航班拼接的行程方案 |
|
||
| code | Integer | 0 | 系统状态码：0 = 成功，非 0 为失败 |
|
||
| msg | String | null | 系统消息：成功时为 null，失败时返回具体系统提示信息 |
|
||
| sessionId | String | 66d807b0-abbc-4b57-aeff-bbf4fc29fb75 | UUID: 与航司通信的session值，可以用于加速后续动作，如继续获取包裹，选座，下单。 |
|
||
|
||
# 常见问题
|
||
|
||
## origin/originAirport的区别是什么？
|
||
|
||
origin：出发地，建议传入IATA规定的城市码，必填
|
||
|
||
originAirport：出发机场，非必填
|
||
|
||
由于各个数据源对于城市码/机场码的需求场景不一致，服务端做了兼容处理。
|
||
|
||
一般情况只需要传入Origin(城市码)，我们会自动将Origin翻译为机场码，并对航司进行轮询获取所有数据。
|
||
|
||
部分特殊情况，如只需要搜索单个机场码，或者直接搜索城市码，不希望服务端转换为机场码，请将需要搜索的三字码直接放入OriginAirport。
|
||
|
||
**举例：**
|
||
|
||
入参：origin: LON。
|
||
|
||
不传入originAirport， 服务端发送给航司originAirport: LCY, LGW, LHR, LTN, SEN, STN
|
||
|
||
传入originAirport: LCY, 服务端实际发送给航司originAirport: LCY
|
||
|
||
传入originAirport: LON, 服务端实际发送给航司 originAirport: LON
|
||
|
||
**destination/destinationAirport逻辑同origin/originAirport**
|
||
|
||
##
|
||
|
||
# 业务案例
|
||
|
||
## 单人单程搜索
|
||
|
||
### 请求（Request）
|
||
|
||
```objective-c
|
||
|
||
```
|
||
|
||
### 请求（Response）
|
||
|
||
---
|
||
|
||
## 转机行程搜索
|
||
|
||
### 请求（Request）
|
||
|
||
```json
|
||
{
|
||
"journeyType": "OW",
|
||
"origin": "BOM",
|
||
"destination": "CNX",
|
||
"departureDate": "20251118",
|
||
"adults": 1,
|
||
"children": 0,
|
||
"infants": 0
|
||
}
|
||
```
|
||
|
||
### 响应（Response）
|
||
|
||
在线查看：https://jsonhero.io/j/J0LMhczR0bJM/editor
|
||
|