# 用 Webhook 把连续扫码器的扫码记录推送到自己的系统

在台账上添加 Webhook 后，草料连续扫码器会把这个台账新录的每一条扫码记录，以 JSON 格式自动推送到你填的地址（URL）。你的系统收到后可以存进自己的数据库、发群消息、对接仓库或 ERP 系统，不用再到小程序里导出。

开始前请确认：

1. **接收地址**：一个以 `http://` 或 `https://` 开头、能从公网访问的地址，用来接收推送。公司内网地址收不到。
2. **台账创建者**：只有台账的创建者能添加和修改 Webhook，其他成员只能查看。

> **注**：草料二维码表单的 Webhook 是另一套功能，推送内容不同，见 [Webhook 说明文档](/help/integration-and-connection/data-api/webhook-webhook-guide)。

## 什么时候推送

每录一条扫码记录推送一次，推送时机如下：

| 情况 | 推不推 |
|------|------|
| 录了一条新记录 | 推。连续扫码时，扫下一条时推出上一条；不再扫的话，大约 1 分钟后推出 |
| 推出去之后又改了这条记录（改状态、补备注等） | 再推一次，内容是改后的 |
| 删除记录 | 不推 |
| 添加 Webhook 之前录的记录 | 不推，以后也不补推 |
| Webhook 关掉期间录的记录 | 不推，重新打开后也不补推 |

等一会儿再推，是因为扫完一条马上点状态、写备注是常有的事。等这条录完再推，收到的就是完整的内容。

## 一、打开台账的自动化设置

Webhook 在每个台账的「自动化设置」里配置，每个台账单独设置。

在草料连续扫码器里打开台账，点「流程设计」，切到最右边的「自动化设置」标签。

## 二、添加 Webhook 并填写地址

在「推送到你的系统」下点「添加 Webhook」，在弹出的窗口里填写：

| 配置项 | 说明 |
|------|------|
| URL | 接收推送的地址，以 `http://` 或 `https://` 开头，要能从公网访问 |
| 名称（可选） | 自己看的名字，比如「推到仓库系统」；不填就用地址里的域名 |

URL 下面的「更多设置」默认收起，一般不用改；接收方有要求时再点开：

| 配置项 | 说明 |
|------|------|
| 说明（可选） | 一句话写这个 Webhook 是做什么的 |
| 请求方法 | POST 或 GET，默认 POST |
| Headers（可选） | 接收方需要鉴权时填写，例如名称填 `Authorization`，值填接收方给的密钥 |

填好后点「保存」。Webhook 列表里这一行的开关打开就会推送，关掉就停止推送。一个台账可以添加多个 Webhook，每个地址都会收到同样的推送。

> **提示**：接收程序不会写的话，点「推送到你的系统」旁的「?」，再点「复制说明给 AI」，把复制的内容贴给你常用的 AI，让它照着写。复制的内容有推送规则、每个字段的意思和一份请求体示例；示例里的字段和这个台账一致，值是编的，不含真实记录。

## 三、确认接收方收到了推送

保存 Webhook 后扫一条码，接着扫下一条（或等 1 分钟），再到接收方查看有没有收到这条记录。

小程序里不显示每一次推送的结果，以接收方是否收到为准。接收方在 30 秒内返回 2xx 状态码（如 200）就算推送成功，返回的内容不看。

没收到时，依次检查：

1. 自动化设置里这个 Webhook 的开关是否打开；
2. URL 是否填对，能否从公网访问；
3. 接收方是否在 30 秒内返回了 2xx；
4. 接收方需要鉴权时，Headers 是否填对；
5. 这条记录是不是在添加 Webhook 之前录的。

## 推送的请求和请求体示例

每推一条记录，就向你的 URL 发一次 HTTP 请求：请求方法是配置里选的 POST 或 GET，请求头带 `Content-Type: application/json` 和你填的 Headers，请求体是下面这样的 JSON。

```json
{
  "version": 2,
  "task": {
    "id": "01a1ecc7-9096-7ab7-a369-b29094411c79",
    "name": "仓库入库"
  },
  "session": {
    "id": "01a1ecc8-d206-7873-b256-e6df7b489b02",
    "name": "batch-20261118-001",
    "label": "第1批 11月18日"
  },
  "record": {
    "recordId": "01a1ed13-9bb0-7016-8a0a-18f1ce5dd84c",
    "taskId": "01a1ecc7-9096-7ab7-a369-b29094411c79",
    "sessionId": "01a1ecc8-d206-7873-b256-e6df7b489b02",
    "recordUniqueNumber": "R4",
    "scanResult": "6901234567892",
    "scanType": "barcode",
    "scannedAt": "2026-11-18T05:14:09.283Z",
    "createdAt": "2026-11-18T05:14:09.928Z",
    "location": "浙江省杭州市西湖区文三路90号 30.274085,120.155070（精度35米）",
    "locationAddress": "浙江省杭州市西湖区文三路90号",
    "images": [
      "https://ncassets.clewm.net/rsrc/2026/1118/13/remark.jpg?auth_key=4070908800-..."
    ],
    "remark": "外箱有破损",
    "category": { "optionKey": "2", "optionLabel": "异常", "color": "#D23B2A" },
    "submitter": "张三",
    "sessionName": "batch-20261118-001",
    "sessionLabel": "第1批 11月18日"
  },
  "fields": [
    { "key": "noteText", "name": "备注", "type": "text", "value": "外箱有破损" },
    { "key": "category", "name": "状态", "type": "select", "value": { "key": "2", "label": "异常", "color": "#D23B2A" } },
    { "key": "cf_mwkxop4t_dq4r", "name": "数量", "type": "number", "value": 12 },
    { "key": "cf_mwkruld0_qq80", "name": "现场照片", "type": "image", "value": [] }
  ]
}
```

请求体分四块：

- `version`：推送格式的版本，现在是 `2`。
- `task`、`session`：这条记录属于哪个台账、哪个批次。
- `record`：这一次扫码本身的信息，比如扫到的内容、时间、位置、录入人。
- `fields`：台账「记录内容」里的字段，顺序和名字和小程序里一样。读备注、状态和你自己加的字段，请以 `fields` 为准。

## 请求体字段说明

### task：台账

| 字段 | 说明 |
|------|------|
| `id` | 台账 ID，不会变 |
| `name` | 台账名称 |

### session：批次

| 字段 | 说明 |
|------|------|
| `id` | 批次 ID，不会变 |
| `name` | 批次编号，例如 `batch-20261118-001`，和 `record.sessionName` 一样 |
| `label` | 小程序里显示的批次名，例如「第1批 11月18日」，和 `record.sessionLabel` 一样 |

### record：这一次扫码

`record` 里没有值的字段不推，这个键直接不出现。比如没写备注就没有 `remark`，没开「扫码位置」就没有 `location`，没有图片就没有 `images`。

| 字段 | 类型 | 说明 |
|------|------|------|
| `recordId` | 文字 | 记录 ID，每条记录唯一。同一条记录改了再推，ID 不变，可以用它判断是不是同一条 |
| `taskId` | 文字 | 台账 ID，同 `task.id` |
| `sessionId` | 文字 | 批次 ID，同 `session.id` |
| `recordUniqueNumber` | 文字 | 记录序号，例如 `R4`，在一个台账里不重复 |
| `scanResult` | 文字 | 扫到的内容（二维码或条码里的文字、链接） |
| `scanType` | 文字 | 扫码类型：`qrcode` 是二维码，`barcode` 是条码 |
| `scannedAt` | 文字 | 扫码时间，UTC 时间（ISO 8601 格式），加 8 小时是北京时间 |
| `createdAt` | 文字 | 记录传到服务器的时间。没网时录的记录，联网后才上传，这个时间会晚于 `scannedAt` |
| `location` | 文字 | 扫码位置。台账开了「扫码位置」才有。格式是「地名 纬度,经度（精度N米）」，地名还没解析出来时只有「纬度,经度（精度N米）」 |
| `locationAddress` | 文字 | 扫码位置的地名，例如「浙江省杭州市西湖区文三路90号」，是草料按坐标查出来的附近地址。查不到时没有这个键 |
| `images` | 链接数组 | 这条记录的图片：台账开了「解码图片」时存下的识别画面，以及备注里添加的图片 |
| `remark` | 文字 | 备注的文字 |
| `submitter` | 文字 | 录入这条记录的人在小程序里的名字 |
| `sessionName` | 文字 | 批次编号，例如 `batch-20261118-001`，固定不变，适合用来分组。从草料扫码器转过来的台账，这里就是批次名 |
| `sessionLabel` | 文字 | 小程序里显示的批次名，例如「第1批 11月18日」，给人看用 |

为了兼容已经接好的系统，`record` 里还会按字段的 key 带上部分记录内容（比如示例里的 `category`，以及 `cf_` 开头的自定义字段）。这部分的格式和 `fields` 不一样，新接入请读 `fields`。

### fields：记录内容

`fields` 是一个数组，台账「记录内容」里每个字段一项。备注（`key` 为 `noteText`）一定在第一项；台账没加别的字段时，`fields` 里只有备注。这一项以前叫「快速备注」，2026 年 11 月起 `name` 改为「备注」，`key` 不变，请用 `key` 对齐。

| 键 | 说明 |
|------|------|
| `key` | 字段标识，字段改名也不变，用它对应你系统里的列 |
| `name` | 字段现在的名字 |
| `type` | 字段类型，见下表 |
| `value` | 字段的值，格式按类型不同；没填也会推，每条记录的 `fields` 结构都一样 |

| type | 对应的字段 | value | 没填时 |
|------|------|------|------|
| `text` | 文字、备注 | 文字 | `null` |
| `number` | 数字 | 数字 | `null` |
| `date` | 日期 | `"2026-11-20"` | `null` |
| `time` | 时间 | `"09:30"` | `null` |
| `datetime` | 日期和时间 | `"2026-11-20 09:30"` | `null` |
| `select` | 选择（单选） | 对象，含 `key`、`label`，选项设了颜色时还有 `color` | `null` |
| `multiSelect` | 选择（多选） | 上面这种对象的数组 | `[]` |
| `image` | 图片 | 图片链接数组 | `[]` |

日期、时间字段推的是录入时手机上填的本地时间，不用换算时区。

## 常见问题

### 添加 Webhook 之前录的记录能推吗？

不能。Webhook 只推添加之后录的记录，关掉期间录的也不推，以后都不补推。要之前的记录，可以在台账里导出。

### 推送失败会重试吗？

不会自动重试。地址打不开、30 秒内没有回应、返回的状态码不是 2xx，这条记录这一次就推送失败了；之后有人改了这条记录，会带着改后的内容再推一次。

建议接收方收到后先把内容存下来、马上返回 200，再慢慢处理，避免处理太久超过 30 秒。

### 同一条记录为什么收到了好几次？

推出去之后又改了这条记录，每改一次推一次。用 `recordId` 判断是同一条记录，以后收到的为准。

### 收到的内容里为什么没有 version 和 fields？

这是在草料扫码器里早先建好的 Webhook。为了不影响已经接好的系统，它照原来的格式推送。想改用上面说的新格式，删掉这个 Webhook 后重新添加，接收方也要按新格式改。

### fields 里为什么只有备注？

台账「记录内容」里只有备注时，`fields` 就只有这一项。在「流程设计」的「记录内容」里加字段后，之后推送的记录会带上新字段。

### 图片链接能打开多久？

图片链接长期有效，拿到链接的人不用登录就能打开，可以直接保存到你的系统里。链接里的 `auth_key` 不要删，删了会打不开。

## 相关文档

- 不想自己写接收程序，只想把扫码记录汇总成表格：[把连续扫码器的扫码记录同步到腾讯文档](/help/integration-and-connection/continuous-scanner/tencent-docs-sync)
- 想把推送转发到企业微信群、飞书等应用：[用腾讯轻联，打通草料与其它应用的连接](/help/integration-and-connection/third-party-integration/tencent-hiflow/connection)
