Skip to main content
Home
  • API 参考
  • 上传传真文件

文件上传

本接口用于上传传真所需文档，支持表单上传、URL远程上传、二进制流式上传三种方式，适配不同开发场景。文件上传成功后返回唯一文件标识 file_ref，该参数为创建传真任务的核心必填参数。

#接口基础信息

项目 说明
请求方法 POST
接口路径 /api/v2/files/upload
访问认证 请求头携带 X-API-Key、X-API-Secret，参考 API 认证
头部参数 Content-Type，详见下方上传方式说明

#上传方式说明

上传方式 适用场景 Content-Type
表单上传（推荐） 本地文件快速上传 multipart/form-data
URL上传 文件已托管公网地址，远程拉取上传 application/json
二进制上传 本地文件流式上传 application/octet-stream

#请求示例

#表单上传（推荐）

参数说明：file（必填，本地文件）、file_name（选填，自定义文件名）

shell 
curl -X POST "http://api.globfax.com/api/v2/files/upload" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@本地文件.pdf" \
  -F "file_name=本地文件.pdf"

#URL远程上传

参数说明：remote_url（必填，公网可访问文件地址）、file_name（选填，自定义文件名）

shell 
curl -X POST "http://api.globfax.com/api/v2/files/upload" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "remote_url": "https://example.com/files/contract.pdf",
    "file_name": "远程文件.pdf"
  }'

#二进制上传

参数说明：请求头 X-File-Name（必填，完整文件名含后缀）、请求体为文件二进制流

shell 
curl -X POST "http://api.globfax.com/api/v2/files/upload" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret" \
  -H "Content-Type: application/octet-stream" \
  -H "X-File-Name: 二进制文件.pdf" \
  --data-binary "@/path/to/file.pdf"

#响应结果

#调用成功

json 
{
  "success": true,
  "message": "File uploaded",
  "data": {
    "file_ref": "file_abc123def456",
    "file_size": 1048576,
    "file_ext": "pdf"
  }
}

#调用失败

json 
{
  "success": false,
  "message": "错误描述",
  "errors": "详细错误信息"
}

#返回字段说明

字段名 数据类型 字段说明 示例值
file_ref string 文件唯一标识，用于创建传真任务 file_abc123def456
file_size int 文件大小，单位：字节 1048576
file_ext string 文件后缀格式 pdf