文件上传接口¶

概述¶

通过本接口上传文档，支持三种文件上传方式，满足不同场景需求。上传成功后，系统会返回文件唯一标识符（file_ref），用于后续创建传真任务。

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

接口详情¶

上传方式选择¶

上传方式详解¶

方式一：表单上传（推荐）¶

适用场景：通过网页表单或直接上传本地文件。

请求示例：

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"

参数说明： - file：必填，上传的文件。 - file_name：选填，自定义文件名（不填则使用原文件名）。

方式二：URL 上传¶

适用场景：文件已存在于公网，通过 URL 直接下载。

请求示例：

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

参数说明： - remote_url：必填，文件的公网 URL 地址。 - file_name：选填，自定义文件名（不填则从 URL 提取）。

方式三：二进制上传¶

适用场景：编程场景，直接上传文件二进制内容。

请求示例：

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"

参数说明： - 请求头 X-File-Name：必填，文件名（需包含扩展名）。 - 请求体：文件的二进制内容。

响应格式¶

成功响应¶

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

失败响应¶

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

字段说明¶

常见问题¶

1. 文件大小限制¶

• 单文件最大：10 MB。
• 建议单个文件控制在 2 MB 以内，以避免上传失败。
• 创建传真任务时，最多可包含 3 个文件。

2. 支持的文件格式¶

• PDF、DOC、DOCX、TXT、JPG、PNG 等常见文档格式。
• 建议使用 PDF 格式，兼容性最佳。

3. 文件名要求¶

• 支持中文、英文、数字和常见符号。
• 建议包含文件扩展名（如 .pdf、.docx）。
• 最大长度：255 个字符。

4. 上传失败怎么办？¶

1. 检查认证信息是否正确。
2. 确认文件大小不超过限制。
3. 检查网络连接是否正常。
4. 如为 URL 上传，确认 URL 可公开访问。

使用建议¶

推荐使用方式¶

• 网页应用：使用表单上传。
• 集成已有文件：使用 URL 上传。
• 程序化集成：使用二进制上传。

文件准备¶

1. 建议将文档转换为 PDF 格式。
2. 单页图像文件建议压缩至 2 MB 以内。
3. 超大文件可拆分为多个小文件分批上传。

错误处理¶

• 建议在代码中添加重试机制。
• 记录上传失败的日志，便于排查问题。
• 对于重要文件，建议先测试再正式使用。

下一步¶

文件上传成功后，使用返回的 file_ref 创建传真任务：

• 参考 发送传真接口 文档。
• 将 file_ref 添加到传真任务的文件列表中。