1. 接口
Help for ShipSage
  • 中文版 V2.0
    • 接口集成
      • OMS API
        • 入门指南
        • 接口
          • 店铺
          • 仓库
          • 产品
          • 库存
          • 订单
          • 包裹
          • 物流跟踪
          • 发货计划
          • 转运
          • 增值服务
          • 退货
          • 文件上传
  • English V2.0
    • API Integration
      • OMS API
        • Getting Started
        • APIs
          • Account
          • Warehouse
          • Product
          • Inventory
          • Order
          • Shipping
          • Tracking
          • ASN
          • Transfer
          • VAS
          • Return
          • File Upload
  1. 接口

转运

端点#

方法端点描述
GET/api/v202608/transfers获取转运单列表
POST/api/v202608/transfers创建转运单
PUT/api/v202608/transfers/{transfer_id}声明 FBA 装箱切分（仅 Pending Shipment Id 状态）
DELETE/api/v202608/transfers/{transfer_id}取消转运单
GET/api/v202608/transfer-docs获取转运单附件列表
POST/api/v202608/transfer-docs上传转运单附件
DELETE/api/v202608/transfer-docs/{doc_id}删除转运单附件
[新增] v202608 新增接口（2026-09 补丁）：以上 7 个转运接口均为本次新增，v202206 未提供。
本版仅支持组合：shipment_type = 1 (Amazon FBA) + shipping_arrangement_id = 1 (Customer Pickup) + SKU 装载。其他组合会返回 "not supported in v202608 yet" 错误。

头部#

键值
AuthorizationBearer eyJ0eXAiOiJKV1QiLCJhbGciOi ...

GET /api/v202608/transfers （获取转运单列表）#

响应始终返回完整详情结构。transfer_id 参数仅作过滤器：指定 → 单条；不指定 → 列表。

请求#

参数#
类型名称描述必填/选填数据结构
queryapiAPI 类型

可用值:
index.by-default		必填enum
querytransfer_id转运单 id选填integer
queryshipment_type转运类型 id（本版仅 1 = Amazon FBA）选填integer
querysource_warehouse_id源仓库 id选填integer
querystatus转运单处理状态（通过 API 创建的转运单直接进入 Review，不会停留在 Draft，因此 API 文档不列 Draft）。整体流转：Review → Pending → Open → In Progress → …（中间步骤按 SPD/LTL、仓库打包/客户打包变体略有差异）→ Ready Pickup → Billing Audit → Completed；Cancelled 可在 Open 及之前任意状态触发
可用值:
Review：转运单创建后的初始状态，仓库排队审核中
Pending：审核已通过，正在等待所关联的前置对象（如 VAS 单）完成，前置对象一旦就绪即自动流转到 Open；不依赖任何前置对象的转运单在审核通过时会直接跳过 Pending 进入 Open
Open：所有前置对象已就绪，仓库可以开始拣货（取消窗口截止于此，之后不能再取消）
In Progress：仓库开始拣货
Pending Shipment Id：仓库已打完箱，等待客户在 Amazon 生成 FBA shipment 号后调用「声明 FBA 装箱切分」把每个 packed carton 分配到对应 shipment（仅出现于 DC 打包流程）
In Progress Palletize：仓库正在打托（仅 LTL 流程）
Pending Label/BOL：等待客户提供承运商 Shipping Label / BOL 附件（LTL 流程，附件上传满足流程要求后自动流转到下一状态）
In Progress Finalize：仓库正在贴标、收尾
Ready Pickup：货物已备好，等待承运商上门提货
Billing Audit：承运商已提货离仓，仓库正在做账单审核
Completed：转运单完全结束，费用已出账（响应字段 fees 仅在此状态返回具体明细）
Cancelled：转运单已取消
不区分大小写，- / _ / 空格等价		选填string
querycreated_at_from创建时间 开始（PST）选填datetime
querycreated_at_to创建时间 结束（PST）选填datetime
queryupdated_at_from更新时间 开始
时区：太平洋标准时间		选填datetime
queryupdated_at_to更新时间 结束
时区：太平洋标准时间		选填datetime
querynext_token下一页数据的秘钥选填string
请求示例#
GET /api/v202608/transfers?api=index.by-default&shipment_type=1&source_warehouse_id=100&status=Pending%20Shipment%20Id&created_at_from=2026-08-01%2000:00:00&created_at_to=2026-08-31%2023:59:59

返回#

键值
errcode0/4000
errmsgok/Error Info
dataData Properties
Data properties#
名称描述数据结构
transfer_id转运单 idinteger
title标题string
description描述string
status转运单当前状态。整体流转：Review → Pending → Open → In Progress → …（中间步骤依 SPD/LTL、仓库/客户打包变体不同）→ Ready Pickup → Billing Audit → Completed；也可能为 Cancelled：
Review：转运单创建后的初始状态，仓库审核中
Pending：审核通过，等待关联的前置对象（如 VAS 单）完成后才能进入 Open（无前置依赖的转运单会跳过此状态）
Open：所有前置对象就绪，仓库可开始拣货（取消窗口截止于此）
In Progress：仓库开始拣货
Pending Shipment Id：仓库已打完箱，等待客户分配 FBA shipment 号（仅 DC 打包）
In Progress Palletize：仓库正在打托（仅 LTL）
Pending Label/BOL：等待客户上传 Shipping Label / BOL（LTL）
In Progress Finalize：仓库正在贴标、收尾
Ready Pickup：货物已备好，等待承运商提货
Billing Audit：承运商已提货，账单审核中
Completed：结束，费用已出账（fees 有值）
Cancelled：已取消		string
shipment_type转运类型 id（本版仅 1 = Amazon FBA）integer
shipping_method_idShipping method id：出运方式，决定后续走小包还是整车流程
可用值:
1：SPD（Small Parcel Delivery，小包裹）
2：LTL（Less Than Truckload，整车 / 拼车）		integer
shipping_arrangement_id运输安排方 id：本票货由谁负责安排运输
可用值:
1：Customer Pickup（由客户自行安排运输，包括自提或委托第三方承运商到仓库提货）

本版仅支持 1，未来会新增"由 ShipSage 代为安排运输"的选项		integer
inventory_source库存来源 id：本转运单从哪一批库存扣减发货
1：On Hand——直接从仓库现有库存中扣减，创建后无需等待任何前置对象，可立即进入 Open 拣货
2：VAS——从关联 VAS 单的加工产出中扣减，需等 VAS 完成后其产出库存到位；关联 VAS 未完成前转运单处于 Pending 状态
3：ASN——从关联 ASN 到货后的库存中扣减，需等 ASN 收货入库完成；关联 ASN 未收货前转运单处于 Pending 状态		integer
source_warehouse_id源仓库 idinteger
is_dc_packing_list装箱模式：由谁负责决定装箱方式（拆几个 shipment、每个 shipment 装几箱、每箱装什么 SKU / 多少数量）
0：Customer Packing——客户在源头已打好箱，创建时传入完整的 3 层结构 shipments → cartons → items；后续仓库直接按此结构拣货、无需 Pending Shipment Id 阶段
1：DC Packing——客户只提供 SKU 汇总（manifest_items），由仓库（DC = Distribution Center）根据 SKU 决定装几箱、每箱怎么装；仓库打完箱后转运单进入 Pending Shipment Id 状态，packed_cartons 字段返回每箱明细，客户据此在 Amazon 生成对应数量的 FBA shipment 号后调用「声明 FBA 装箱切分」接口分配		integer
reference_order_number客户参考订单号string
master_tracking_number主 tracking 号string
actual_finish_time实际完成时间
时区：太平洋标准时间		datetime
manifest_itemsSKU 汇总数组（按 SKU 求和后的清单）array
shipmentsShipment 数组（3 层嵌套 shipment → cartons → items）array
packed_cartons已打包 carton 列表（仅 Pending Shipment Id 状态有值）array
fees费用数组（仅 Completed 状态有值，否则空数组）array
created_at创建时间
时区：太平洋标准时间		datetime
updated_at更新时间
时区：太平洋标准时间		datetime
manifest_items 子结构#
名称描述数据结构
customer_sku客户 sku 编码string
qty数量总和integer
shipments 子结构#
名称描述数据结构
shipment_numberFBA 分配的 shipment 号string
fulfillment_center目的中心string
cartons装箱数组（下详）array
shipments.cartons 子结构#
名称描述数据结构
carton_numberCarton 编号integer
barcode条码string
length箱长（inch）number
width箱宽（inch）number
height箱高（inch）number
weight箱重（lb）number
tracking_number单箱 tracking（可空）string
items装箱项数组：customer_sku + units_per_cartonarray
packed_cartons 子结构#
名称描述数据结构
carton_numberCarton 编号integer
barcode条码string
length箱长（inch）number
width箱宽（inch）number
height箱高（inch）number
weight箱重（lb）number
customer_skusSKU 列表（逗号分隔）string
units单位数integer
fees 子结构#
名称描述数据结构
fee_name费用名string
balance_type结算类型string
price单价decimal
qty数量decimal
total_fee总费用（price × qty）decimal
description描述string
返回示例#
{
    "errcode": 0,
    "errmsg": "ok",
    "data": {
        "items": [
            {
                "transfer_id": 12345,
                "title": "FBA-20260810-001",
                "description": "Send 100 units to SEA8",
                "status": "Pending Shipment Id",
                "shipment_type": 1,
                "shipping_method_id": 1,
                "shipping_arrangement_id": 1,
                "inventory_source": 1,
                "source_warehouse_id": 100,
                "is_dc_packing_list": 1,
                "reference_order_number": "PO-2026-001",
                "master_tracking_number": null,
                "actual_finish_time": null,
                "manifest_items": [
                    { "customer_sku": "CUS-SKU-001", "qty": 100 }
                ],
                "shipments": [],
                "packed_cartons": [
                    {
                        "carton_number": 1,
                        "barcode": "P00001",
                        "length": 12, "width": 10, "height": 8, "weight": 5.2,
                        "customer_skus": "CUS-SKU-001",
                        "units": 50
                    }
                ],
                "fees": [],
                "created_at": "2026-08-10 09:00:00",
                "updated_at": "2026-08-12 14:00:00"
            }
        ],
        "next_token": null
    }
}

POST /api/v202608/transfers （创建转运单）#

请求#

参数#
类型名称描述必填/选填数据结构
queryapiAPI 类型

可用值:
store.by-default		必填enum
bodytitle转运单标题必填string
bodyshipment_type转运类型
可用值:
1：Amazon FBA		必填enum
bodyshipping_method_idShipping method id：出运方式，决定后续走小包还是整车流程
可用值:
1：SPD（Small Parcel Delivery，小包裹）
2：LTL（Less Than Truckload，整车 / 拼车）		必填enum
bodyshipping_arrangement_id运输安排方：本票货由谁负责安排运输
可用值:
1：Customer Pickup（由客户自行安排运输，包括自提或委托第三方承运商到仓库提货）

本版仅支持 1		必填enum
bodysource_warehouse_id源仓库 id必填integer
bodyinventory_source库存来源：本转运单从哪一批库存扣减发货
可用值:
1：On Hand——直接从仓库现有库存中扣减
2：VAS——从关联 VAS 单的加工产出中扣减，需等 VAS 完成（关联 VAS 未完成前转运单处于 Pending）
3：ASN——从关联 ASN 到货后的库存中扣减，需等 ASN 收货入库完成（关联 ASN 未收货前转运单处于 Pending）		必填enum
bodyis_dc_packing_list装箱模式：由谁负责决定装箱方式
可用值:
0：Customer Packing——客户在源头已打好箱，需在 body 里以 3 层嵌套结构 shipments → cartons → items 完整传入，仓库照此拣货、不经过 Pending Shipment Id 阶段
1：DC Packing——客户只提供 SKU 汇总清单（manifest_items 字段），由仓库根据 SKU 决定装几箱；仓库打完箱后转运单进入 Pending Shipment Id，客户据此在 Amazon 生成 shipment 号后调用「声明 FBA 装箱切分」分配		必填enum
bodyvas_id关联 VAS id（inventory_source = 2 时必填，且 VAS 必须存在）条件必填integer
bodyasn_id关联 ASN id（inventory_source = 3 时必填，且 ASN 必须存在）条件必填integer
bodymanifest_itemsSKU 明细数组（is_dc_packing_list = 1 时必填）条件必填array
bodyshipmentsShipment 数组（is_dc_packing_list = 0 时必填，3 层嵌套）条件必填array
bodyreference_order_number客户参考订单号选填string
bodymaster_tracking_number主 tracking 号选填string
bodydescription描述选填string
注：
handling_unit_id 不接受传入，本版固定为 SKU
manifest_items 子结构（DC Packing 模式）#
名称描述必填/选填数据结构
customer_sku客户 sku 编码必填string
qty数量（> 0）必填integer
shipments 子结构（Customer Packing 模式）#
名称描述必填/选填数据结构
shipment_numberShipment 号（批次内不能重复）必填string
fulfillment_center目的中心选填string
cartons装箱类型数组必填array
documents该 shipment 附件（下详）选填array
shipments.cartons 子结构#
名称描述必填/选填数据结构
qty该箱型数量（> 0）必填integer
length箱长（inch，> 0）必填number
width箱宽（inch，> 0）必填number
height箱高（inch，> 0）必填number
weight箱重（lb，> 0）必填number
items箱内 SKU 数组必填array
tracking_number单箱 tracking选填string
reference_po_idPO 号选填string
comments备注选填string
shipments.cartons.items 子结构#
名称描述必填/选填数据结构
customer_sku客户 sku 编码必填string
units_per_carton每箱装数（> 0）必填integer
shipments.documents 子结构（可选）#
名称描述必填/选填数据结构
type_id附件类型 id。创建接口内嵌上传时仅接受以下 7 类，其余类型需在转运单创建后走 POST /transfer-docs 接口
可用值:
1：Carton Label——箱唛，贴在每箱外部（含承运商追踪或 Amazon FBA 追踪信息）
2：Pallet Label——托盘标签（含 SSCC 等托盘级追踪信息）
3：BOL——提单 / 运单（Bill of Lading），LTL/FTL 承运凭证
4：Signed BOL——承运商签收后的 BOL 副本，用于结算与审计
5：Packing Slip——装箱单（随货附带的商品清单，供收货方核对）
8：Shipping Label——小包裹运输面单（SPD 场景用）
11：Other——其他		必填enum
url文件 URL——必须是先调用 ShipSage 文件上传接口 POST /api/v202206/files?api=store.by-upload 后拿到的返回 URL，不接受任何外部/第三方 URL
校验规则：
1. 域名须为 ShipSage 名下（shipsage.com / shipsage.cn / gaatu.com / jootop.com 及其子域）
2. 路径须以 /uploads/ 开头
3. 目标文件必须真实存在（系统会实时校验存储中该文件是否可达）
4. Query String 与 Fragment 会被服务端自动去掉（签名链接会过期，不允许持久化）
5. 存入库时按相对路径存储，长度上限 255 字符

背景：这些附件由仓库在数天后打印使用（打 BOL、贴箱唛）。若指向外部服务器，届时链接可能失效——因此强制要求所有附件必须先上传到 ShipSage 存储		必填string
doc_name文件名（省略时自动从 URL basename 推导）选填string
请求示例（DC Packing 模式，is_dc_packing_list = 1）#
{
    "title": "FBA-20260810-001",
    "shipment_type": 1,
    "shipping_method_id": 1,
    "shipping_arrangement_id": 1,
    "source_warehouse_id": 100,
    "inventory_source": 1,
    "is_dc_packing_list": 1,
    "reference_order_number": "PO-2026-001",
    "description": "Send 100 units to SEA8",
    "manifest_items": [
        { "customer_sku": "CUS-SKU-001", "qty": 100 }
    ]
}
请求示例（Customer Packing 模式，is_dc_packing_list = 0）#
{
    "title": "FBA-20260810-002",
    "shipment_type": 1,
    "shipping_method_id": 1,
    "shipping_arrangement_id": 1,
    "source_warehouse_id": 100,
    "inventory_source": 1,
    "is_dc_packing_list": 0,
    "shipments": [
        {
            "shipment_number": "FBA15ABC123",
            "fulfillment_center": "SEA8",
            "cartons": [
                {
                    "qty": 2,
                    "length": 12,
                    "width": 10,
                    "height": 8,
                    "weight": 5.2,
                    "tracking_number": "1Z999AA10123456784",
                    "reference_po_id": "PO-2026-001",
                    "comments": "",
                    "items": [
                        { "customer_sku": "CUS-SKU-001", "units_per_carton": 50 }
                    ]
                }
            ],
            "documents": [
                {
                    "type_id": 3,
                    "url": "https://cdn.shipsage.com/docs/bol.pdf",
                    "doc_name": "bol.pdf"
                }
            ]
        }
    ]
}

返回#

键值
errcode0/4000
errmsgok/Error Info
dataData Properties
Data properties#
名称描述数据结构
transfer_id新创建的转运单 idinteger
status转运单状态字符串（通常为 Review）string
返回示例#
{
    "errcode": 0,
    "errmsg": "ok",
    "data": {
        "transfer_id": 12345,
        "status": "Review"
    }
}

PUT /api/v202608/transfers/{transfer_id} （声明 FBA 装箱切分）#

触发时机：仓库已装完箱（Pending Shipment Id 状态），客户从 Amazon 拿到 FBA shipment 号后，把仓库的每个 packed carton 分配到对应 shipment。这是本接口唯一支持的 PUT 语义。

请求#

参数#
类型名称描述必填/选填数据结构
pathtransfer_id目标转运单 id必填integer
queryapiAPI 类型

可用值:
update.by-declare-shipments		必填enum
bodyshipmentsShipment 分配数组（下详）必填array
shipments 子结构#
名称描述必填/选填数据结构
shipment_numberFBA 分配的 shipment 号（不重复）必填string
fulfillment_center目的中心（Amazon 随号给出）必填string
cartonsCarton 分配数组必填array
documents该 shipment 附件（同创建接口）选填array
shipments.cartons 子结构#
名称描述必填/选填数据结构
carton_number对应 GET /transfers 响应里 packed_cartons.carton_number必填integer
分配规则：
每个 packed carton 必须且仅能被分配到一个 shipment
存在未分配的 carton → 报错 Every carton must be assigned to a shipment; N left out: ...
一个 carton 分给多个 shipment → 报错 carton X is assigned to Y as well
carton_number 不在 packed list 中 → 报错 carton X is not a carton of this transfer
请求示例#
PUT /api/v202608/transfers/12345?api=update.by-declare-shipments
{
    "shipments": [
        {
            "shipment_number": "FBA15ABC123",
            "fulfillment_center": "SEA8",
            "cartons": [
                { "carton_number": 1 },
                { "carton_number": 2 }
            ],
            "documents": [
                { "type_id": 3, "url": "https://cdn.shipsage.com/docs/bol.pdf", "doc_name": "bol.pdf" }
            ]
        },
        {
            "shipment_number": "FBA15DEF456",
            "fulfillment_center": "LAX9",
            "cartons": [
                { "carton_number": 3 }
            ]
        }
    ]
}

返回#

键值
errcode0/4000
errmsgok/Error Info
dataData Properties
Data properties#
名称描述数据结构
transfer_id转运单 idinteger
status转运单最新状态。依 SPD/LTL 流程及本次是否同步上传 BOL / Label 附件不同，可能为 In Progress Palletize（LTL 打托中） / Pending Label/BOL（LTL 等附件） / In Progress Finalize（收尾中）等string
返回示例#
{
    "errcode": 0,
    "errmsg": "ok",
    "data": {
        "transfer_id": 12345,
        "status": "Pending Label/BOL"
    }
}

DELETE /api/v202608/transfers/{transfer_id} （取消转运单）#

取消不物理删除，转运单保留在 Cancelled 状态可查询。
允许状态：Review / Pending / Open。已 Cancelled 或已进入拣货流程的转运单不允许取消；任一关联 shipment 已发货或已开票的也不允许。

请求#

参数#
类型名称描述必填/选填数据结构
pathtransfer_id要取消的转运单 id必填integer
queryapiAPI 类型

可用值:
destroy.by-default		必填enum
bodyreason取消原因选填string
请求示例#
DELETE /api/v202608/transfers/12345?api=destroy.by-default
{
    "reason": "客户改变主意，本单不再需要发货"
}

返回#

键值
errcode0/4000
errmsgok/Error Info
dataData Properties
Data properties#
名称描述数据结构
transfer_id转运单 idinteger
status状态（Cancelled）string
cancelled_at取消时间戳
时区：太平洋标准时间		datetime
返回示例#
{
    "errcode": 0,
    "errmsg": "ok",
    "data": {
        "transfer_id": 12345,
        "status": "Cancelled",
        "cancelled_at": "2026-08-14 15:30:00"
    }
}

GET /api/v202608/transfer-docs （获取转运单附件列表）#

transfer_id 必带。任何状态的 transfer（含 Cancelled）都可读附件。

请求#

参数#
类型名称描述必填/选填数据结构
queryapiAPI 类型

可用值:
index.by-default		必填enum
querytransfer_id目标转运单 id必填integer
querytype_id按附件类型过滤
可用值:
1：Carton Label（箱唛）
2：Pallet Label（托盘标签）
3：BOL（提单 / 运单）
4：Signed BOL（已签收 BOL）
5：Packing Slip（装箱单，随货附带的商品清单）
6：Reference File（参考文件）
7：GTIN-14 Label（GTIN-14 标签）
8：Shipping Label（小包裹面单）
9：GS1 Carton Label（GS1 箱标签）
10：GS1 Pallet Label（GS1 托盘标签）
11：Other（其他）		选填integer
querytransfer_shipment_id按 shipment 过滤选填integer
querynext_token下一页数据的秘钥选填string
请求示例#
GET /api/v202608/transfer-docs?api=index.by-default&transfer_id=12345&type_id=3

返回#

键值
errcode0/4000
errmsgok/Error Info
dataData Properties
Data properties#
名称描述数据结构
doc_id附件 idinteger
transfer_id所属转运单 idinteger
transfer_shipment_id所属 shipment（0 = 挂在主单上）integer
type_id附件类型 id：
1：Carton Label（箱唛，贴在每箱外部）
2：Pallet Label（托盘标签）
3：BOL（提单 / 运单，LTL/FTL 承运凭证）
4：Signed BOL（承运商签收后的 BOL 副本）
5：Packing Slip（装箱单，随货附带的商品清单）
6：Reference File（参考文件）
7：GTIN-14 Label（GTIN-14 全球贸易项代码标签）
8：Shipping Label（小包裹运输面单，SPD 用）
9：GS1 Carton Label（GS1 标准箱标签）
10：GS1 Pallet Label（GS1 标准托盘标签）
11：Other（其他）		integer
doc_name文件名string
ext扩展名string
url附件的完整 URL：域名为 ShipSage 名下（*.shipsage.com / *.shipsage.cn / *.gaatu.com / *.jootop.com），路径以 /uploads/ 开头。
访问方式：owner = Merchant（客户上传，落在 company 0）的文件通过公共文件路由访问，任何持有 URL 者可直接下载（供仓库数天后打印）；owner = ShipSage（仓库上传，落在仓库公司目录）的文件需要携带 token 走认证路由。
有效期：长期有效，不会过期		string
comments备注string
ownerMerchant（客户上传）/ ShipSage（仓库上传）string
created_at上传时间
时区：太平洋标准时间		datetime
返回示例#
{
    "errcode": 0,
    "errmsg": "ok",
    "data": {
        "items": [
            {
                "doc_id": 9001,
                "transfer_id": 12345,
                "transfer_shipment_id": 0,
                "type_id": 3,
                "doc_name": "bol.pdf",
                "ext": "pdf",
                "url": "https://cdn.shipsage.com/docs/bol.pdf",
                "comments": "",
                "owner": "Merchant",
                "created_at": "2026-08-11 10:15:00"
            }
        ],
        "next_token": null
    }
}

POST /api/v202608/transfer-docs （上传转运单附件）#

一次上传一个附件。仅 Cancelled 状态不允许写入。URL 必须来自 ShipSage 文件上传接口。附件上传完成后，如果该文件正好是转运单流程等待的最后一份（比如 Pending Label/BOL 状态在等 BOL），转运单会自动前进到下一状态。

请求#

参数#
类型名称描述必填/选填数据结构
queryapiAPI 类型

可用值:
store.by-default		必填enum
bodytransfer_id目标转运单 id必填integer
bodytransfer_shipment_id挂到具体 shipment；0 或省略 = 挂主单选填integer
bodytype_id附件类型 id
可用值:
1：Carton Label（箱唛，贴在每箱外部）
2：Pallet Label（托盘标签）
3：BOL（提单 / 运单，LTL/FTL 承运凭证）
4：Signed BOL（承运商签收后的 BOL 副本）
5：Packing Slip（装箱单，随货附带的商品清单）
6：Reference File（参考文件）
7：GTIN-14 Label（GTIN-14 全球贸易项代码标签）
8：Shipping Label（小包裹运输面单，SPD 用）
9：GS1 Carton Label（GS1 标准箱标签）
10：GS1 Pallet Label（GS1 标准托盘标签）
11：Other（其他）		必填enum
bodyurl文件 URL——必须是先调用 ShipSage 文件上传接口 POST /api/v202206/files?api=store.by-upload 后拿到的返回 URL，不接受任何外部/第三方 URL
校验规则：
1. 域名须为 ShipSage 名下（shipsage.com / shipsage.cn / gaatu.com / jootop.com 及其子域）
2. 路径须以 /uploads/ 开头
3. 目标文件必须真实存在（系统会实时校验存储中该文件是否可达）
4. Query String 与 Fragment 会被服务端自动去掉（签名链接会过期，不允许持久化）
5. 存入库时按相对路径存储，长度上限 255 字符

背景：这些附件由仓库在数天后打印使用（打 BOL、贴箱唛）。若指向外部服务器，届时链接可能失效——因此强制要求所有附件必须先上传到 ShipSage 存储		必填string
bodydoc_name文件名（省略从 URL basename 推导；最长 255 字符）选填string
bodycomments备注（最长 255 字符）选填string
说明：客户端上传的附件 owner 一律为 Merchant。
请求示例#
{
    "transfer_id": 12345,
    "transfer_shipment_id": 0,
    "type_id": 3,
    "url": "https://cdn.shipsage.com/docs/bol.pdf",
    "doc_name": "bol.pdf",
    "comments": "Signed BOL from carrier"
}

返回#

键值
errcode0/4000
errmsgok/Error Info
dataData Properties
Data properties#
名称描述数据结构
doc_id新附件 idinteger
transfer_id转运单 idinteger
transfer_shipment_idShipment idinteger
type_id附件类型 id（值同上请求 body 的 type_id）integer
doc_name文件名string
url附件的完整 URL：域名为 ShipSage 名下（*.shipsage.com / *.shipsage.cn / *.gaatu.com / *.jootop.com），路径以 /uploads/ 开头，长期有效string
返回示例#
{
    "errcode": 0,
    "errmsg": "ok",
    "data": {
        "doc_id": 9002,
        "transfer_id": 12345,
        "transfer_shipment_id": 0,
        "type_id": 3,
        "doc_name": "bol.pdf",
        "url": "https://cdn.shipsage.com/docs/bol.pdf"
    }
}

DELETE /api/v202608/transfer-docs/{doc_id} （删除转运单附件）#

仅允许删除本公司上传的附件（owner = Merchant）；仓库端上传的附件不允许删除。转运单已取消时也不允许操作附件。

请求#

参数#
类型名称描述必填/选填数据结构
pathdoc_id附件 id必填integer
queryapiAPI 类型

可用值:
destroy.by-default		必填enum
bodyreason删除原因（会追加到附件备注末尾，格式 [Deleted: <reason>]）选填string
请求示例#
DELETE /api/v202608/transfer-docs/9002?api=destroy.by-default
{
    "reason": "文件版本错误，重新上传"
}

返回#

键值
errcode0/4000
errmsgok/Error Info
dataData Properties
Data properties#
名称描述数据结构
doc_id附件 idinteger
transfer_id转运单 idinteger
doc_name文件名string
返回示例#
{
    "errcode": 0,
    "errmsg": "ok",
    "data": {
        "doc_id": 9002,
        "transfer_id": 12345,
        "doc_name": "bol.pdf"
    }
}
Modified at 2026-09-23 07:31:06
Previous
发货计划
Next
增值服务
Built with