业务回调

场景：服务商通过此接口配置回调参数，当数字农人产生交易的时候，将通过回调地址回推给到服务商。

通用回调协议

适用于所有回调类型的统一接口规范。

请求方式：POST
Content-Type：application/json
请求超时：30 秒
请求头：serviceid — 服务商 ID，用于身份识别

请求结构体

所有回调请求都采用统一的包装格式。请求体已进行 SM2 加密处理，接收方需要先解密后再进行业务处理。同时请求包含 SM2 签名，需要进行验签以确保数据完整性。

json

{
  "timestamp": 1704067200000,
  "callbackType": "ORDER_STATUS_CHANGE",
  "appId": "12345",
  "callbackId": "cb_20240101120000_abc123",
  "data": "{具体业务数据的JSON字符串}",
  "requestId": "req_20240101120000_xyz789",
  "taskCreateTimestamp": 1704067000000
}

通用字段说明

字段	类型	必填	说明
timestamp	String	是	回调时间戳（毫秒）
callbackType	String	是	回调类型标识，详见业务回调规范
appId	String	是	应用 ID
callbackId	String	是	回调唯一标识，用于幂等判断
data	String	是	业务数据 JSON 字符串，具体结构见各业务回调规范
requestId	String	是	请求追踪 ID
taskCreateTimestamp	String	是	回调任务创建时间戳（毫秒），此时间在任务创建时确定，重试过程中不会变化

通用响应协议

返回以下格式的响应：

json

{
  "code": 0,
  "message": "处理成功",
  "data": null,
  "logId": "log_20240101120000_001"
}

字段	类型	必填	说明
code	Integer	是	响应码，0 表示成功，非 0 表示失败
message	String	是	响应消息
data	Object	是	响应数据，可为 null
logId	String	是	日志 ID，用于问题排查

成功判定条件

HTTP 状态码为 2xx
响应体中 code 字段值为 0

重试机制

项目	说明
重试触发	当回调失败时（HTTP 非 2xx 状态码或响应 code 非 0）自动触发重试
重试次数	最大重试 13 次
重试策略	采用指数退避策略，跨越 7 天周期
重试间隔	1, 2, 4, 8, 16, 32, 60, 120, 240, 480, 1440, 2880, 4320 分钟
重试停止	达到最大重试次数后停止重试

业务回调规范

企业注册审核结果回调

触发场景：当企业入驻申请审核完成后（无论审核通过还是失败），系统将通过回调通知服务商审核结果。

callbackType：CUSTOMER_APPLY_AUDIT

data 字段业务数据结构

字段	类型	必填	说明
name	String	是	企业名称
creditCode	String	是	社会信用代码
status	String	是	审核状态，详见审核状态枚举
failReason	String	否	审核失败原因，仅当 status 为 FAIL 时有值

审核状态枚举

值	说明
SUCCESS	审核通过
FAIL	审核失败

回调示例

json

{
  "timestamp": 1704067200000,
  "callbackType": "CUSTOMER_APPLY_AUDIT",
  "appId": "12345",
  "callbackId": "cb_20240101120000_audit001",
  "data": "{\"name\":\"XX科技有限公司\",\"creditCode\":\"91110000000000000X\",\"status\":\"SUCCESS\",\"failReason\":null}",
  "requestId": "req_20240101120000_audit001",
  "taskCreateTimestamp": 1704067000000
}

成功响应示例

json

{
  "code": 0,
  "message": "审核结果处理成功",
  "data": null,
  "logId": "log_20240101120000_001"
}

失败响应示例

json

{
  "code": 1001,
  "message": "企业信息不存在",
  "data": null,
  "logId": "log_20240101120000_002"
}

订单状态变更回调

触发场景：当订单的支付状态或发票状态发生变化时触发此回调。

callbackType：ORDER_STATUS_CHANGE

data 字段业务数据结构

字段	类型	必填	说明
orderNo	String	是	内部订单编号
externalOrderNo	String	是	外部订单编号（服务商侧订单号）
payStatus	Long	是	订单支付状态，详见支付状态枚举
payMessage	String	否	支付错误信息，成功时为 null
invoiceStatus	Long	是	开票状态，详见发票状态枚举
invoiceMessage	String	否	开票错误信息，成功时为 null
canceled	Boolean	是	订单是否取消，true 表示已取消，false 表示未取消

支付状态枚举

状态码	状态名称	说明
0	待支付	订单创建，等待支付
1	已支付	支付成功
3	支付失败	支付失败
4	支付中	正在支付处理中
5	待收款方确认	等待收款方确认支付

发票状态枚举

状态码	状态名称	说明
0	待开票	等待开具发票
1	开票中	正在开具发票
2	已开票	发票开具成功
3	开票失败	发票开具失败
4	红冲中	正在进行红冲处理
5	已红冲	红冲处理完成
6	红冲失败	红冲处理失败

回调示例

json

{
  "timestamp": 1704067200000,
  "callbackType": "ORDER_STATUS_CHANGE",
  "appId": "12345",
  "callbackId": "cb_20240101120000_abc123",
  "data": "{\"orderNo\":\"PO2024010112345\",\"externalOrderNo\":\"EXT20240101001\",\"payStatus\":1,\"payMessage\":null,\"invoiceStatus\":2,\"invoiceMessage\":null,\"canceled\":false}",
  "requestId": "req_20240101120000_xyz789"
}

成功响应示例

json

{
  "code": 0,
  "message": "订单状态更新成功",
  "data": null,
  "logId": "log_20240101120000_001"
}

失败响应示例

json

{
  "code": 1001,
  "message": "订单不存在",
  "data": null,
  "logId": "log_20240101120000_002"
}

事中风控事件回调

触发场景：当服务商绑定的企业触发事中风控策略命中时，推送事中风控事件信息给服务商。仅向已绑定该企业的服务商推送。

callbackType：CURRENT_EVENT_RISK

data 字段业务数据结构

字段	类型	必填	说明
riskEventNo	String	是	风控事件编号
customerName	String	否	采购商名称
customerCreditCode	String	否	社会统一信用代码（税号）
supplierName	String	否	农户姓名
supplierPhone	String	否	手机号
transactionProductName	String	否	交易商品名称
transactionAmount	Number	否	交易金额
decisionType	Enum	是	处理方式，详见处理方式枚举
strategyName	String	否	触发风险（风险指标名称）
occurrenceTime	String	否	风控时间

处理方式枚举

值	说明
REMIND	提醒
WARN	预警
BLOCK	阻断

回调示例

json

{
  "timestamp": 1709618400000,
  "callbackType": "CURRENT_EVENT_RISK",
  "appId": "12345",
  "callbackId": "cb_20260305143025_abc123",
  "data": "{\"riskEventNo\":\"R20260305143025123456789\",\"customerName\":\"XX农业公司\",\"customerCreditCode\":\"91110000XXXXXXXXXX\",\"supplierName\":\"张三\",\"supplierPhone\":\"13800138000\",\"transactionProductName\":\"玉米\",\"transactionAmount\":5000.00,\"decisionType\":\"WARN\",\"strategyName\":\"单笔交易金额异常\",\"occurrenceTime\":\"2026-03-05 14:30:25\"}",
  "requestId": "req_20260305143025_xyz789"
}

成功响应示例

json

{
  "code": 0,
  "message": "风控事件处理成功",
  "data": null,
  "logId": "log_20260305143025_001"
}

失败响应示例

json

{
  "code": 1001,
  "message": "风控事件处理失败",
  "data": null,
  "logId": "log_20260305143025_002"
}

事后风控事件回调

触发场景：当服务商绑定的企业触发事后风控策略命中时，推送事后风控事件信息给服务商。仅向已绑定该企业的服务商推送。

callbackType：AFTER_EVENT_RISK

data 字段业务数据结构

字段	类型	必填	说明
riskEventNo	String	是	风控事件编号
purchaseOrderNo	String	否	采购订单号（异常采购商没有则为空）
customerName	String	否	采购商名称
customerCreditCode	String	否	社会统一信用代码（税号）
orderAmount	Number	否	订单金额（异常采购商没有则为空）
riskLevel	Enum	是	风险等级，详见风险等级枚举
processStatus	Enum	否	处理状态（工单状态），详见处理状态枚举
strategyName	String	否	触发风险（风险指标名称）
riskTime	String	否	风控时间

风险等级枚举

值	说明
HIGH	高风险
MIDDLE	中风险
LOW	低风险

处理状态枚举

值	说明
TO_DO	待处理
DOING	处理中
DONE	已完成

回调示例

json

{
  "timestamp": 1709618400000,
  "callbackType": "AFTER_EVENT_RISK",
  "appId": "12345",
  "callbackId": "cb_20260305150000_def456",
  "data": "{\"riskEventNo\":\"123456789\",\"purchaseOrderNo\":\"PO2026030500001\",\"customerName\":\"XX农业公司\",\"customerCreditCode\":\"91110000XXXXXXXXXX\",\"orderAmount\":5000.00,\"riskLevel\":\"HIGH\",\"processStatus\":\"TO_DO\",\"strategyName\":\"采购金额异常\",\"riskTime\":\"2026-03-05 15:00:00\"}",
  "requestId": "req_20260305150000_abc789"
}

成功响应示例

json

{
  "code": 0,
  "message": "风控事件处理成功",
  "data": null,
  "logId": "log_20260305150000_001"
}

失败响应示例

json

{
  "code": 1001,
  "message": "风控事件处理失败",
  "data": null,
  "logId": "log_20260305150000_002"
}

业务回调 ​

通用回调协议 ​

请求结构体 ​

通用字段说明 ​

通用响应协议 ​

成功判定条件 ​

重试机制 ​

业务回调规范 ​

企业注册审核结果回调 ​

data 字段业务数据结构 ​

审核状态枚举 ​

回调示例 ​

成功响应示例 ​

失败响应示例 ​

订单状态变更回调 ​

data 字段业务数据结构 ​

支付状态枚举 ​

发票状态枚举 ​

回调示例 ​

成功响应示例 ​

失败响应示例 ​

事中风控事件回调 ​

data 字段业务数据结构 ​

处理方式枚举 ​

回调示例 ​

成功响应示例 ​

失败响应示例 ​

事后风控事件回调 ​

data 字段业务数据结构 ​

风险等级枚举 ​

处理状态枚举 ​

回调示例 ​

成功响应示例 ​

失败响应示例 ​

业务回调

通用回调协议

请求结构体

通用字段说明

通用响应协议

成功判定条件

重试机制

业务回调规范

企业注册审核结果回调

data 字段业务数据结构

审核状态枚举

回调示例

成功响应示例

失败响应示例

订单状态变更回调

data 字段业务数据结构

支付状态枚举

发票状态枚举

回调示例

成功响应示例

失败响应示例

事中风控事件回调

data 字段业务数据结构

处理方式枚举

回调示例

成功响应示例

失败响应示例

事后风控事件回调

data 字段业务数据结构

风险等级枚举

处理状态枚举

回调示例

成功响应示例

失败响应示例