跳到主要内容

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

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

开始前请确认:

  1. 接收地址:一个以 http:// 或 https:// 开头、能从公网访问的地址,用来接收推送。公司内网地址收不到。
  2. 台账创建者:只有台账的创建者能添加和修改 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)就算推送成功,返回的内容不看。

没收到时,依次检查:

  1. 自动化设置里这个 Webhook 的开关是否打开;
  2. URL 是否填对,能否从公网访问;
  3. 接收方是否在 30 秒内返回了 2xx;
  4. 接收方需要鉴权时,Headers 是否填对;
  5. 这条记录是不是在添加 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,选项设了颜色时还有 colornull
multiSelect选择(多选)上面这种对象的数组[]
image图片图片链接数组[]

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

常见问题​

添加 Webhook 之前录的记录能推吗?​

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

推送失败会重试吗?​

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

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

同一条记录为什么收到了好几次?​

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

收到的内容里为什么没有 version 和 fields?​

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

fields 里为什么只有备注?​

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

图片链接能打开多久?​

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

相关文档​