查询传真状态接口¶

概述¶

通过本接口查询传真任务的详细信息，包括任务状态、发送进度和所有收件人的详细发送结果。使用创建传真任务时返回的 task_ref 进行查询。

完整路径： http://api.globfax.com/api/v2/faxes/{task_ref}

接口详情¶

项目	说明
方法	GET
路径	`/api/v2/faxes/{task_ref}`
认证	需要在请求头中添加 `X-API-Key` 和 `X-API-Secret`，详见认证指南。
请求头	无特殊要求，只需认证头即可。

请求参数¶

路径参数¶

参数名	类型	必填	验证规则	说明	示例值
`task_ref`	string	是	1. 非空字符串 2. 仅包含字母、数字、下划线（`_`）、短横线（`-`） 3. 最大长度 255 字符	传真任务唯一标识符，从发送传真接口返回	`fax_789xyz`

标识符格式

关于 task_ref 等标识符的通用格式说明，请参考 API 概述中的「标识符格式」章节。

请求示例¶

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": 0.5,
        "page_count": 3,
        "charged_amount": 1.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": "8613912345678",
        "unit_price": 0.5,
        "page_count": 3,
        "charged_amount": 1.5,
        "status": "failed",
        "failed_code": "BUSY",
        "failed_reason": "Recipient line is busy",
        "completed_at": "2025-02-22 14:35:10",
        "created_at": "2025-02-22 10:00:00"
      }
    ]
  }
}

参数验证失败响应¶

{
  "success": false,
  "message": "Invalid task_ref format",
  "errors": {
    "uid": [
      "The uid format is invalid."
    ]
  }
}

任务不存在响应¶

{
  "success": false,
  "message": "Fax job not found",
  "errors": ""
}

服务器异常响应¶

{
  "success": false,
  "message": "Failed to fetch task",
  "errors": "具体异常信息"
}

通用错误格式

关于错误响应的通用格式及常见 HTTP 状态码，请参考 API 概述中的「错误处理」章节。

字段说明¶

任务信息¶

字段名	类型	说明	示例值
`task_ref`	string	传真任务唯一标识符	`"fax_789xyz"`
`name`	string	任务名称	`"2025年2月客户账单"`
`status`	string	任务整体状态（见下方状态说明）	`"completed"`
`scheduled_at`	string	预约发送时间（Y‑m‑d H:i:s 格式）	`"2025-02-22 14:30:00"`
`created_at`	string	任务创建时间（Y‑m‑d H:i:s 格式）	`"2025-02-22 10:00:00"`
`recipients`	array[object]	收件人列表，每个收件人包含详细信息	见下方

收件人信息（`recipients` 数组中的对象）¶

字段名	类型	说明	示例值
`rcpt_ref`	string	收件人唯一标识符	`"rcpt_111aaa"`
`phone_number`	string	收件人传真号码	`"8613812345678"`
`unit_price`	float	单页发送费用（元/页）	`0.5`
`page_count`	int	实际发送页数	`3`
`charged_amount`	float	总费用（unit_price × page_count）	`1.5`
`status`	string	收件人发送状态（见下方状态说明）	`"success"`
`failed_code`	string	失败代码（仅失败状态有效）	`"BUSY"`
`failed_reason`	string	失败原因描述（仅失败状态有效）	`"Recipient line is busy"`
`completed_at`	string	发送完成时间（Y‑m‑d H:i:s 格式，未完成则为 `null`）	`"2025-02-22 14:31:20"`
`created_at`	string	收件人记录创建时间（Y‑m‑d H:i:s 格式）	`"2025-02-22 10:00:00"`

状态说明

任务整体状态及收件人发送状态的详细定义，请参考 API 概述中的「状态说明」章节。

常见问题¶

1. 如何获取 `task_ref`？¶

task_ref 在创建传真任务时返回，请务必保存该标识符。
如果丢失，需要通过其他方式（如管理后台）查找任务。

2. 查询频率限制¶

建议查询间隔不少于 30 秒，避免频繁查询。
对于发送中的任务，适当增加查询间隔（如 1 分钟）。

3. 任务状态与收件人状态的关系¶

任务整体状态反映任务的整体进度。
收件人状态显示每个收件人的具体发送结果。
任务状态为 done 时，所有收件人处理完成（可能有成功有失败）。

API 调用频率

关于接口调用频率限制等通用约定，请参考 API 概述中的「频率限制与重试」章节。

使用建议¶

完整工作流程¶

创建任务：调用发送传真接口，保存返回的 task_ref。
查询状态：使用 task_ref 调用本接口查询发送进度。
处理结果：根据收件人状态进行后续处理（如通知用户、重试等）。

错误处理建议¶

对于参数格式错误，检查 task_ref 是否符合要求。
对于任务不存在错误，确认 task_ref 是否正确或任务是否已被删除。
对于服务器异常，建议稍后重试，如持续失败请联系技术支持。

数据使用建议¶

保存任务详情用于业务对账和统计分析。
记录失败原因用于优化发送策略。
使用 rcpt_ref 可单独查询收件人详情（如需）。

下一步¶

需要单独查询某个收件人状态？参考收件人状态查询接口。
需要实时接收发送结果？设置回调通知接口。
遇到问题？查看常见问题或联系技术支持。