用 Webhook 把连续扫码器的扫码记录推送到自己的系统
在台账上添加 Webhook 后,草料连续扫码器会把这个台账新录的每一条扫码记录,以 JSON 格式自动推送到你填的地址(URL)。你的系统收到后可以存进自己的数据库、发群消息、对接仓库或 ERP 系统,不用再到小程序里导出。
开始前请确认:
- 接收地址:一个以
http://或https://开头、能从公网访问的地址,用来接收推送。公司内网地址收不到。 - 台账创建者:只有台账的创建者能添加和修改 Webhook,其他成员只能查看。
注:草料二维码表单的 Webhook 是另一套功能,推送内容不同,见 Webhook 说明文档。
什么时候推送
每录一条扫码记录推送一次,推送时机如下:
| 情况 | 推不推 |
|---|---|
| 录了一条新记录 | 推。连续扫码时,扫下一条时推出上一条;不再扫的话,大约 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)就算推送成功,返回的内容不看。
没收到时,依次检查:
- 自动化设置里这个 Webhook 的开关是否打开;
- URL 是否填对,能否从公网访问;
- 接收方是否在 30 秒内返回了 2xx;
- 接收方需要鉴权时,Headers 是否填对;
- 这条记录是不是在添加 Webhook 之前录的。
推送的请求和请求体示例
每推一条记录,就向你的 URL 发一次 HTTP 请求:请求方法是配置里选的 POST 或 GET,请求头带 Content-Type: application/json 和你填的 Headers,请求体是下面这样的 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 不要删,删了会打不开。
相关文档
- 不想自己写接收程序,只想把扫码记录汇总成表格:把连续扫码器的扫码记录同步到腾讯文档
- 想把推送转发到企业微信群、飞书等应用:用腾讯轻联,打通草料与其它应用的连接