上传传真文件

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

接口基础信息

上传方式说明

请求示例

表单上传（推荐）

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

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（选填，自定义文件名）

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（必填，完整文件名含后缀）、请求体为文件二进制流

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"

响应结果

调用成功

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

调用失败

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

返回字段说明

规范与限制

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

1. 文件基础规范：
   兼容 PDF、DOC、DOCX、TXT、JPG、PNG 等主流格式，优先使用 PDF，排版兼容性最佳。 单文件最大建议控制在 5MB 以内。单个传真任务最多关联 3 个已上传文件。
2. 文件名规范：
   文件名支持中文、英文、数字及常规符号，最大长度 255 字符。 件名必须携带合法后缀扩展名，否则无法解析。
3. 场景适配规范：
   WEB端业务优先使用表单上传，适配前端交互场景。 公网已有文件使用 URL 远程上传，无需重复下载，高效便捷。 代码层建议增加日志记录与重试机制，适配网络临时波动。

常见问题

1. 文件上传失败如何排查？
   依次排查：认证信息有效性、文件大小/格式合规性、网络连通性；URL上传需确认链接无防盗、无登录权限、公开可访问。
2. 是否支持批量上传文件？
   接口单次仅支持单文件上传，可多次调用上传多个文件，最终最多3个文件组合为一个传真任务。
3. 上传的文件是否长期有效？
   上传文件有效期 30 天。上传后的文件资源可正常用于传真创建，建议上传后及时调用发送接口完成任务创建。

下一步操作

文件上传成功获取 file_ref 后，可传入发送传真接口，创建并提交传真发送任务。