Open API 接口+MCP 服务操作指南

一、功能介绍

UpSeller 现已支持开放 API 与 MCP（AI 工具连接）功能

该功能主要适用于需要进行系统对接，或希望通过 AI 工具访问 UpSeller 数据的用户

您可以通过开放 API 将 UpSeller 数据接入自有系统，也可以通过 MCP 连接 Claude、Codex、ChatGPT、Cursor 等 AI 工具，实现 UpSeller 数据查询与智能化管理

二、适用范围

该功能面向以下用户开放：


	
专业版及以上套餐用户 
	
组合套餐用户 


注意：该功能无需额外付费；

仅主账号可进入【开放平台】，并申请 API Token，子账号暂不支持查看入口或申请 Token。

三、开放能力

目前，UpSeller 开放 API 与 MCP 支持以下数据查询能力：

1. 查询仓库列表


	
API 接口： getWarehouseList/v1
	
MCP 工具： get_warehouse_list_by_puid


用于查询当前账号下的所有仓库列表

 

2. 查询 SKU 库存详情


	
API 接口： pageWarehouseSku/v1
	
MCP 工具： page_warehouse_sku_inventory_list


用于查询指定仓库下全部或指定 SKU 的库存详情

四、请求限制

注意：请求限制按照接口维度计算

不同套餐对应的请求限制如下：


	
专业版


API 请求限制：100 次/分钟 

MCP 请求限制：60 次/分钟 


	
企业版


API 请求限制：200 次/分钟 

MCP 请求限制：120 次/分钟 


	
企业版 Plus


API 请求限制：500 次/分钟 

MCP 请求限制：300 次/分钟

五、获取授权凭证

在开始配置 API 或 MCP 前，请先进入 UpSeller 后台获取专属授权信息，包括：


	
用户 ID（User ID） 
	
API Token 
	
MCP Token


第一步：开启功能

1.  登录 UpSeller 后台，在左侧菜单栏点击【开放平台】→【API / MCP】

2.  首次使用时，在右侧页面点击蓝色【生成】按钮

 



 

第二步：复制授权凭证

生成成功后，系统会展示以下授权信息，请妥善保存：


	
用户 ID (User ID)：您的商户唯一识别码
	
API Token：用于传统 API 接口调用的鉴权密钥
	
MCP Token：用于连接大模型或 AI 开发工具的鉴权密钥




注意：Token 属于敏感信息，请勿分享给第三方。如发现 Token 存在安全风险，可在同一页面重新生成或删除 Token

六、API 接口说明

1. 库存查询接口概述

该接口提供仓库管理和库存查询能力，支持：


	
查询当前账号下的仓库列表
	
分页查询仓库库存信息


基础信息


	
协议： HTTP/HTTPS 
	
请求方式： POST 
	
数据格式： JSON 
	
认证方式： API 密钥认证（通过请求头传递）


通用请求头







通用响应格式



 



通用响应字段说明







通用错误码





七、接口详情

1. 查询仓库列表

接口说明

查询当前账号下的仓库列表

 

请求信息

请求地址：https://openapi.upseller.com/erp/inventory/getWarehouseList/v1 

请求方式：POST

内容类型：application/json 

 

请求头

请参考【通用请求头】

 

请求体

 



请求参数说明

warehouseType


	
类型： String 
	
是否必填： 否 
	
最大长度： 32 
	
说明： ALL 全部仓库，不限制仓库类型，SELF_OPERATED 自营仓【自建仓】，THIRD_PARTY 三方仓


请求示例



 



响应字段说明







响应示例

 



2. 分页查询仓库 SKU 库存清单



请求信息

请求地址：https://openapi.upseller.com/erp/inventory/pageWarehouseSku/v1 

请求方式：POST

内容类型：application/json 

 

请求头

请参考【通用请求头】

 

请求体







请求示例







请求体字段说明







响应数据字段说明







响应示例

 



常见错误处理

1. 认证失败：检查请求头是否正确设置

2. 参数错误：确认请求参数格式和必填项

3. 服务器错误：联系技术支持并提供requestId以便追踪问题

 

注意事项

1. 所有时间字段均采用ISO 8601格式（如：2023-01-01T12:00:00Z）

2. 建议对请求进行适当的重试机制，特别是网络不稳定的情况下

3. 对于分页查询，注意合理设置pageNo和pageSize以避免性能问题

八、MCP 服务文档

服务信息

Transport =streamable-http

url=https://openapi.upseller.com/mcp



通用请求头



提供的工具方法

1. get_warehouse_list_by_puid



功能: 查询当前认证账号下的仓库信息列表

工具名称: get_warehouse_list_by_puid

参数:warehouseType (String): 仓库类型；可选值: ALL, SELF_OPERATED, THIRD_PARTY

描述: 获取属于当前认证账户的仓库列表信息。支持多语言（中文、英文、葡萄牙文、西班牙文）

触发词:


	
中文: 查看仓库、获取仓库、查询仓库、列出仓库、我的仓库、仓库列表、仓库信息
	
英文: view warehouses, get warehouses, list warehouses, my warehouses, warehouse list
	
葡萄牙文: ver armazéns, listar armazéns, meus armazéns, lista de armazéns
	
西班牙文: ver almacenes, listar almacenes, mis almacenes, lista de almacenes


返回值: McpResult>

用途: 当用户请求查看、获取、查询或列出账户仓库时调用此工具。不用于查询库存SKU



2. page_warehouse_sku_inventory_list



功能: 查询当前认证账号指定仓库下的库存 SKU 清单

工具名称: page_warehouse_sku_inventory_list

参数:

PageWarehouseSkuQuery (对象):


	
warehouseIdList - 仓库ID列表（1到100个）
	
skuList - 可选的SKU集合
	
pageNo - 分页游标
	
pageSize - 每页大小（1到100，默认20）
	
updateTime - 更新时间


描述: 查询指定仓库的分页SKU库存清单。支持多语言（中文、英文、葡萄牙文、西班牙文）

触发词:


	
中文: 查看库存、查询库存、获取库存、列出库存、SKU库存、仓库库存、库存列表
	
英文: view inventory, query inventory, get inventory, list inventory, SKU stock, warehouse stock
	
葡萄牙文: ver inventário, consultar estoque, obter estoque, listar estoque, estoque SKU
	
西班牙文: ver inventario, consultar inventario, obtener inventario, listar inventario, stock SKU


返回值: McpResult

用途: 当用户请求查看、查询、获取或列出仓库SKU库存时调用此工具。不用于获取仓库列表本身



如果您需要了解更详细的 API 接口参数、请求示例及 MCP 配置方法，请查看：UpSeller Open API & MCP 服务详细开发文档