跳转至

查询收件人状态接口

概述

通过本接口查询指定收件人的详细发送状态及计费信息，包括发送结果、失败原因和费用明细。使用创建传真任务时返回的收件人标识符（rcpt_ref）进行查询。

完整路径： http://api.globfax.com/api/v2/fax/recipients/{rcpt_ref}

接口详情

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

请求参数

路径参数

参数名 类型 必填 验证规则 说明 示例值
rcpt_ref string 是 1. 非空字符串
2. 仅包含字母、数字、下划线（_）、短横线（-）
3. 最大长度 255 字符		 收件人唯一标识符，从 发送传真接口 返回的 recipients 列表中获取 rcpt_111aaa

标识符格式

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

请求示例

cURL

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

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

响应格式

成功响应（发送成功）

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

成功响应（发送失败）

{
  "success": true,
  "message": "Recipient details retrieved",
  "data": {
    "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 rcpt_ref format",
  "errors": {
    "uid": [
      "The uid format is invalid."
    ]
  }
}

收件人不存在响应

{
  "success": false,
  "message": "Recipient not found",
  "errors": ""
}

服务器异常响应

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

通用错误格式

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

字段说明

字段名 类型 说明 示例值
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. 如何获取 rcpt_ref？

  • rcpt_ref 在创建传真任务时返回的 recipients 列表中。
  • 每个收件人都有一个独立的 rcpt_ref。
  • 如果丢失，可以通过 查询任务状态接口 获取。

2. 查询频率限制

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

3. 与任务状态查询的区别

  • 本接口查询单个收件人的详细信息。
  • 任务状态查询返回整个任务的所有收件人状态。
  • 根据需求选择合适的查询方式。

API 调用频率

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

使用建议

完整工作流程

  1. 创建任务：调用 发送传真接口，保存返回的 recipients 列表。
  2. 获取标识：从 recipients 列表中提取需要的 rcpt_ref。
  3. 查询状态：使用 rcpt_ref 调用本接口查询单个收件人状态。
  4. 处理结果：根据状态进行后续处理（如通知用户、重试失败收件人等）。

错误处理建议

  • 对于参数格式错误，检查 rcpt_ref 是否符合要求（字母、数字、下划线、短横线）。
  • 对于收件人不存在错误，确认 rcpt_ref 是否正确或记录是否已被删除。
  • 对于服务器异常，建议稍后重试，如持续失败请联系技术支持。

数据使用建议

  • 保存收件人详情用于业务对账和统计分析。
  • 记录失败原因用于优化发送策略（如避开繁忙时段）。

下一步