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