Skip to main content
Home
  • API 参考
  • 提交传真任务

提交传真任务

本接口用于创建并提交传真发送任务，支持多文件组合、批量收件人投递、预约定时发送。开发者需先通过上传传真文件接口获取文件标识 file_ref，再调用本接口完成任务创建。

#接口基础信息

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

#请求参数

参数名 类型 必填 校验规则 说明
name string 是 最大255字符 自定义传真任务名称，用于后台识别与管理
file_refs array[string] 是 数组元素1-3个 已上传文件唯一标识，通过文件上传接口获取
phone_numbers array[string] 是 数组元素1-100个 收件人传真号码列表，支持国际格式
scheduled_at string 否 合法时间格式 Y-m-d H:i:s，需晚于当前时间 预约发送时间，不传则立即发送

#请求示例

#cURL 请求

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

code 
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"
}

#响应结果

#成功响应

任务创建成功，返回任务唯一标识及收件人标识，用于后续状态查询。

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

#失败响应

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

#规范与限制

严格遵循文件上传格式、大小、命名、场景适配及异常处理要求，以避免上传失败。

  1. 收件人限制：
    单任务最多 100 个收件人，超出数量需拆分多任务提交。

  2. 文件限制：
    单任务最多绑定 3 个文件，建议多页面文档合并为 PDF，提升发送效率。

  3. 预约时间限制：
    预约时间必须晚于当前系统时间，格式严格遵循 Y-m-d H:i:s，不传则立即发送。

#最佳实践

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

  2. 开发建议：
    自定义清晰的任务名称，便于后台运维与日志检索。完整记录任务标识与请求日志，便于异常排查与对账。

  3. 异常排查：
    核对API认证信息有效、账户余额充足。校验 file_ref 有效未过期，文件已正常上传。
    严格校验传真号码格式合规，无非法字符。遇5xx临时异常，可加入指数退避重试机制。

#常见问题

  1. 任务创建成功后为什么显示待发送状态？
    刚提交时待发送为正常待调度状态，系统会自动排队投递，可通过状态查询接口实时跟踪进度。

  2. 批量多个文件如何高效发送？ 单任务支持最多 3 个文件，多页文档建议合并为单个PDF。一旦上传成功后，可以重复是使用，不需要重新上传。

  3. 批量收件人数量超出限制如何处理？
    需拆分多个任务分批提交，避免参数超限导致创建失败。

#下一步操作

任务创建成功后，可通过返回的 task_ref 调用查询任务状态接口，实时获取传真发送进度、成功/失败结果，处理异常投递任务。