<!-- mipuyun-api-doc: async-query -->
# async/query - 异步查询

# 异步查询（async/query）API 说明文档

## 用户使用场景

> 本接口目的是：
> 当异步调用API返回code:202时，通过本接口查询异步请求的结果。

## 使用时机

> 当异步调用API返回 `code: 202` 时，表示请求已接收并正在后台处理。
> 此时响应中会包含 `requestId`，使用本接口查询处理结果。

## 性能指标

> - 响应速度：毫秒级（直接从缓存读取）
> - 请求频率QPS：无限制
> - 数据保留时间：24小时

## 请求说明

| **请求地址** | https://${endpoint}/async/query/{requestId} |
| --- | --- |
| **请求方法** | GET |
| **注意事项** | Header 必须带认证信息。 |

## 请求参数

### Header

| **参数名称** | **类型** | **是否必选** | **示例值** | **说明** |
| --- | --- | --- | --- | --- |
| client-key | String | 是 | xxxxx | 联系我们获取生产环境 key |
| client-secret | String | 是 | xxxxx | 联系我们获取生产环境 secret |

### 路径参数

| **参数名称** | **类型** | **是否必选** | **示例值** | **说明** |
| --- | --- | --- | --- | --- |
| requestId | String | 是 | abc123-def456 | 异步请求返回的 requestId |

## 响应说明

### 有结果（请求已处理完成）

当异步请求已处理完成，**直接返回原始响应数据**（不包裹在统一响应结构中）。

**判断方式**：响应体中直接包含业务数据字段（如 `itineraries`、`bookingId` 等），无 `code` 字段包裹。

**示例 - 有结果（搜索）**：

```json
{
  "itineraries": [
    {
      "itineraryId": "xxx",
      "outbound": {
        "segments": [...]
      },
      "price": {
        "total": 1200.00
      }
    }
  ],
  "sessionId": "session-xxx"
}
```

**示例 - 有结果（预订）**：

```json
{
  "bookingId": "BK123456",
  "status": "HOLD",
  "expiryTime": "2025-01-20T12:00:00Z"
}
```

### 无结果（请求未找到或已过期）

当异步请求不存在或已过期时，返回 404 错误。

**判断方式**：响应体中 `code: 404`

**示例 - 无结果**：

```json
{
  "code": 404,
  "msg": "Not found"
}
```

**可能原因**：
1. `requestId` 不存在
2. 请求已过期（超过 24 小时）
3. 请求属于其他租户（clientCode 不匹配）

### 请求仍在处理中

当异步请求仍在处理中时，会返回处理中的状态。

**示例 - 处理中**：

```json
{
  "code": 202,
  "msg": "Processing",
  "requestId": "abc123-def456"
}
```

## 完整示例

### 请求示例

```bash
curl -X GET "https://api.example.com/async/query/abc123-def456" \
  -H "client-key: your-client-key" \
  -H "client-secret: your-client-secret"
```

### 响应示例（有结果）

```json
{
  "itineraries": [
    {
      "itineraryId": "itinerary-001",
      "outbound": {
        "segments": [
          {
            "carrier": "CA",
            "flightNumber": "CA123",
            "origin": "PEK",
            "destination": "SHA",
            "departureTime": "2025-01-20T08:00:00",
            "arrivalTime": "2025-01-20T10:00:00"
          }
        ]
      },
      "price": {
        "currency": "CNY",
        "total": 1200.00
      }
    }
  ],
  "sessionId": "session-xxx"
}
```

### 响应示例（无结果）

```json
{
  "code": 404,
  "msg": "Not found"
}
```

## 常见问题

### Q: 如何获取 requestId？

A: 当异步调用API返回 `code: 202` 时，响应中会包含 `requestId` 字段。

```json
{
  "code": 202,
  "msg": "Async request accepted",
  "requestId": "abc123-def456"
}
```

### Q: 结果会保留多久？

A: 异步请求的结果会保留 24 小时，超时后自动删除。

### Q: 可以查询其他租户的请求吗？

A: 不可以。接口会根据认证信息中的 clientCode 进行租户隔离，只能查询本租户的请求。

### Q: 建议的轮询策略是什么？

A: 建议每隔 2-5 秒查询一次，最多查询 10 次。如果 10 次后仍未获取结果，可能是航司响应较慢，建议稍后重试。