> For AI agents: the complete documentation index is available at /apps-plugin/docs/llms.txt, the full documentation bundle is available at /apps-plugin/docs/llms-full.txt.

# 卡片相关 API

> **阅读提示**：本文介绍豆包应用插件卡片相关的服务端 API。当前提供「刷新卡片实例」接口，用于在卡片下发后主动更新卡片数据。后续会陆续开放更多卡片操作接口。

## 接口列表

| 接口     | 方法   | 路径                               | 说明                             |
| ------ | ---- | -------------------------------- | ------------------------------ |
| 刷新卡片实例 | POST | `/api/card/v1/developer/refresh` | 按 `refresh_key` 批量更新已下发卡片的展示数据 |

## 基本概念

### refresh\_key

`refresh_key` 是卡片的刷新标识。你需要在 Manifest 的实体 schema 中，通过 `is_refresh_key: true` 声明哪个字段作为刷新键；卡片下发时，该字段的值会作为卡片的 `refresh_key`。

服务端可以使用 `refresh_key` 调用「刷新卡片实例」接口，在不打扰用户的前提下，主动更新匹配卡片的展示内容。刷新操作按 `refresh_key` 匹配卡片实例，**不区分用户和会话**，同一个 `refresh_key` 下的所有卡片实例都会被刷新。

## 刷新卡片实例

按 `refresh_key` 全量刷新匹配的卡片实例。调用时可选择“直接数据刷新”或“工具结果刷新”两种模式；未传 `refresh_mode` 时，默认使用直接数据刷新。无论使用哪种方式，卡片的 `widget_id` 等身份信息均保持不变。

### 刷新方式

| `refresh_mode`    | 刷新模式       | 行为                                                              |
| ----------------- | ---------- | --------------------------------------------------------------- |
| 不传或 `widget_data` | 直接数据刷新（默认） | 将请求中的 `structured_content` 作为完整的新 `widget_data`，直接覆盖卡片当前展示数据。   |
| `tool_result`     | 工具结果刷新     | 按卡片**首次下发时**记录的应用版本、工具和模板，重新解释工具结果，同时生成新的 `widget_data` 和模型上下文。 |

`refresh_mode` 只能是字符串 `widget_data` 或 `tool_result`。接口只接受文档列出的字段。

### 使用限制

- 单次请求最多刷新 **10** 个卡片实例。如果匹配到的卡片数量超过 10 个，请求将整体失败，不会部分执行。
- 刷新时使用的 `refresh_key` 必须与卡片下发时的值完全一致。
- 传入 `idempotency_key` 时，相同 `idempotency_key` 的重复请求会直接返回首次的处理结果，不会重复刷新。
- 传入 `sequence` 时，服务端会按序列号大小判断请求新旧；小于等于已处理序列号的请求将被拒绝。
- `tool_result` 方式仅支持具有完整首次下发来源的引用卡片；Inline、LegacyPack、共享卡片或来源版本、工具、模板不可追溯的卡片不会刷新。
- `tool_result` 方式会拒绝转换出零张或多张物理卡、转换后模板不匹配，或转换得到的刷新键与请求不一致的请求；这类请求不会部分更新 IM 卡片。

### 控制刷新体验

使用 `reload_card` 控制客户端处理最新卡片数据的方式：

| `reload_card` | 客户端行为                                                                  |
| ------------- | ---------------------------------------------------------------------- |
| 不传或为 `true`   | 客户端按常规方式处理最新卡片数据，可以重新加载或重建卡片。                                          |
| `false`       | 客户端会在条件允许时复用当前卡片容器，仅更新卡片数据。客户端不支持此能力，或卡片的标识、布局、尺寸、运行状态不满足复用条件时，仍会重建卡片。 |

`reload_card=false` 用于优先减少卡片刷新带来的界面重建，不保证卡片一定不会重建。接口成功仅表示服务端已完成本次刷新处理；客户端最终是否复用现有容器取决于设备和卡片的当前状态。

### 接口说明

- **业务场景**：当卡片对应的业务数据发生变化时（例如订单状态更新、库存变化、进度推进），服务端可以调用本接口，将最新数据推送给所有持有该卡片的用户，无需用户重新发起对话。

- **前提条件**：

  - 已在豆包开发者平台完成应用创建，获取到 `app_id` 和 `app_secret`。
  - 已通过“获取应用级 Access Token”接口获取有效的应用级 Access Token。
  - 已在 Manifest 中通过 `is_refresh_key: true` 声明了卡片的刷新键字段，且服务端已记录下发卡片时使用的 `refresh_key` 值。

- **注意事项**：

  - 直接数据刷新（`widget_data`）中，`structured_content` 是卡片的完整新数据，将直接作为卡片的 `widget_data` 覆盖原有内容，不是增量更新。请确保传入的是完整、可直接渲染的卡片数据。
  - 工具结果刷新（`tool_result`）中，`content` 可省略，省略时按空数组处理；传入时必须是合法的 JSON 数组。`content` 和 `structured_content` 共同作为工具结果输入，最终写入模型上下文的内容由首次下发版本中的 `model_view` 规则生成，不直接透传请求字段。
  - 刷新操作按 `refresh_key` 匹配所有卡片实例，不区分用户和会话。
  - 建议为每次刷新生成唯一的 `idempotency_key`，并在网络异常或超时后使用相同的 `idempotency_key` 重试，避免重复刷新。

### 基本信息

<table><colgroup><col width="200"/><col width="200"/></colgroup><tbody><tr><td><strong>名称</strong></td><td><strong>描述</strong></td></tr><tr><td>HTTP Path</td><td>/api/card/v1/developer/refresh</td></tr><tr><td>HTTP Method</td><td>POST</td></tr><tr><td>Scope</td><td>无需特殊 Scope</td></tr><tr><td>权限要求</td><td>使用应用级 Access Token 鉴权，无需用户授权</td></tr></tbody></table>

### 请求头

<table><colgroup><col width="200"/><col width="200"/><col width="200"/><col width="200"/></colgroup><tbody><tr><td><strong>名称</strong></td><td><strong>类型</strong></td><td><strong>必填</strong></td><td><strong>描述</strong></td></tr><tr><td>content-type</td><td>string</td><td>是</td><td>固定值 "application/json"</td></tr><tr><td>X-DB-AccessToken</td><td>string</td><td>是</td><td>应用级 Access Token，通过“获取应用级 Access Token”接口获取</td></tr></tbody></table>

### 请求参数

#### 直接数据刷新（`widget_data`）请求体

<table><colgroup><col width="200"/><col width="200"/><col width="200"/><col width="200"/><col width="200"/></colgroup><tbody><tr><td><strong>名称</strong></td><td><strong>类型</strong></td><td><strong>是否必填</strong></td><td><strong>描述</strong></td><td><strong>示例值</strong></td></tr><tr><td>refresh_key</td><td>string</td><td>是</td><td>刷新键，用于匹配需要更新的卡片实例。该值来自 Manifest 中被 <code>is_refresh_key: true</code> 标记的字段，卡片下发时该字段的值即为 refresh_key。刷新时必须与下发时完全一致。</td><td>order_123456</td></tr><tr><td>structured_content</td><td>object</td><td>条件必填</td><td>当前规范字段。卡片的完整新数据，将直接作为卡片的 <code>widget_data</code> 覆盖原有内容。必须是合法的 JSON 对象。</td><td>{"title":"订单已发货","status":"shipped"}</td></tr><tr><td>reload_card</td><td>boolean</td><td>否</td><td>是否按常规方式重新加载卡片。默认值为 <code>true</code>。传入 <code>false</code> 时，客户端会在条件允许时优先复用当前卡片容器并更新数据；不满足条件时仍会重建卡片。</td><td>false</td></tr><tr><td>content</td><td>array</td><td>否</td><td>内容数组，会被加入到模型上下文中对模型可见。如不需要模型感知刷新内容可不传。传入时必须是合法的 JSON 数组。</td><td>[{"type":"text","text":"订单已发货"}]</td></tr><tr><td>sequence</td><td>integer</td><td>否</td><td>序列号，必须为正整数。用于保证同一 refresh_key 下多次刷新的顺序，小于等于已处理序列号的请求将被拒绝。</td><td>2</td></tr><tr><td>idempotency_key</td><td>string</td><td>否</td><td>幂等键。相同幂等键的重复请求会直接返回首次的处理结果，不会重复刷新。建议在网络异常重试时使用相同的幂等键。</td><td>refresh_20260716_001</td></tr></tbody></table>

#### `tool_result` 方式的字段约束

除上述通用字段外，`tool_result` 请求增加 `refresh_mode: "tool_result"`，并使用以下约束：

| 字段                   | 类型             | 是否必填 | 约束                                                                                       |
| -------------------- | -------------- | ---- | ---------------------------------------------------------------------------------------- |
| `refresh_mode`       | string         | 是    | 固定为 `tool_result`。                                                                       |
| `structured_content` | object 或 array | 是    | 原始工具结果的结构化部分，必须符合**首次下发该卡的工具**在 Manifest 中声明的 schema。不能将直接数据刷新的 `widget_data` 直接作为该字段传入。 |
| `content`            | array          | 否    | 原始工具结果的内容部分；省略时按 `[]` 处理。                                                                |
| `refresh_key`        | string         | 是    | 必须与转换后的工具结果中的刷新键一致；不能借本接口迁移历史卡的刷新键。                                                      |

服务端从历史卡中读取首次下发时的应用版本、工具和模板，开发者不能在本次请求中覆盖它们。转换成功后，每个卡片实例分别得到一对结果：用于 IM 渲染的 `widget_data`，以及按 `model_view` 投影后的模型上下文。IM 更新成功后，模型上下文才会异步写入该卡片的新版本；`card_instance_refresh_key` 关系保持不变。

### 请求示例

#### 直接数据刷新（`widget_data`）请求示例

以下示例将完整的展示数据直接写入卡片；`reload_card: false` 表示客户端在条件允许时优先复用当前卡片容器：

```bash
curl -X POST 'https://api.doubao-dev.com/api/card/v1/developer/refresh' \
  -H 'Content-Type: application/json' \
  -H 'X-DB-AccessToken: <ACCESS_TOKEN>' \
  -d '{
    "refresh_key": "order_123456",
    "structured_content": {
      "title": "订单已发货",
      "status": "shipped"
    },
    "reload_card": false,
    "idempotency_key": "refresh_20260908_001"
  }'
```

#### `tool_result` 请求示例

下面示例假设首次下发卡片的工具 schema 以 `structuredContent.entities` 为实体根。实际字段必须以该工具的 Manifest 为准：

```bash
curl -X POST 'https://api.doubao-dev.com/api/card/v1/developer/refresh' \
  -H 'Content-Type: application/json' \
  -H 'X-DB-AccessToken: <ACCESS_TOKEN>' \
  -d '{
    "refresh_key": "order_123456",
    "refresh_mode": "tool_result",
    "content": [
      {"type": "text", "text": "订单已发货"}
    ],
    "structured_content": {
      "entities": [
        {
          "entity_type": "order",
          "order_id": "order_123456",
          "status": "shipped"
        }
      ]
    },
    "idempotency_key": "refresh_20260908_002"
  }'
```

### 响应参数

<table><colgroup><col width="200"/><col width="200"/><col width="200"/><col width="200"/><col width="200"/></colgroup><tbody><tr><td><strong>名称</strong></td><td><strong>类型</strong></td><td><strong>是否必填</strong></td><td><strong>描述</strong></td><td><strong>示例值</strong></td></tr><tr><td>code</td><td>integer</td><td>是</td><td>响应状态码，0 表示成功，非 0 表示失败。</td><td>0</td></tr><tr><td>msg</td><td>string</td><td>是</td><td>响应状态描述信息。</td><td>success</td></tr><tr><td>log_id</td><td>string</td><td>是</td><td>日志 ID，用于问题排查时提供给技术支持。</td><td>20260716120000ABCDEF123456</td></tr><tr><td>data</td><td>object</td><td>否</td><td>响应数据对象，详见下方 data 字段说明。请求失败时可能为 null。</td><td>-</td></tr></tbody></table>

#### data 字段说明

<table><colgroup><col width="200"/><col width="200"/><col width="200"/><col width="200"/><col width="200"/></colgroup><tbody><tr><td><strong>名称</strong></td><td><strong>类型</strong></td><td><strong>是否必填</strong></td><td><strong>描述</strong></td><td><strong>示例值</strong></td></tr><tr><td>status</td><td>string</td><td>是</td><td>刷新结果状态，取值见下方 status 枚举。</td><td>success</td></tr><tr><td>matched_count</td><td>integer</td><td>是</td><td>匹配到的卡片实例数量。</td><td>3</td></tr><tr><td>success_count</td><td>integer</td><td>是</td><td>刷新成功的卡片实例数量。</td><td>3</td></tr><tr><td>failed_count</td><td>integer</td><td>是</td><td>刷新失败的卡片实例数量。</td><td>0</td></tr><tr><td>errors</td><td>array</td><td>否</td><td>错误明细列表，仅在存在失败实例时返回。每个元素包含错误码和该错误对应的实例数量。</td><td>[{"code":"stale_sequence","count":1}]</td></tr></tbody></table>

`status` 枚举：

<table><colgroup><col width="244"/><col width="244"/><col width="244"/></colgroup><tbody><tr><td>值</td><td>说明</td><td>建议处理</td></tr><tr><td><code>success</code></td><td>所有匹配的卡片实例均刷新成功</td><td>无需额外处理</td></tr><tr><td><code>partial_success</code></td><td>部分卡片实例刷新成功，部分失败</td><td>查看 errors 字段了解失败原因，对失败实例可稍后重试</td></tr><tr><td><code>failed</code></td><td>所有匹配的卡片实例均刷新失败</td><td>查看 errors 字段了解失败原因，修正后重试</td></tr></tbody></table>

`errors` 元素字段：

<table><colgroup><col width="200"/><col width="200"/><col width="200"/><col width="200"/></colgroup><tbody><tr><td><strong>名称</strong></td><td><strong>类型</strong></td><td><strong>是否必填</strong></td><td><strong>描述</strong></td></tr><tr><td>code</td><td>string</td><td>是</td><td>错误码，取值见下方 errors.code 枚举。</td></tr><tr><td>count</td><td>integer</td><td>是</td><td>该错误对应的卡片实例数量。</td></tr></tbody></table>

`errors.code` 枚举：

<table><colgroup><col width="244"/><col width="244"/><col width="244"/></colgroup><tbody><tr><td>值</td><td>说明</td><td>建议处理</td></tr><tr><td><code>invalid_argument</code></td><td>请求参数不合法</td><td>检查 refresh_key、structured_content 等字段是否符合要求</td></tr><tr><td><code>too_many_targets</code></td><td>匹配的卡片数量超过单次刷新上限</td><td>缩小 refresh_key 的匹配范围，或拆分刷新请求</td></tr><tr><td><code>request_processing</code></td><td>相同 refresh_key 的刷新请求正在处理中</td><td>稍后使用相同 idempotency_key 查询结果，或等待当前请求完成</td></tr><tr><td><code>stale_sequence</code></td><td>序列号已过期，小于等于已处理的序列号</td><td>使用更大的 sequence 值重新发起请求</td></tr><tr><td><code>widget_instance_message_not_found</code></td><td>部分卡片实例对应的消息不存在或已不可用</td><td>该实例无法刷新，可忽略或在后续对话中重新下发卡片</td></tr><tr><td><code>render_failed</code></td><td>卡片数据渲染失败</td><td>检查 structured_content 是否符合卡片模板的数据结构要求</td></tr><tr><td><code>im_update_failed</code></td><td>卡片消息更新失败</td><td>稍后重试，持续失败时联系技术支持并提供 log_id</td></tr><tr><td><code>internal_error</code></td><td>服务内部错误</td><td>稍后重试，持续失败时联系技术支持并提供 log_id</td></tr></tbody></table>

`tool_result` 方式还可能返回以下错误码：

| 错误码                                                                          | 说明                          | 建议处理                                   |
| ---------------------------------------------------------------------------- | --------------------------- | -------------------------------------- |
| `unsupported_creation_mode`                                                  | 历史卡不是支持的引用卡创建方式。            | 重新下发支持该方式的卡片，或使用直接数据刷新（`widget_data`）。 |
| `source_version_missing` / `source_tool_missing` / `source_metadata_invalid` | 无法恢复首次下发时的版本、工具或模板来源。       | 不要使用 `tool_result` 刷新该历史卡。             |
| `route_unavailable` / `instance_unavailable`                                 | 历史卡或其消息路由不可用。               | 重新下发卡片或稍后重试。                           |
| `manifest_version_not_found` / `source_tool_not_found`                       | 首次下发使用的 Manifest 版本或工具已不可用。 | 恢复对应版本配置，或重新下发卡片。                      |
| `source_rule_unavailable` / `source_rule_ambiguous`                          | 无法唯一恢复首次下发时的卡片规则。           | 检查首次下发版本的工具和模板配置。                      |
| `no_card_after_transform` / `multiple_cards_not_supported`                   | 工具结果按来源规则转换后不是恰好一张物理卡。      | 调整工具结果，使其与被刷新的单张历史卡对应。                 |
| `card_template_mismatch`                                                     | 转换结果的模板与历史卡当前模板不一致。         | 不要用该结果覆盖已切换模板的历史卡。                     |
| `refresh_key_mismatch`                                                       | 工具结果按来源规则得到的刷新键与请求不一致。      | 使用与工具结果一致的刷新键；本接口不迁移刷新键。               |

### 响应示例

#### 正常示例（全部成功）

```json
{
    "code": 0,
    "msg": "success",
    "log_id": "20260716120000ABCDEF123456",
    "data": {
        "status": "success",
        "matched_count": 3,
        "success_count": 3,
        "failed_count": 0
    }
}
```

#### 正常示例（部分成功）

```json
{
    "code": 0,
    "msg": "success",
    "log_id": "20260716120000ABCDEF123456",
    "data": {
        "status": "partial_success",
        "matched_count": 3,
        "success_count": 2,
        "failed_count": 1,
        "errors": [
            {
                "code": "widget_instance_message_not_found",
                "count": 1
            }
        ]
    }
}
```

#### 异常示例（参数错误）

```json
{
    "code": 40001,
    "msg": "param error: refresh_key is required",
    "log_id": "20260716120001ABCDEF654321",
    "data": null
}
```

#### 异常示例（匹配数量超限）

```json
{
    "code": 0,
    "msg": "success",
    "log_id": "20260716120000ABCDEF123456",
    "data": {
        "status": "failed",
        "matched_count": 12,
        "success_count": 0,
        "failed_count": 12,
        "errors": [
            {
                "code": "too_many_targets",
                "count": 12
            }
        ]
    }
}
```

### 错误码

<table><colgroup><col width="200"/><col width="200"/><col width="200"/><col width="200"/></colgroup><tbody><tr><td><strong>HTTP 状态码</strong></td><td><strong>错误码</strong></td><td><strong>描述</strong></td><td><strong>排查建议</strong></td></tr><tr><td>200</td><td>0</td><td>请求成功</td><td>请结合 data.status 判断刷新结果</td></tr><tr><td>200</td><td>40001</td><td>参数错误</td><td>请检查请求参数是否完整、格式是否正确，确认 refresh_key、structured_content 均已正确填写</td></tr><tr><td>200</td><td>500010003</td><td>应用级 Access Token 已过期</td><td>重新获取并缓存新的应用级 Access Token 后重试</td></tr><tr><td>200</td><td>500010004</td><td>应用级 Access Token 无效</td><td>检查令牌是否属于当前应用和环境，重新获取后重试</td></tr><tr><td>200</td><td>500000000</td><td>服务暂时无法完成请求</td><td>保留 log_id，稍后重试；持续失败时联系技术支持</td></tr></tbody></table>

> 当 `code` 为 `0` 时，仅表示请求被服务端正常接收和处理。卡片刷新的实际结果请以 `data.status` 和 `data.errors` 为准。
