商户开放接口API文档

文档编号 Document number	GSWYIT-OPEN-API-01
页数 Pages		修改状态 Modification Status		生效日期 Effective Date
拟制 Drafted		审核 Reviewed		审批 Approved

版本号	修改标识	修改原因/内容	修改人	审核人	修改时间
V1.0	新建 New	创建原始文档 Create Original Document	黄旭 Huang Xu	王显泽 Wang Xianze	2024-12-08 Dec 8^th.,2024
V2.0	修改 Update	修改文档 Update Document	赵春阳 Zhao Chunyang	王显泽 Wang Xianze	2026-02-23 Feb 23^th.,2026
V3.0	修改 Update	增加获取配置说明 Update Document	赵春阳 Zhao Chunyang	王显泽 Wang Xianze	2026-09-23 Sept. 23^th.,2026

名称 Name	类型 Type	是否必须 Required or not	备注 Remarks
key	String	是 Yes	key
key-md5	String	是 Yes	MD5(key + secret+ timestamp)，key可在管理后台生成
timestamp	String	是 Yes	东八区当前时间戳 Timestamp of the Eastern 8th Time Zone (In milliseconds,Example:17527 31459238)

attribute	type	required
`code`	String	required
`msg`	String	required
`data`	Object	required

code	notes
`200`	success
`400`	failed

名称 Name	类型 Type	是否必须 Required or not	默认值 Default Value	备注 Remarks
activeName	String	Y		活动名称 activity name
startTime	String	Y		活动开始时间（yyyy-MM-dd HH:mm:ss） Eastern 8th Time Zone activity start time,
deviceTypeId	Long	Y		设备机型id
deviceIds	List	N		机型下部分设备集合,不传则为所有机型
endTime	String	Y		活动结束时间(yyyy-MM-dd HH:mm:ss) Eastern 8th Time Zone activity end time
exchangeType	Integer	Y		兑换形式（1-单一商品 2-任意商品） exchange type (1-single product 2-any product)
qty	Integer	N		兑换数量（仅限任意商品兑换）exchange quantity (only for any product)
deviceTypeId	String	Y		设备机型id
goodsItemDtos	List	Y		单一商品时必填 required for single product
	-- qty	Integer	N
	-- goodsId	String	Y
notifyUrl	String	N		回调地址(API1.4.1) callback address(API1.4.1)

名称 Name	类型 Type	是否必须 Required or not	默认值 Default Value	备注 Remarks
code	integer	是 Yes
message	String	是 Yes
data	Object	是 Yes		兑换码 Exchange code
	- activeInfo	Object	是 Yes
	-- id	String	是 Yes
	-- activeNo	String	是 Yes
	-- activeName	String	是 Yes
	- exchangeCodes	List	是 Yes

名称 Name	类型 Type	是否必须 Required or not	默认值 Default Value	备注 Remarks
activeName	String	Y		活动名称 activity name
startTime	String	Y		活动开始时间（yyyy-MM-dd HH:mm:ss） Eastern 8th Time Zone activity start time
deviceTypeId	Long	Y		设备机型id
deviceIds	List	N		机型下部分设备集合,不传则为所有机型
endTime	String	Y		活动结束时间(yyyy-MM-dd HH:mm:ss) Eastern 8th Time Zone activity end time
exchangeType	Integer	Y		兑换形式（1-单一商品 2-任意商品） exchange type (1-single product 2-any product)
qty	Integer	N		兑换数量（仅限任意商品兑换）exchange quantity (only for any product)
deviceTypeId	String	Y		设备机型id
goodsItemDtos	List	Y		单一商品时必填 required for single product
	-- qty	Integer	N
	-- goodsId	String	Y
notifyUrl	String	N		回调地址(API1.4.1) callback address(API1.4.1)

名称 Name	类型 Type	是否必须 Required or not	备注 Remarks
code	integer	是 Yes
message	String	是 Yes
data	List	是 Yes	兑换码 Exchange code

名称 Name	类型 Type	是否必须 Required or not	默认值 Default Value	备注 Remarks
activeNo	String	Y		活动 no activity No
status	Interger	Y		状态:0:暂停,2.启用,3:结束temporarily disabled:0,start to enable :2,pause to disable:3

名称 Name	类型 Type	是否必须 Required or not	备注 Remarks
code	integer	是 Yes
message	String	是 Yes
data	Boolean	是 Yes	兑换码 Exchange code

名称 Name	类型 Type	是否必须 Required or not	备注 Remarks
deviceId	String	是 Yes	设备id device ID
code	String	是 Yes	兑换码 Exchange code
goodsId	String	是 Yes	商品id goods ID
status	int	是 Yes	1. 制作中 2-已完成 0-失败） (1-in progress 2-completed 0-failed))
orderNo	String	是 Yes	订单号 order No.

名称 Name	类型 Type	是否必须 Required or not
code	integer	是 Yes
message	String	是 Yes
data	boolean	是 Yes

名称 Name	类型 Type	是否必须 Required or not	备注 Remarks
current	Integer	是 Yes	当前页 current page
size	Integer	是 Yes	每页数量 number per page
name	String	否 No	机型名称 model name

名称 Name	类型 Type	是否必须 Required or not	默认值 Default Value
code	integer	是 Yes
message	String	是 Yes
data		是 Yes
	--pages	Integer	是 Yes
	--size	Integer	是 Yes
	--total	Integer	是 Yes
	--total	Integer	是 Yes
	--records	List
	--id	String	是 Yes
	--name	String	是 Yes
	--protocol	String	是 Yes
	--series	String	是 Yes

名称 Name	类型 Type	是否必须 Required or not	备注 Remarks
current	Integer	是 Yes	当前页 current page
size	Integer	是 Yes	每页数量 number per page
deviceExtNo	String	否 No	设备编号 device number
name	String	否 No	设备名称 device name
deviceTypeName	String	否 No	机型编号 model number
status	int	否 No	设备状态（1-在线 2-离线） device status (1-online 2-offline)
longitude	BigDecimal	否 No	经度（根据经纬度可以返回当前设备距离）并且按距离排序 longitude (the current device distance can be returned based on longitude and latitude) and sorted by distance
latitude	BigDecimal	否 No	纬度（根据经纬度可以返回当前设备距离），并且按距离排序 latitude (the current device distance can be returned based on longitude and latitude) and sorted by distance

名称 Name	类型 Type	是否必须 Required or not	默认值 Default Value
code	integer	是 Yes
message	String	是 Yes
data		是 Yes
	--pages	Integer	是 Yes
	--size	Integer	是 Yes
	--total	Integer	是 Yes
	--total	Integer	是 Yes
	--records	List	是 Yes
	--id	String	是 Yes
	--deviceExtNo	String	是 Yes
	--deviceTypeId	String	是 Yes
	--name	String	是 Yes
	--distance	Long	否 No
	--merchantId	String	否 No
	--merchantName	String	否 No
	--status	Integer	是 Yes
	--deviceRunStatus	String	是 Yes
	--scarceStatus	String	是 Yes
	--exceptionRemark	String	是 Yes
	--scarceRemark	Long	否 No

名称 Name	类型 Type	是否必须 Required or not	默认值 Default Value	备注 Remarks
deviceId	String	是 Yes		设备id device ID

名称 Name	类型 Type	是否必须 Required or not	默认值 Required or not
code	integer	是 Yes
message	String	是 Yes
data		是 Yes
	--id	String	是 Yes
	--deviceExtNo	String	是 Yes
	--deviceTypeId	String	是 Yes
	--name	String	是 Yes
	--deviceNo	String	是 Yes
	--devicePwd	String	是 Yes
	--merchantId	String	是 Yes
	--merchantName	String	否No
	--status	Integer	是 Yes
	--deviceRunStatus	String	是 Yes
	--scarceStatus	String	是 Yes
	--exceptionRemark	String	是 Yes
	--scarceRemark	Long	否No

名称 Name	类型 Type	是否必须 Required or not	备注 Remarks
current	Integer	是 Yes	当前页 current page
size	Integer	是 Yes	每页数量 number per page
deviceTypeName	String	否 No	机型名称 model name
deviceTypeId	String	否 No	机型 ID model Id
no	String	否 No	商品编号 goods number
name	String	否 No	商品名称 goods name

名称 Name	类型 Type	是否必须 Required or not	默认值 Default Value
code	integer	是 Yes
message	String	是 Yes
data		是 Yes
	--pages	Integer	是 Yes
	--size	Integer	是 Yes
	--total	Integer	是 Yes
	--current	Integer	是 Yes
	--records	List	是 Yes
	--deviceTypeName	String	是 Yes
	--createUserName	String	是 Yes
	--id	String	是 Yes
	--deviceTypeId	String	是 Yes
	--no	String	是 Yes
	--price	BigDecimal	是 Yes
	--attachList	List	是 Yes
	--goodsId	String	是 Yes
	--fileName	String	是 Yes
	--path	String	是 Yes
	--fullPath	String	是 Yes
	--templateFileType	Integer	是 Yes

名称 Name	类型 Type	是否必须 Required or not	默认值 Default Value	备注 Remarks
id	String	是 Yes		商品id goods ID

名称 Name	类型 Type	是否必须 Required or not	默认值 Default Value
code	integer	是 Yes
message	String	是 Yes
data		是 Yes
	--id	String	是 Yes
	--name	String	是 Yes
	--price	BigDecimal	是 Yes
	--sort	String	是 Yes
	--spec	String	否 No
	--attachList	List	是 Yes
	--goodsId	String	是 Yes
	--fileName	String	是 Yes
	--path	String	是 Yes
	--fullPath	String	是 Yes
	--templateFileType	Integer	是 Yes

名称 Name	类型 Type	是否必须 Required or not	默认值 Default Value	备注 Remarks
id	String	是 Yes		商品id goods ID
name	String	是 Yes		商品名称 goods name
price	Bigdecimal	否 No		单价 unit price
sort	int	否 No		排序 sort
spec	String	否 No		商品规格 goods specifications
deviceTypeId	String	是 Yes		机型id device ID
	--attachList	List	否 No
	--goodsId	String	否 No
	--fileName	String	否 No
	--path	String	否 No
	--fullPath	String	否 No
	--templateFileType	Integer	否 No

名称 Name	类型 Type	是否必须 Required or not
code	integer	是 Yes
message	String	是 Yes
success	Boolean	是 Yes
data	Boolean	是 Yes

名称 Name	类型 Type	是否必须 Required or not	默认值 Default Value	备注 Remarks
name	String	是 Yes		商品名称 goods name
price	Bigdecimal	是 Yes		单价 unit price
sort	int	否 No		排序 sort
spec	String	否 No		商品规格 goods specifications
deviceTypeId	String	是 Yes		机型id device ID
	--attachList	List	是 Yes
	--fileName	String	是 Yes
	--path	String	否 No
	--fullPath	String	是 Yes
	--templateFileType	Integer	是 Yes

名称 Name	类型 Type	是否必须 Required or not
code	integer	是 Yes
message	String	是 Yes
success	Boolean	是 Yes
data	String	是 Yes

名称 Name	类型 Type	是否必须 Required or not	备注 Remarks
current	Integer	是 Yes	当前页 current page
size	Integer	是 Yes	每页数量 number of pages
deviceIds	List	否 No	设备id device ID

名称 Name	类型 Type	是否必须 Required or not	默认值 Default Value
code	integer	是 Yes
message	String	是 Yes
data		是 Yes
	--pages	Integer	是 Yes
	--size	Integer	是 Yes
	--total	Integer	是 Yes
	--current	Integer	是 Yes
	--records	List	是 Yes
	--deviceTypeName	String	是 Yes
	--createUserName	String	是 Yes
	--id	String	是 Yes
	--deviceTypeId	String	是 Yes
	--no	String	是 Yes
	--price	BigDecimal	是 Yes
	--name	String	是 Yes

名称 Name	类型 Type	是否必须 Required or not	备注 Remarks
current	Integer	是 Yes	当前页 current page
size	Integer	是 Yes	每页数量 page quantity
deviceIds	List	否 No	设备id device ID

名称 Name	类型 Type	是否必须 Required or not	默认值 Default Value
code	integer	是 Yes
message	String	是 Yes
data		是 Yes
	--pages	Integer	是 Yes
	--size	Integer	是 Yes
	--total	Integer	是 Yes
	--current	Integer	是 Yes
	--records	List	是 Yes
	--deviceTypeName	String	是 Yes
	--createUserName	String	是 Yes
	--id	String	是 Yes
	--deviceTypeId	String	是 Yes
	--no	String	是 Yes
	--price	BigDecimal	是 Yes
	--attachList	List	是 Yes
	--goodsId	String	是 Yes
	--fileName	String	是 Yes
	--path	String	是 Yes
	--fullPath	String	是 Yes
	--templateFileType	Integer	是 Yes

名称 Name	类型 Type	是否必须 Required or not	默认值 Default Value	备注 Remarks
deviceId	String	是 Yes		设备id device ID

名称 Name	类型 Type	是否必须 Required or not	默认值 Default Value
code	integer	是 Yes
message	String	是 Yes
data	List	是 Yes
	--deviceTypeName	String	是 Yes
	--createUserName	String	是 Yes
	--id	String	是 Yes
	--deviceTypeId	String	是 Yes
	--no	String	是 Yes
	--price	BigDecimal	是 Yes
	--soldOut	Integer	是 Yes
	--attachList	List	是 Yes
	--goodsId	String	是 Yes
	--fileName	String	是 Yes
	--path	String	是 Yes
	--fullPath	String	是 Yes
	--templateFileType	Integer	是 Yes

名称 Name	类型 Type	是否必须 Required or not	默认值 Default Value	备注 Remarks
deviceId	String	是 Yes		设备id device ID

名称 Name	类型 Type	是否必须 Required or not	默认值 Default Value	备注 Remarks
code	integer	是 Yes
message	String	是 Yes
data	List	是 Yes
	--id	String	是 Yes
	--materialId	String	是 Yes
	--no	String	是 Yes
	--rawType	String	是 Yes
	--name	String	是 Yes
	--capacity	Bigdecimal	是 Yes
residueQty	Bigdecimal	是 Yes		剩余容量 Remaining Capacity
position	String	是 Yes		原料位置 Material Position
unit	String	是 Yes		单位 Material Unit
expendRate	Bigdecimal	是 Yes		消耗速率 Remaining Capacity
warnCapacity	Bigdecimal	是 Yes		告警容量 Warn Capacity
stockVerification	Integer	是 Yes		是否参与库存校验 Whether to verify the inventory
stockConsumption	Integer	是 Yes		是否参与库存消耗 Whether inventory is consumed
isUsed	Integer	是 Yes		是否在使用 Whether inventory is used

名称 Name	类型 Type	是否必须 Required or not	默认值 Default Value	备注 Remarks
	--id	String	是 Yes
	--replenishQt	BigDecimal	是 Yes

名称 Name	类型 Type	是否必须 Required or not
code	integer	是 Yes
message	String	是 Yes
data	Boolean	是 Yes

名称 Name	类型 Type	是否必须 Required or not	默认值 Default Value	备注 Remarks
deviceId	String	是 Yes		设备id Device Id
goodsItems	List	是 Yes		商品信息项 Goods items
	-- goodsId	String	是 Yes
	-- devicePrice	BigDecimal	否 No

名称 Name	类型 Type	是否必须 Required or not
code	integer	是 Yes
message	String	是 Yes
data	Boolean	是 Yes

名称 Name	类型 Type	是否必须 Required or not	默认值 Default Value	备注 Remarks
	--deviceId	String	是 Yes
	--goodsId	String	是 Yes

名称 Name	类型 Type	是否必须 Required or not
code	integer	是 Yes
message	String	是 Yes
data	Boolean	是 Yes

名称 Name	类型 Type	是否必须 Required or not	备注 Remarks
current	Integer	是 Yes	当前页 current page
size	Integer	是 Yes	每页数量 quantity per page
orderNo	String	否 No	订单编号 Order No
startDate	String	是 Yes	订单查询开始时间 The start date of order inquiry (yyyy-MM-dd)
endDate	String	是 Yes	订单查询结束时间 The end date of order inquiry (yyyy-MM-dd)

名称 Name	类型 Type	是否必须 Required or not	默认值 Default Value
code	integer	是 Yes
message	String	是 Yes
data		是 Yes
	--pages	Integer	是 Yes
	--size	Integer	是 Yes
	--total	Integer	是 Yes
	--total	Integer	是 Yes
	--records	List	是 Yes
	--orderNo	String	是 Yes
	--deviceNo	String	是 Yes
	--deviceName	String	是 Yes
	--goodsName	String	是 Yes
	--merchantName	String	是 Yes
	--payAmt	Bigdecimal	是 Yes
	--payWay	int	是 Yes
	--status	int	是 Yes
	--outStockStatus	int	是 Yes
	--refundStatus	int	否 No

属性	属性值	说明
outStockStatus	0	取消 Canceled
	1	未出 Pending
	2	已出货 Delivered
status	0	取消 Canceled
	1	制作中 Making
	2	制作完成 Complete
	6	超时 Time out
	7	未制作 Not Product
refundStatus	1	已退款 Refunded
	2	退款失败 Refunded Failed

名称 Name	类型 Type	是否必须 Required or not	默认值 Default Value	备注 Remarks
code	String	是 Yes		授权码 authorization Code
deviceId	String	是 Yes		设备id device ID

名称 Name	类型 Type	是否必须 Required or not	默认值 Default Value
code	integer	是 Yes
message	String	是 Yes
data		是 Yes
	--orderNo	String	是 Yes
	--deviceNo	String	是 Yes
	--deviceName	String	是 Yes
	--goodsName	String	是 Yes
	--merchantName	String	是 Yes
	--payAmt	Bigdecimal	是 Yes
	--payWay	int	是 Yes
	--status	int	是 Yes
	--outStockStatus	int	是 Yes
	--refundStatus	int	是 Yes

名称 Name	类型 Type	是否必须 Required or not	备注 Remarks
code	String	是 Yes	兑换码 Exchange Code
deviceId	String	是 Yes	设备id device ID
goodsId	String	是 Yes	商品id Goods ID
deviceNo	String	是 Yes	设备唯一码 device no

名称 Name	类型 Type	是否必须 Required or not	默认值 Default Value
code	integer	是 Yes
message	String	是 Yes
data		是 Yes	true

名称 Name	类型 Type	是否必须 Required or not	备注 Remarks
deviceId	String	是 Yes	设备id device ID
deviceNo	String	是 Yes	设备唯一码 device no
deviceRunStatus	String	是 Yes	设备状态(1:Normal,2:Exception) Device Run Stataus
exceptionRemark	String	是 Yes	异常信息 Device Run exception infomation
timestamp	Long	是 Yes	告警时间戳 Time Stamp of exception Time

名称 Name	类型 Type	是否必须 Required or not	默认值 Default Value
code	integer	是 Yes
message	String	是 Yes
data		是 Yes	true

¶ 1.api配置说明 API Docs Configuration Instructions

¶ 1.1.接口协议说明

¶ 1.1.1 请求公共参数 Request

¶ 1.1.2.请求返回体说明 Public request return body

¶ 1.2.获取接口加密配置

¶ 2.接口设计 API Design

¶ 2.1. 营销管理

¶ 2.1.1. 创建兑换活动v2

¶ 2.1.2. 创建兑换活动

¶ 2.1.3. 修改兑换活动状态

¶ 2.1.4. 兑换码兑换回调

¶ 2.2. 设备管理 Machine Management

¶ 2.2.1. 获取机型列表 Get The Type List

¶ 2.2.2. 获取设备列表 Get Device List

¶ 2.2.3. 获取设备详情 Get Device Details

¶ 2.3. 商品管理 Goods Management

¶ 2.3.1. 获取商品列表 Get product list

¶ 2.3.2. 获取商品详情 Get Product Details

¶ 2.3.3. 编辑商品 Edit Product

¶ 2.3.4. 新增商品 Add New Goods

¶ 2.3.5. 根据设备id查询设备已上架商品

¶ 2.3.6. 根据设备id查询设备已上架商品明细

¶ 2.3.7. 根据设备id查询设备商品明细不分页(包含是否售罄标识)

¶ 2.3.8. 根据设备id查询设备物料信息

¶ 2.3.9. 根据设备id补充设备原料

¶ 2.3.10. 设备上架商品

¶ 2.3.11. 设备下架商品

¶ 2.4. 订单管理 Order Management

¶ 2.4.1. 获取订单列表 Get Order List

¶ 2.4.2. 获取当前兑换码对应的订单

¶ 2.4.3 使用兑换码立即制饮

¶ 2.5. 数据推送webhook Data Push Api webhook

¶ 2.5.1 设备告警信息推送 Device Alarm Notification Push

¶ 2.5.2 设备物料告警信息推送 Device Material Alarm Information Push

¶ 2.5.3 订单推送 Transaction data push

¶ 1.api配置说明 API Docs Configuration Instructions

¶ 1.1.接口协议说明

¶ **1.1.1 请求公共参数 Request **

¶ 1.1.2.请求返回体说明 Public request return body

¶ 1.2.获取接口加密配置

¶ 2.接口设计 API Design

¶ 2.1. 营销管理

¶ 2.1.1. 创建兑换活动v2

¶ 2.1.2. 创建兑换活动

¶ 2.1.3. 修改兑换活动状态

¶ 2.1.4. 兑换码兑换回调

¶ 2.2. 设备管理 Machine Management

¶ 2.2.1. 获取机型列表 Get The Type List

¶ 2.2.2. 获取设备列表 Get Device List

¶ 2.2.3. 获取设备详情 Get Device Details

¶ 2.3. 商品管理 Goods Management

¶ 2.3.1. 获取商品列表 Get product list

¶ 2.3.2. 获取商品详情 Get Product Details

¶ 2.3.3. 编辑商品 Edit Product

¶ 2.3.4. 新增商品 Add New Goods

¶ 2.3.5. 根据设备id查询设备已上架商品

¶ 2.3.6. 根据设备id查询设备已上架商品明细

¶ 2.3.7. 根据设备id查询设备商品明细不分页(包含是否售罄标识)

¶ 2.3.8. 根据设备id查询设备物料信息

¶ 2.3.9. 根据设备id补充设备原料

¶ 2.3.10. 设备上架商品

¶ 2.3.11. 设备下架商品

¶ 2.4. 订单管理 Order Management

¶ 2.4.1. 获取订单列表 Get Order List

¶ 2.4.2. 获取当前兑换码对应的订单

¶ 2.4.3 使用兑换码立即制饮

¶ 2.5. 数据推送webhook Data Push Api webhook

¶ 2.5.1 设备告警信息推送 Device Alarm Notification Push

¶ 2.5.2 设备物料告警信息推送 Device Material Alarm Information Push

¶ 2.5.3 订单推送 Transaction data push

¶ 1.1.1 请求公共参数 Request