API 参考

传真任务查询

本接口用于查询传真任务整体进度与全量收件人明细结果，可获取任务状态、创建时间、预约时间、单收件人发送结果、计费信息、失败原因等完整数据。开发者需传入创建任务时返回的唯一任务标识 task_ref 发起查询。

接口基础信息

项目	说明
请求方法	`GET`
接口路径	`/api/v2/faxes/{task_ref}`
访问认证	请求头携带 `X-API-Key`、`X-API-Secret`，参考 [账户访问认证]
头部参数	`Content-Type: application/json`

请求参数

参数名	类型	必填	校验规则	说明
task_ref	string	是	最大255字符	传真任务唯一标识，由提交传真任务接口返回

请求示例

cURL 请求


curl -X GET "http://api.globfax.com/api/v2/faxes/fax_789xyz" \
  -H "X-API-Key: your_api_key_here" \
  -H "X-API-Secret: your_api_secret_here"

原生 HTTP 请求


GET /api/v2/faxes/fax_789xyz HTTP/1.1
Host: api.globfax.com
X-API-Key: your_api_key_here
X-API-Secret: your_api_secret_here

响应结果

成功响应

返回任务整体信息及全部收件人详细发送、计费、异常数据。


{
  "success": true,
  "message": "Task details retrieved",
  "data": {
    "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"
      }
    ]
  }
}

失败响应


{
  "success": false,
  "message": "错误描述",
  "errors": "详细错误信息"
}

返回字段说明

任务基础信息

字段名	数据类型	字段说明	示例值
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

规范与限制

查询频率限制：
常规查询间隔不少于 30 秒；发送中任务建议间隔 1 分钟，避免高频轮询。生产环境下使用 Webhook 方式获取结果，避免查询频率限制。
状态逻辑：
任务整体状态为 done 代表全部收件人处理完毕，允许部分成功、部分失败。

最佳实践

标准调用流程：
文件上传获取 file_ref → 调用本接口创建任务 → 持久保存 task_ref、rcpt_ref → 轮询/回调监控任务状态。
业务使用建议：
持久化存储任务与收件人明细数据，用于业务统计与对账。记录失败码与失败原因，迭代优化发送策略。精细化场景可使用 rcpt_ref 调用单收件人状态查询接口。
异常排查：
校验 task_ref 格式、长度是否符合规范。核对标识是否正确、任务是否过期删除、账户是否匹配。遇5xx临时异常，可加入指数退避重试机制。

常见问题

task_ref 丢失如何处理？
task_ref 仅在创建任务时返回，建议业务落地时持久存储；若丢失，可登录管理后台通过任务列表检索对应任务信息。
任务 done 状态是否代表全部发送成功？
不代表。done 仅代表所有收件人处理完成，需遍历收件人列表 status 字段判断单条成功/失败状态。
如何实现实时传真状态监控？
高频轮询易触发频率限制，生产环境优先配置 Webhook 回调，系统自动推送状态变更，高效稳定。

下一步操作

配置Webhook回调通知，替代主动轮询，接收状态自动推送。