Skip to main content
Home
  • API 参考
  • 任务状态查询

任务状态查询

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

#接口基础信息

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

#请求参数

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

#请求示例

#cURL 请求

shell 
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 请求

code 
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

#响应结果

#成功响应

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

json 
{
  "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"
      }
    ]
  }
}

#失败响应

json 
{
  "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