文件上传

端点

方法	端点	描述
POST	/api/v202206/files	上传附件文件到 ShipSage 存储，获得可用于后续接口的 URL

[新增] v202608 补丁（2026-09 新增）：本文档为本次新增，用于统一介绍附件文件上传流程；接口本身沿用 v202206 版本，之前未在本目录中列出。
用途：所有 POST /asn-docs、POST /vas-docs、POST /transfer-docs 及 POST /transfers（内嵌 shipments.documents）接口所需的 url 参数，必须先通过本接口上传文件，取得返回的 URL 后再传给对应的附件挂载接口。任何外部 / 第三方 URL 都会被拒绝。

头部

键	值
Authorization	Bearer eyJ0eXAiOiJKV1QiLCJhbGciOi ...
Content-Type	multipart/form-data

POST /api/v202206/files （上传附件文件）

上传一个文件到 ShipSage 公共存储桶，返回可持久保存的公开 URL。返回的 URL 可作为 url 字段传给 ASN / VAS / Transfer 的附件挂载接口。

存储与可访问性说明：

文件落地在 company 0 的公共目录下，返回的 URL 走"公共文件重定向到签名 S3 链接"的路径——**任何持有该 URL 的人（无需鉴权 token）**都可以下载文件；这就是仓库能在数天后直接打印它的原因。

该 URL 是长期有效的，不会过期；因此适合作为附件持久化保存。

若你需要更强隐私的私有存储，请与 ShipSage 商议——本接口专用于"允许 URL 分发的附件"场景（即挂到 ASN / VAS / Transfer 单据上、供仓库读取打印的文件）。

请求

参数

类型	名称	描述	必填/选填	数据结构
query	api	API 类型可用值: store.by-upload	必填	enum
formData	file	待上传的文件（`multipart/form-data` 中 `file` 字段，二进制流）	必填	file
formData	file_name	自定义存储文件名。省略时使用上传文件的原始文件名；用于避免名称冲突或规范化命名	选填	string

约束：

请求头 Content-Type 必须为 multipart/form-data

file 字段传的是真正的文件流，不是 base64 字符串

允许的扩展名与体积上限跟随 ShipSage 服务器全局配置（如遇拒绝错误请与 ShipSage 联系确认限制）

请求示例

POST /api/v202206/files?api=store.by-upload
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW

------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="file"; filename="bol.pdf"
Content-Type: application/pdf

<PDF 二进制内容>
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="file_name"

bol-transfer-12345.pdf
------WebKitFormBoundary7MA4YWxkTrZu0gW--

键	值
errcode	0/4000
errmsg	ok/Error Info
data	Data Properties

Data properties

名称	描述	数据结构
url	上传成功后返回的绝对 URL。域名为 ShipSage 名下（`.shipsage.com` / `.shipsage.cn` / `.gaatu.com` / `.jootop.com`），路径以 `/uploads/` 开头。此 URL 应原样传给 `POST /asn-docs` / `POST /vas-docs` / `POST /transfer-docs` 的 `url` 参数	string

返回示例

{
    "errcode": 0,
    "errmsg": "ok",
    "data": {
        "url": "https://app.shipsage.com/uploads/0/2026/09/bol-transfer-12345.pdf"
    }
}

典型使用流程

以"给转运单挂 BOL 附件"为例，客户端需要两步：

Step 1：上传文件，拿到 URL

POST /api/v202206/files?api=store.by-upload
Content-Type: multipart/form-data
(file 字段承载 bol.pdf 二进制)

响应：
{ "errcode": 0, "errmsg": "ok", "data": { "url": "https://app.shipsage.com/uploads/0/2026/09/bol.pdf" } }

Step 2：把 URL 挂到转运单

POST /api/v202608/transfer-docs?api=store.by-default
Content-Type: application/json

{
    "transfer_id": 12345,
    "type_id": 3,
    "url": "https://app.shipsage.com/uploads/0/2026/09/bol.pdf",
    "doc_name": "bol.pdf"
}

为什么必须走 ShipSage 存储：附件由仓库在数天后打印使用（BOL、箱唛等）。若指向客户自己的服务器或第三方链接，届时链接可能已失效——ShipSage 无法预知、无法修复，只能在打印那一刻才发现问题。因此系统强制附件必须先落到 ShipSage 存储、且是长期可访问的公共 URL。

端点#

头部#

POST /api/v202206/files （上传附件文件）#

请求#

参数#

请求示例#

返回#

Data properties#

返回示例#

典型使用流程#

端点

头部

POST /api/v202206/files （上传附件文件）

请求

参数

请求示例

返回

Data properties

返回示例

典型使用流程