提交传真任务

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

接口基础信息

请求参数

请求示例

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

返回字段说明

任务基础信息

收件人信息

规范与限制

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

1. 文件限制：
   单任务最多绑定 3 个文件，建议多页面文档合并为 PDF，提升发送效率。
2. 收件人限制：
   单任务最多 100 个收件人，超出数量需拆分多任务提交。
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 调用查询任务状态接口，实时获取传真发送进度、成功/失败结果，处理异常投递任务。