跳转至

发送传真接口

概述

通过本接口创建传真发送任务，支持多文件、多收件人批量发送，并可指定预约发送时间。上传文件后获得 file_ref，使用该标识符创建传真任务。

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

接口详情

项目 说明
方法 POST
路径 /api/v2/faxes
认证 需要在请求头中添加 X-API-Key 和 X-API-Secret，详见 认证指南。
请求头 Content-Type: application/json

请求参数

参数名 类型 必填 验证规则 说明 示例值
name string 是 1. 非空字符串
2. 最大长度 255 字符		 传真任务名称，用于业务标识 "2025年2月客户账单"
file_refs array[string] 是 1. 数组长度 1‑3
2. 每个元素最大 64 字符
3. 元素不能为空		 文件唯一标识符，需通过 文件上传接口 预先获取 ["file_abc123", "file_def456"]
phone_numbers array[string] 是 1. 数组长度 1‑100
2. 格式：以 1‑9 开头，7‑15 位数字
3. 支持国际号码格式		 收件人传真号码列表 ["8613812345678", "8613912345678"]
scheduled_at string 否 合法的日期时间格式（Y‑m‑d H:i:s） 预约发送时间，未指定则立即发送 "2025-02-22 14:30:00"

号码格式说明

  • 号码必须以 1‑9 开头，长度为 7‑15 位数字。
  • 支持国际区号（如 86 表示中国），不含 + 号或空格。
  • 示例：8613812345678（中国号码）。

请求示例

cURL

curl -X POST "http://api.globfax.com/api/v2/faxes" \
  -H "X-API-Key: your_api_key_here" \
  -H "X-API-Secret: your_api_secret_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "2025年2月客户账单",
    "file_refs": ["file_abc123", "file_def456"],
    "phone_numbers": ["8613812345678", "8613912345678"],
    "scheduled_at": "2025-02-22 14:30:00"
  }'

原始 HTTP 请求

POST /api/v2/faxes HTTP/1.1
Host: api.globfax.com
X-API-Key: your_api_key_here
X-API-Secret: your_api_secret_here
Content-Type: application/json
Content-Length: 187

{
  "name": "2025年2月客户账单",
  "file_refs": ["file_abc123", "file_def456"],
  "phone_numbers": ["8613812345678", "8613912345678"],
  "scheduled_at": "2025-02-22 14:30:00"
}

响应格式

成功响应

{
  "success": true,
  "message": "Fax queued for sending",
  "data": {
    "task_ref": "fax_789xyz",
    "name": "2025年2月客户账单",
    "status": "pending",
    "scheduled_at": "2025-02-22 14:30:00",
    "created_at": "2025-02-22 10:00:00",
    "recipients": [
      {
        "rcpt_ref": "rcpt_111aaa",
        "phone_number": "8613812345678"
      },
      {
        "rcpt_ref": "rcpt_222bbb",
        "phone_number": "8613912345678"
      }
    ]
  }
}

参数验证失败响应

{
  "success": false,
  "message": "Invalid parameters",
  "errors": {
    "phone_numbers.0": [
      "Phone number must start with 1-9 and be 7-15 digits long."
    ],
    "file_refs": [
      "At least one file must be provided."
    ]
  }
}

业务处理失败响应

{
  "success": false,
  "message": "Failed to create fax job",
  "errors": "文件引用无效或已过期，请重新上传文件"
}

通用错误格式

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

字段说明

任务信息

字段名 类型 说明 示例值
task_ref string 传真任务唯一标识符，用于后续查询状态 "fax_789xyz"
name string 任务名称 "2025年2月客户账单"
status string 任务当前状态（pending‑待发送） "pending"
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] 收件人列表，每个收件人包含 rcpt_ref 和 phone_number 见下方

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

字段名 类型 说明 示例值
rcpt_ref string 收件人唯一标识符 "rcpt_111aaa"
phone_number string 收件人传真号码 "8613812345678"

状态说明

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

常见问题

1. 文件限制

  • 每个传真任务最多支持 3 个文件。
  • 建议提前将多个页面合并为单个 PDF 文件，以提升发送效率。

2. 收件人限制

  • 每个任务最多支持 100 个收件人。
  • 超过限制建议拆分为多个任务。

3. 预约发送时间

  • 格式：Y‑m‑d H:i:s（如 2025‑02‑22 14:30:00）。
  • 未指定则立即发送。
  • 预约时间必须晚于当前时间。

4. 任务状态说明

创建成功后，任务状态为 pending（待发送），后续状态变化可通过 查询任务状态接口 获取。

使用建议

完整工作流程

  1. 准备文件：通过 文件上传接口 上传文档，获取 file_ref。
  2. 创建任务：调用本接口，传入 file_refs 和收件人号码。
  3. 保存标识：务必保存返回的 task_ref，用于后续查询状态。
  4. 监控状态：通过 查询任务状态接口 了解发送进度。

最佳实践

  • 为任务设置有意义的名称，便于后续管理。
  • 对于重要传真，建议先测试再正式发送。
  • 记录 task_ref 和发送日志，便于问题排查。

错误处理

  • 检查认证信息是否正确。
  • 确认文件引用是否有效（通过上传接口获取）。
  • 验证收件人号码格式是否符合要求。
  • 如遇系统错误，建议稍后重试。

下一步

任务创建成功后，使用返回的 task_ref 查询发送状态：