增值服务

端点

方法	端点	描述
GET	/api/v202608/vas	获取增值服务（VAS）列表
POST	/api/v202608/vas	创建增值服务（VAS）
DELETE	/api/v202608/vas/{vas_id}	取消增值服务（VAS）
GET	/api/v202608/vas-docs	获取增值服务附件列表
POST	/api/v202608/vas-docs	上传增值服务附件
DELETE	/api/v202608/vas-docs/{doc_id}	删除增值服务附件

[新增] v202608 新增接口（2026-09 补丁）：以上 6 个增值服务接口均为本次新增，v202206 未提供。

VAS 中文即"增值服务"（Value-Added Service），指仓库在标准收发货之外提供的加工 / 处理服务，例如换标、改 SKU、重新测量、组装、拆分、销毁、拍照、重包装、盘点、贴标签等。

VAS 不提供 update 接口。修改 VAS 内容 = 取消旧的 + 重建新的。

头部

键	值
Authorization	Bearer eyJ0eXAiOiJKV1QiLCJhbGciOi ...

GET /api/v202608/vas （获取增值服务 VAS 列表）

响应始终返回完整详情结构。vas_id 参数仅作过滤器。

请求

参数

类型	名称	描述	必填/选填	数据结构
query	api	API 类型可用值: index.by-default	必填	enum
query	vas_id	VAS id	选填	integer
query	vas_type	VAS 类型 id 可用值: 1：General（通用加工，具体处理内容由 `description` 描述；唯一支持 `inventory_source = 5 Conditioned` 的类型） 2：Relabel / Change SKU（换标 / 改 SKU，替换商品外标签且同步修改 SKU 归属——两个动作是同一次操作的两个侧面） 3：Remeasure（重新测量商品尺寸与重量） 4：Assembly（组装，把多个 SKU 按套件配比组装成一个新 SKU） 5：Split（拆分，把一个套件 SKU 拆成多个子 SKU） 6：Disposal（销毁 / 报废库存） 7：Photo（拍照，仓库对商品拍照存档） 8：Repackaging（重新包装，换外箱 / 加缓冲料 / 修复破损包装等） 9：Cycle Count（循环盘点，定期抽点库存核对数量） 10：Label（贴额外标签，如 FNSKU、危险品标签、Made-in 产地标签等）	选填	integer
query	status_id	状态 id（API 创建的 VAS 直接进入 `Review`，不会停留在 Draft，因此 API 不接受 `1`）。整体流转：`Review (2)` → `Pending (3)` → `Open (4)` → `In Progress (5)` → `Billing Audit (6)` → `Completed (7)`；`Cancelled (8)` 可在 `Open` 及之前任意状态触发可用值: 2：Review——VAS 创建后的初始状态，仓库排队审核中 3：Pending——审核已通过，正在等待关联的前置对象（如关联的 ASN 入库到货）完成；无前置依赖（`inventory_source = 1 On Hand`）的 VAS 会跳过该状态直接进 `Open` 4：Open——所有前置对象已就绪，仓库可开工（取消窗口截止于此，之后不能再取消） 5：In Progress——仓库开工作业 6：Billing Audit——作业完成，账单审核中 7：Completed——完全结束，费用已出账（响应字段 `fees` 仅在此状态返回具体明细） 8：Cancelled——已取消	选填	integer
query	warehouse_id	仓库 id	选填	integer
query	asn_id	按关联 ASN 过滤	选填	integer
query	scheduled_at_from	SLA 计划开始时间起时区：太平洋标准时间	选填	datetime
query	scheduled_at_to	SLA 计划开始时间止时区：太平洋标准时间	选填	datetime
query	created_at_from	创建时间起时区：太平洋标准时间	选填	datetime
query	created_at_to	创建时间止时区：太平洋标准时间	选填	datetime
query	updated_at_from	更新时间起时区：太平洋标准时间	选填	datetime
query	updated_at_to	更新时间止时区：太平洋标准时间	选填	datetime
query	next_token	下一页数据的秘钥	选填	string

请求示例

GET /api/v202608/vas?api=index.by-default&vas_type=2&status_id=5&warehouse_id=100&created_at_from=2026-08-01%2000:00:00

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

Data properties

名称	描述	数据结构
vas_id	VAS id	integer
title	标题	string
description	描述 / 原因	string
vas_type	VAS 类型 id： 1：General（通用加工，具体内容由 `description` 描述；唯一支持 `inventory_source = 5 Conditioned` 的类型） 2：Relabel / Change SKU（换标 / 改 SKU） 3：Remeasure（重新测量尺寸与重量） 4：Assembly（组装，把多个 SKU 按套件配比组装成一个新 SKU） 5：Split（拆分，把一个套件 SKU 拆成多个子 SKU） 6：Disposal（销毁 / 报废库存） 7：Photo（拍照存档） 8：Repackaging（重新包装） 9：Cycle Count（循环盘点） 10：Label（贴额外标签，如 FNSKU / 危险品标签 / 产地标签等）	integer
vas_type_name	VAS 类型显示名	string
status_id	状态 id	integer
status	VAS 处理状态（通过 API 创建的 VAS 直接进入 `Review`，不会停留在 Draft，因此 API 文档不列 Draft）。整体流转：`Review` → `Pending` → `Open` → `In Progress` → `Billing Audit` → `Completed`；`Cancelled` 可在 `Open` 及之前任意状态触发： Review：VAS 创建后的初始状态，仓库审核中 Pending：审核已通过，正在等待关联的前置对象（如关联的 ASN 入库到货）完成，前置对象一旦就绪即自动流转到 `Open`；不依赖任何前置对象（如库存来源为 On Hand）的 VAS 在审核通过时会直接跳过 `Pending` 进入 `Open` Open：所有前置对象已就绪，仓库可以开工（取消窗口截止于此） In Progress：仓库开工作业 Billing Audit：作业完成，账单审核中 Completed：完全结束，费用已出账（响应字段 `fees` 仅在此状态返回具体明细） Cancelled：已取消	string
warehouse_id	仓库 id	integer
warehouse_name	仓库名	string
inventory_source	库存来源 id：本 VAS 单从哪一批库存进行加工 1：On Hand——从仓库现有可售库存中扣减，无前置依赖，可立即进入 `Open` 3：ASN——从关联 ASN 到货后的库存中扣减，需等 ASN 收货入库完成；关联 ASN 未收货前 VAS 处于 `Pending` 状态 5：Conditioned——从非 New 状态（Damaged / 待检疫 / 已归位等）的库存中扣减，仅 `vas_type = 1 (General)` 支持	integer
inventory_source_name	库存来源显示名	string
scheduled_start_time	SLA 计划开始时间时区：太平洋标准时间	datetime
scheduled_finish_time	SLA 计划完成时间时区：太平洋标准时间	datetime
actual_start_time	实际开始时间时区：太平洋标准时间	datetime
actual_finish_time	实际完成时间时区：太平洋标准时间	datetime
vas_items	SKU 明细数组	array
linked_asn_ids	关联 ASN id 数组	array of integer
docs	客户端上传附件数组	array
photos	仓库端上传照片 URL 数组（只读，纯 URL 数组）	array of string
fees	费用数组（仅 Completed 状态有值）	array
create_time	创建时间时区：太平洋标准时间	datetime
update_time	更新时间时区：太平洋标准时间	datetime

vas_items 子结构

名称	描述	数据结构
customer_sku	客户 sku 编码	string
qty	数量	integer

docs 子结构

名称	描述	数据结构
doc_id	附件 id	integer
type_id	附件类型 id： 1：Packing Slip（装箱单，随货附带的商品清单，供收货方核对） 2：BOL（提单 / 运单，Bill of Lading，LTL 承运凭证） 3：Carton Label（箱唛，贴在每箱外部） 4：Pallet Label（托盘标签） 5：Shipping Label（小包裹运输面单，SPD 用） 6：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
owner	`Merchant` / `ShipSage`	string
created_at	上传时间时区：太平洋标准时间	datetime

fees 子结构

名称	描述	数据结构
fee_name	费用名	string
balance_type	结算类型	string
price	单价	decimal
qty	数量	decimal
total_fee	总费用（`price × qty`）	decimal
description	描述	string

返回示例

{
    "errcode": 0,
    "errmsg": "ok",
    "data": {
        "items": [
            {
                "vas_id": 15216,
                "title": "换标 A → B",
                "description": "SKU 品牌方要求换标",
                "vas_type": 2,
                "vas_type_name": "Relabel / Change SKU",
                "status_id": 5,
                "status": "In Progress",
                "warehouse_id": 100,
                "warehouse_name": "SG-MDW1",
                "inventory_source": 1,
                "inventory_source_name": "On Hand",
                "scheduled_start_time": "2026-08-15 09:00:00",
                "scheduled_finish_time": "2026-08-15 17:00:00",
                "actual_start_time": "2026-08-15 09:30:00",
                "actual_finish_time": null,
                "vas_items": [
                    { "customer_sku": "CUS-SKU-001", "qty": 200 }
                ],
                "linked_asn_ids": [],
                "docs": [
                    {
                        "doc_id": 7001, "type_id": 6, "doc_name": "authorization.pdf",
                        "ext": "pdf", "url": "https://cdn.shipsage.com/vas/authorization.pdf",
                        "owner": "Merchant", "created_at": "2026-08-14 10:00:00"
                    }
                ],
                "photos": [],
                "fees": [],
                "create_time": "2026-08-14 09:00:00",
                "update_time": "2026-08-15 09:30:00"
            }
        ],
        "next_token": null
    }
}

POST /api/v202608/vas （创建增值服务 VAS）

每次仅创建一个 VAS。创建后 VAS 状态为 Review（跳过 Draft）。

请求

参数

类型	名称	描述	必填/选填	数据结构
query	api	API 类型可用值: store.by-default	必填	enum
body	title	VAS 标题	必填	string
body	description	描述 / 原因	必填	string
body	vas_type	VAS 类型可用值: 1：General（通用加工，具体处理内容由 `description` 描述；唯一支持 `inventory_source = 5 Conditioned` 的类型；配 Conditioned 时 `vas_items` 可以为空） 2：Relabel / Change SKU（换标 / 改 SKU，替换商品外标签且同步修改 SKU 归属——两个动作是同一次操作的两个侧面） 3：Remeasure（重新测量商品尺寸与重量；`qty` 不传或 ≤ 0 时默认 1，因为重测只针对单件操作） 4：Assembly（组装，把多个 SKU 按套件配比组装成一个新 SKU；`customer_sku` 必须是套件产品） 5：Split（拆分，把一个套件 SKU 拆成多个子 SKU；`customer_sku` 必须是套件产品） 6：Disposal（销毁 / 报废库存） 7：Photo（拍照，仓库对商品拍照存档） 8：Repackaging（重新包装，换外箱 / 加缓冲料 / 修复破损包装等） 9：Cycle Count（循环盘点，定期抽点库存核对数量；`qty` 服务端强制归零，传值不生效） 10：Label（贴额外标签，如 FNSKU / 危险品标签 / 产地标签等）	必填	enum
body	warehouse_id	仓库 id	必填	integer
body	inventory_source	库存来源：本 VAS 单从哪一批库存进行加工可用值: 1：On Hand（默认）——从仓库现有可售库存中扣减 3：ASN——从关联 ASN 到货后的库存中扣减，需等 ASN 收货入库完成（关联 ASN 未收货前 VAS 处于 `Pending`） 5：Conditioned——从非 New 状态（Damaged / 待检疫 / 已归位等）的库存中扣减，仅 `vas_type = 1 (General)` 支持	选填（默认 1）	enum
body	asn_id	关联 ASN id（`inventory_source = 3` 时必填；ASN 必须存在）	条件必填	integer
body	vas_items	SKU 明细数组（见下方联动规则）	条件必填	array

联动校验：

inventory_source = 5 (Conditioned) 只能配 vas_type = 1 (General)
vas_type = 1 + inventory_source = 5 时 vas_items 可为空；其他所有组合必填
vas_type = 4 (Assembly) / 5 (Split) 时 customer_sku 必须是套件产品

vas_items 子结构

名称	描述	必填/选填	数据结构
customer_sku	客户 sku 编码	必填	string
qty	数量（规则见下）	条件必填	integer

qty 规则：

vas_type = 9 (Cycle Count)：服务端强制归零，传值不生效
vas_type = 3 (Remeasure)：不传或 <= 0 时默认 1（重测只对 1 pcs 操作）
其他类型：必填且 > 0

注：附件不在创建时挂载，走独立 POST /vas-docs 接口。

请求示例（Relabel 类型）

{
    "title": "换标 A → B",
    "description": "SKU 品牌方要求换标",
    "vas_type": 2,
    "warehouse_id": 100,
    "inventory_source": 1,
    "vas_items": [
        { "customer_sku": "CUS-SKU-001", "qty": 200 }
    ]
}

请求示例（Disposal 类型，从 ASN 上销毁）

{
    "title": "销毁 - 客户主动退运",
    "description": "客户临时退运，销毁处理",
    "vas_type": 6,
    "warehouse_id": 100,
    "inventory_source": 3,
    "asn_id": 88888,
    "vas_items": [
        { "customer_sku": "CUS-SKU-001", "qty": 50 }
    ]
}

请求示例（General + Conditioned，`vas_items` 可省）

{
    "title": "General 通用作业",
    "description": "由仓库现场判断需要的操作",
    "vas_type": 1,
    "warehouse_id": 100,
    "inventory_source": 5
}

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

Data properties

名称	描述	数据结构
vas_id	新创建的 VAS id	integer
status	VAS 状态字符串（通常为 Review）	string

返回示例

{
    "errcode": 0,
    "errmsg": "ok",
    "data": {
        "vas_id": 15216,
        "status": "Review"
    }
}

DELETE /api/v202608/vas/{vas_id} （取消增值服务 VAS）

取消不物理删除，VAS 保留在 Cancelled 状态可查询。取消会一次性完成：释放 On Hand 预留库存、归还 ASN 关联数量、取消关联的 Transfer、翻转状态、写入操作日志。

允许状态：Review / Pending / Open。已 Cancelled 或已进入作业流程的 VAS 不允许取消。

请求

参数

类型	名称	描述	必填/选填	数据结构
path	vas_id	要取消的 VAS id	必填	integer
query	api	API 类型可用值: destroy.by-default	必填	enum

请求示例

DELETE /api/v202608/vas/15216?api=destroy.by-default

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

Data properties

名称	描述	数据结构
vas_id	VAS id	integer
status	状态（`Cancelled`）	string
cancelled_at	取消时间戳时区：太平洋标准时间	datetime

返回示例

{
    "errcode": 0,
    "errmsg": "ok",
    "data": {
        "vas_id": 15216,
        "status": "Cancelled",
        "cancelled_at": "2026-08-14 15:30:00"
    }
}

GET /api/v202608/vas-docs （获取增值服务附件列表）

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

请求

参数

类型	名称	描述	必填/选填	数据结构
query	api	API 类型可用值: index.by-default	必填	enum
query	vas_id	目标 VAS id	必填	integer
query	type_id	按附件类型过滤可用值: 1：Packing Slip（装箱单，随货附带的商品清单，供收货方核对） 2：BOL（提单 / 运单） 3：Carton Label（箱唛） 4：Pallet Label（托盘标签） 5：Shipping Label（小包裹面单） 6：Other（其他）	选填	integer
query	next_token	下一页数据的秘钥	选填	string

请求示例

GET /api/v202608/vas-docs?api=index.by-default&vas_id=15216

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

Data properties

名称	描述	数据结构
doc_id	附件 id	integer
vas_id	所属 VAS id	integer
type_id	附件类型 id： 1：Packing Slip（装箱单，随货附带的商品清单，供收货方核对） 2：BOL（提单 / 运单，Bill of Lading，LTL 承运凭证） 3：Carton Label（箱唛，贴在每箱外部） 4：Pallet Label（托盘标签） 5：Shipping Label（小包裹运输面单，SPD 用） 6：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
owner	`Merchant`（客户上传）/ `ShipSage`（仓库上传）	string
created_at	上传时间时区：太平洋标准时间	datetime

返回示例

{
    "errcode": 0,
    "errmsg": "ok",
    "data": {
        "items": [
            {
                "doc_id": 7001,
                "vas_id": 15216,
                "type_id": 6,
                "doc_name": "authorization.pdf",
                "ext": "pdf",
                "url": "https://cdn.shipsage.com/vas/authorization.pdf",
                "owner": "Merchant",
                "created_at": "2026-08-14 10:00:00"
            }
        ],
        "next_token": null
    }
}

POST /api/v202608/vas-docs （上传增值服务附件）

一次上传一个附件。仅 Cancelled 状态不允许写。URL 必须来自 ShipSage 文件上传接口。

请求

参数

类型	名称	描述	必填/选填	数据结构
query	api	API 类型可用值: store.by-default	必填	enum
body	vas_id	目标 VAS id	必填	integer
body	type_id	附件类型 id 可用值: 1：Packing Slip（装箱单，随货附带的商品清单，供收货方核对） 2：BOL（提单 / 运单，Bill of Lading，LTL 承运凭证） 3：Carton Label（箱唛，贴在每箱外部） 4：Pallet Label（托盘标签） 5：Shipping Label（小包裹运输面单，SPD 用） 6：Other（其他）	必填	enum
body	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
body	doc_name	文件名（省略从 URL basename 推导；最长 255 字符）	选填	string

说明：客户端上传的附件 owner 一律为 Merchant。

请求示例

{
    "vas_id": 15216,
    "type_id": 6,
    "url": "https://cdn.shipsage.com/vas/authorization.pdf",
    "doc_name": "authorization.pdf"
}

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

Data properties

名称	描述	数据结构
doc_id	新附件 id	integer
vas_id	VAS id	integer
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": 7002,
        "vas_id": 15216,
        "type_id": 1,
        "doc_name": "picking_slip.pdf",
        "url": "https://cdn.shipsage.com/vas/picking_slip.pdf"
    }
}

DELETE /api/v202608/vas-docs/{doc_id} （删除增值服务附件）

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

请求

参数

类型	名称	描述	必填/选填	数据结构
path	doc_id	附件 id	必填	integer
query	api	API 类型可用值: destroy.by-default	必填	enum

请求示例

DELETE /api/v202608/vas-docs/500123?api=destroy.by-default

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

Data properties

名称	描述	数据结构
doc_id	附件 id	integer
vas_id	VAS id	integer
doc_name	文件名	string

返回示例

{
    "errcode": 0,
    "errmsg": "ok",
    "data": {
        "doc_id": 7002,
        "vas_id": 15216,
        "doc_name": "picking_slip.pdf"
    }
}

端点

头部

GET /api/v202608/vas （获取增值服务 VAS 列表）

请求

参数

请求示例

返回

Data properties

vas_items 子结构

docs 子结构

fees 子结构

返回示例

POST /api/v202608/vas （创建增值服务 VAS）

请求

参数

vas_items 子结构

请求示例（Relabel 类型）

请求示例（Disposal 类型，从 ASN 上销毁）

请求示例（General + Conditioned，vas_items 可省）

返回

Data properties

返回示例

DELETE /api/v202608/vas/{vas_id} （取消增值服务 VAS）

请求

参数

请求示例

返回

Data properties

返回示例

GET /api/v202608/vas-docs （获取增值服务附件列表）

请求

参数

请求示例

返回

Data properties

返回示例

POST /api/v202608/vas-docs （上传增值服务附件）

请求

参数

请求示例

返回

Data properties

返回示例

DELETE /api/v202608/vas-docs/{doc_id} （删除增值服务附件）

请求

参数

请求示例

返回

Data properties

返回示例

请求示例（General + Conditioned，`vas_items` 可省）