Skip to main content
Home
  • API 参考
  • 收件人状态查询

收件人状态查询

本接口用于查询单个收件人的发送详情，包括发送状态、计费信息、失败原因、完成时间等。传入收件人唯一标识 rcpt_ref 即可获取该收件人的实时状态数据。

#接口基础信息

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

#请求参数

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

#请求示例

#cURL 请求

shell 
curl -X GET "http://api.globfax.com/api/v2/fax/recipients/rcpt_111aaa" \
  -H "X-API-Key: your_api_key_here" \
  -H "X-API-Secret: your_api_secret_here"

#原生 HTTP 请求

code 
GET /api/v2/fax/recipients/rcpt_111aaa 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": "Recipient details retrieved",
  "data": {
    "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"
  }
}

#失败响应

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

#返回字段说明

字段名 数据类型 字段说明 示例值
rcpt_ref string 收件人唯一标识 rcpt_111aaa
phone_number string 收件人传真号码 8613812345678
unit_price float 每页单价，单位：元 1.5
page_count int 成功发送页数 3
charged_amount float 实际计费金额，页数 × 单价 4.5
status string 发送状态：pending等待、sending发送中、success成功、failed失败、canceled已取消 success
failed_code int or null 失败错误码，成功时为空 null
failed_reason string or null 失败原因描述，成功时为空 null
completed_at string or null 发送完成时间 2025-02-22 14:31:20
created_at string 收件人记录创建时间 2025-02-22 10:00:00

#规范与限制

  1. 查询频率限制：
    常规查询间隔不少于 30 秒；发送中任务建议间隔 1 分钟，避免高频轮询。生产环境下使用 Webhook 方式获取结果，避免查询频率限制。

  2. 业务逻辑：
    本接口仅查询单个收件人数据；如需批量查看同任务所有人员结果，使用任务状态查询接口。

#最佳实践

  1. 标准调用流程：
    文件上传获取 file_ref → 调用本接口创建任务 → 持久保存 task_ref、rcpt_ref → 轮询/回调监控任务状态。

  2. 业务使用建议：
    持久化存储任务与收件人明细数据，用于业务统计与对账。
    汇总失败类型与原因，优化号码筛选、发送时段等投递策略。

  3. 异常排查：
    校验 rcpt_ref 格式、长度是否符合规范。
    核对标识是否正确、任务是否过期删除、账户是否匹配。若遇服务响应临时异常时，采用退避策略重试。

#常见问题

  1. 如何获取 rcpt_ref 标识？
    创建传真任务后会在返回的收件人列表中获取，标识丢失也可通过任务状态查询接口重新调取。每个收件人拥有独立唯一标识。

  2. 单收件人查询和整任务查询如何选择？
    仅关注单个号码投递结果时使用本接口；需要一次性查看全部收件人数据，调用传真任务查询接口即可。

  3. 如何实现实时传真状态监控？
    高频轮询易触发频率限制，生产环境优先配置 Webhook 回调，系统自动推送状态变更，高效稳定。

#下一步操作

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