特性 | 事件订阅 (Webhook) | API 调用 |
|---|---|---|
| 通信模式 | 被动接收 (由新核云主动推送) | 主动获取 (由你的应用主动发起请求) |
| 数据流向 | 新核云 → 你的服务器 | 你的服务器 → 新核云 |
| 最佳场景 | 实时通知、状态同步(当某事发生时) | 按需查询、主动操作 (当你需要时) |
| 时效性 | 高 (近实时,事件触发即推送) | 依赖你的调用频率 (可能有过期数据) |
| 数据关系 | 获取事件消息 (发生了什么,通常为变更数据) | 获取资源状态 (是什么,通常为完整数据) |
| 核心概念 | 订阅 (Subscribe) 一个事件 | 调用(Call) 一个接口 |
{
"headers":{
// 租户ID
"TENANT_ID":[
]
// 人员ID
"STAFF_ID":[
]
// 时间戳
"x-nct-time":[
]
// 业务类型代码
"business-type":[
]
}{
"headers":{
// 租户ID
"TENANT_ID":[
"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
]
"STAFF_ID":[
"123123"
]
// 时间戳
"x-nct-time":[
"1750351569887"
]
// 业务类型代码
"business-type":[
"9120"
]
}{
"requestId": "", // 请求唯一标识
"businessType": , // 业务类型
"data": { //事件特定数据
}
}{
"requestId": "3a528d8b-8a9f-41ac-9306-3ca84fcc2985", // 创建请求唯一标识
"businessType": 2010, // 业务类型:采购申请单创建
"data": {
"id": 10558833, // 申请单唯一ID
"code": "PR-250620-007", // 采购申请单编号(PR-年月日-流水号)
"type": 2, // 申请单类型(整数型标识)
"status": 0, // 申请单状态(0通常表示草稿)
"staffCode": "EM001", // 申请人员工工号
"createTime": 1750391230000, // 创建时间戳(毫秒)
"comments": null, // 申请单备注说明(空值)
"extendedFields": [], // 扩展字段列表(空数组)
"records": [ // 申请物料明细
{
"id": 13178611, // 明细项ID
"itemId": "7308337992085815296", // 物料唯一ID(长整型)
"itemCode": "复现mrp", // 物料编码
"itemUnit": "瓶", // 物料计量单位
"supplierCode": "", // 建议供应商编码(空值)
"quantity": 1, // 申请采购数量
"confirmQuantity": 0, // 采购确认数量(初始0)
"deadline": 1750348800000, // 物料需求截止时间
"latestCreateOrderDate": 1750262400000, // 最晚创建采购订单时间
"sourceOrderNumber": null, // 来源订单号(空值)
"procedureName": null, // 相关工序名称(空值)
"procedureCode": null, // 相关工序编码(空值)
"extendedFields": [] // 明细扩展字段(空数组)
}
]
}
}Content-Type: 标识请求体的媒体类型。固定为 application/json,表明请求体为JSON格式的字符串。Authorization(部分含有):包含Bearer Token,用于接收方验证请求的合法性。其格式为:Bearer 您的应用Secret。请注意: 此Token由系统自动生成并添加,您无需也不能在自定义头中重复配置Authorization。TENANT_ID: 用于标识租户。STAFF_ID: 用于标识触发事件的用户。x-nct-time: 请求发出时的UTC时间戳(Unix Timestamp,单位为秒),用于与x-nct-sig配合进行签名验证,防止重放攻击。x-nct-sig: 基于请求体、时间戳和您的应用Secret计算的数字签名。接收方应使用相同算法验证此签名,以确保消息未被篡改且来源可信。business-type: 用于标识业务线。X-API-Version: v2.1X-Channel: production (或 canary, staging)| 自定义请求头 | 主要用途 | 示例值 |
|---|---|---|
X-API-Version | 版本控制、路由 | v2.1, v3 |
Idempotency-Key | 幂等性控制,防重复 | webhook_evt_9876543210 |
X-Trace-ID | 分布式系统链路追踪 | 00-<trace_id>-<span_id>-01 |
X-Event-ID | 事件唯一标识,用于查询 | event_abcd1234 |
X-Environment | 标识来源环境 | PROD, UAT, DEV |
X-Trigger-Module | 标识触发业务模块 | MES_Work_Order, WMS_Inventory |
其他任何您业务系统需要的固定标识符或令牌 |
Content-Type, Authorization, x-nct-time, x-nct-sig 等系统保留字段作为您的自定义头名称,以免发生冲突。系统生成的头将覆盖您自定义的同名头。HTTP 200 响应,系统会自动触发重试,达到最大重试次数(3次)后新增一条失败日志记录。HTTP 200 状态码,然后将耗时的事务处理(如写入数据库、调用其他API)放入后台队列异步执行。