**版本：202601**

# 新增卡片内的块

**POST** `/openapi/2026-01/themes/edit-sessions/:oseid/sections/:section_id/blocks`

在编辑会话中，向某张卡片追加/插入一个块。

## 请求

**Path参数**

- `oseid` string (required)

  编辑会话 ID
- `section_id` string (required)

  文档内的 section 实例 ID；也可传全局卡片 id（`header`、`footer`、`announcement`、`cart_drawer`）

**application/json**

**请求体 | 示例**

**请求体 (required)**

- `doc_id` string (required)

  文档（模板文件）ID
- `theme_id` string (required)

  主题 ID（拼渲染上下文 url）
- `block` object (required)

  要新增的块对象，如 `{type, settings}`
- `index` int32

  在「父容器」blocks 中的 0 基插入位置（`parent_path` 为空时即 section 根）。传 -1（或大于末尾的值）追加到末尾。不传 = 0 = 插入到最前面
- `parent_path` int32[]

  从 section 根到「新块要插入的父块」的祖先下标路径（每个元素是某层 blocks 数组的 0 基下标）；空 = 插入到顶层。如 `parent_path=[1,0]` 配合 `index=-1` 追加到 `section.blocks[1].blocks[0].blocks` 末尾
- `template_name` string

  模板名；默认取文件 location 去掉 `.liquid`
- `locale` string

  渲染语言；默认 en\_US

```json
{
  "doc_id": "string",
  "theme_id": "string",
  "block": {},
  "index": 0,
  "parent_path": [
    0
  ],
  "template_name": "string",
  "locale": "string"
}
```

## 响应

**200**

OK

**application/json**

**数据结构 | 示例**

**数据结构**

- `code` string

  错误码
- `message` string

  错误信息
- `data` object

  - `section` object

    更新后的 section 对象
  - `html` string

    渲染后的 section HTML。目标为全局卡片（header / footer 等）时为空 —— 这类卡片不单独返回渲染结果

```json
{
  "code": "string",
  "message": "string",
  "data": {
    "section": {},
    "html": "string"
  }
}
```