API 参考

Webhook 通知

Webhook 为事件主动推送机制，当传真任务状态发生变更时，系统将以 HTTP POST 请求形式，向预设回调地址推送最新任务与收件人明细数据。采用该方式可规避接口轮询查询，高效实时监控投递状态，减少无效请求消耗。

快速配置流程

设置回调地址
登录管理后台，依次进入「开发者」→「API 设置」页面，填写合法公网回调网址，保存配置即可生效。
查看通知记录
登录管理后台，依次进入「开发者」→「回调通知」页面，可查阅全部历史推送记录、送达状态与响应详情。
回调地址约束
必须为公网可正常访问的 HTTP/HTTPS 链接。地址字符长度上限 255 位。服务端需在 30 秒内完成响应，超时判定推送失败并触发重试。

回调数据示例


{
  "task_ref": "fax_789xyz",
  "name": "2025年2月客户账单",
  "status": "completed",
  "scheduled_at": "2025-02-22 14:30:00",
  "created_at": "2025-02-22 10:00:00",
  "recipients": [
    {
      "rcpt_ref": "rcpt_111aaa",
      "phone_number": "8613812345678",
      "unit_price": 1.5,
      "page_count": 3,
      "charged_amount": 4.5,
      "status": "success",
      "failed_code": null,
      "failed_reason": null,
      "completed_at": "2025-02-22 14:31:20",
      "created_at": "2025-02-22 10:00:00"
    },
    {
      "rcpt_ref": "rcpt_222bbb",
      "phone_number": "8613912345699",
      "unit_price": 1.5,
      "page_count": 3,
      "charged_amount": null,
      "status": "failed",
      "failed_code": 2003,
      "failed_reason": "busy or unavailable",
      "completed_at": "2025-02-22 14:35:10",
      "created_at": "2025-02-22 10:00:00"
    }
  ]
}

数据字段说明

任务基础信息

字段名	数据类型	字段说明	示例值
task_ref	string	传真任务唯一标识	fax_789xyz
name	string	任务自定义名称	2025年2月客户账单
status	string	任务整体状态	completed
scheduled_at	string	预约发送时间，无预约则为空	2025-02-22 14:30:00
created_at	string	任务创建时间	2025-02-22 10:00:00
recipients	array[object]	收件人发送结果明细列表	-

收件人信息

字段名	数据类型	字段说明	示例值
rcpt_ref	string	单收件人唯一标识	rcpt_111aaa
phone_number	string	收件人传真号码	8613812345678
unit_price	float	单页传真单价（元/页）	1.5
page_count	int	传真文档页数	3
charged_amount	float	本条扣费总额，失败则为 null	4.5
status	string	单收件人发送状态	success
failed_code	string	失败错误码，成功则为 null
failed_reason	string	失败原因描述，成功则为 null
completed_at	string	发送完成时间，未完成则为 null	2025-02-22 14:31:20
created_at	string	收件人任务创建时间	2025-02-22 10:00:00

响应处理与重试

接收推送后，需及时返回对应状态码，系统依据响应结果判定送达状态。为保障推送可靠送达，平台内置指数退避重试策略。

200 OK：
判定处理成功，终止本次推送
4xx / 5xx：
判定处理异常，触发自动重试机制
失败重试：
最大重试次数：5 次
重试间隔梯度：1 分钟、2 分钟、3 分钟、4 分钟、5 分钟

最佳实践：核心回执逻辑精简处理，建议 3 秒内返回响应，规避超时。数据存储、统计通知等复杂逻辑延后异步执行。校验报文格式、字段完整性，异常数据丢弃处理。

常见问题

同一任务会多次推送通知吗？
单次状态变更仅推送一次，推送失败会按照规则重试；成功送达后不会重复推送相同状态事件。
如何修改生效回调地址？
在 API 设置页面直接更新网址并保存，系统自动验证新地址，旧地址即刻停止接收通知。
重试推送是否会干扰正常业务？
采用梯度间隔重试，不会集中请求施压；业务端做好幂等处理即可规避重复操作风险。