REXPOS轻自助对接说明

更新时间：2020/05/15 访问次数：2760

变更：文档版本摘要

日期	作者	版本	描述
2019	终端部	1.0.0	初始版本
2020/2/27	终端部	2.0.0	1、商品查询(querycommodity)的错误码增加108、109、110、111
			2、商品（Commodity）的saleType字段增加类型2、3
			3、增加取消合计（cancelsubtotal）接口
			4、小计(subtotal)和取消合计（cancelsubtotal）接口的extra字段类型由string调整为json。
2020/4/29	终端部	2.0.1	1、获取小票信息(getbillinfo)接口，增加字段merchantInfo：商家自定义信息
2020/5/09	终端部	2.0.2	1、日结功能（dailysettle）接口，增加字段dailySettleBill：日结小票协议
2020/5/15	终端部	2.0.3	1、小计（subtotal）接口，extra（Map类型）字段添加一个标志：calculateMode，用来区分是普通合计，还是营销合计。只有营销合计才会触发换购和赠品计算。

1、架构概要图

POS App端对接

交易主流程在ISV POS Server

同步商品数据（前置条件）

2、交互时序图

3、接口概述

3.1 接口协议说明

POS终端与POS服务中台使用HTTP POST进行通讯，数据以JSON（Java Script Object Notation）格式进行交互，字符编码方式采用 UTF-8。

各接口服务使用统一的IP和端口号。如：

http://isv-pos-server-ip:port/XXXX

或

https://isv-pos-server-ip:port/XXXX

注：XXXX接口名称，以"5、接口定义"部分各接口命名为准

3.2 数据安全性

采用https，使用SSL安全套接字层对网络传输中的传输层与应用层间进行加密，达到承载加密的效果，可保证数据的机密性。注：测试阶段可使用http。

3.3 数据可靠性

采用数字签名(RSA算法)，数据发送方负责加签名，数据接收方负责验证签名。

具体步骤:

数据交互双方，生成长度为1024的密钥对(公钥和私钥)，可自行生成，也可以使用支付宝工具生成。切记只能生成一次密钥。支付宝工具地址: https://docs.open.alipay.com/291/106097/。

密钥生成成功后，自己保存私钥，将公钥发给对方。

请求方需要对请求数据进行签名，并且对返回数据进行签名验证；响应方需要对请求数据进行签名验证，并且对返回数据进行签名。

密钥参数：

加密算法：RSA
密钥格式：PKCS8
密钥长度：1024

签名规则（服务端角度）:

加签

把http返回中的responsebody做Base64转码，生成转码字符串
使用自己的私钥对转码字符串进行签名，生成签名字符串
再把签名字符串进行Base64转码，生成最终的签名-sign
把sign放到http返回的header中，key为“X-Sign”

验签

把http请求中的requestbody做Base64转码，生成转码字符串
把http请求header中的签名（客户端加签时塞到“X-Sign”中的值）做Base64解码，生成解码字符串
使用客户端的公钥对前两步生成的数据进行验签

代码：

鉴于开发同学对加签/验签规则的理解和实现差异，总会造成联调的问题，现提供一套标准的加签和验签方法，代码由支付宝的签名SDK修改而来。详见附件：五道口加签和验签，实现语言是Java，下载地址：https://files.alicdn.com/tpsservice/ab8cf8c790b22fb2985a4a752b543171.zip。

?五道口加签验签.zip

举例（角度为客户端，只为说明问题）：

加签：调用商品查询接口（querycommodity）查询商品。

在http request中的请求参数为：httpRequestStr = {"barcode":"000013","tradeFlowNo":"HDFUQINGJIAYUAN212777201059190329151130315","cashierNum":"9999","posNum":"059"}

调用我们提供的加签方法进行加签：

String sign = SignUtils.rsaSign(httpRequestStr, signKey);

signKey为自己的私钥。sign就是加签后得到的签名数据。

这里假设 sign = bKrbD7CK3g914VxE4yBIXakUvgWpx1IwVPkbUZOkj7jCnVHU7mbnfBRvN1imXRDdB/vQm+TNHJeW2ej9q+YFEfzr53Mrm2HRFy7qn2JmXuYD0R5HjuDVcX4CyuUtgLt1satVmQxPKA6H2YeQmkcOiSsNaOU/Qh3uaFkmD94uFjc= 。

然后将sign插入到Http的header中：key为“X-Sign”，value为sign。

验签：商品查询接口（querycommodity）返回查到的商品数据。

在http response中的返回数据为：httpResponseStr = {"traceId":"45b30fbd-b259-4549-a3d0-a46370fa429c","retCode":"0","retMsg":"接口调用成功","data":{"totalFee":1,"discountFee":0,"actualFee":1,"items":[{"rowNo":"351fac0f-9322-4ff1-87d0-d21043b444a9","barcode":"000013","isvSkuCode":"000013","name":"货物","picUrl":null,"price":1,"promotionPrice":1,"unit":"个","quantity":1,"weight":0,"isWeight":false,"sellStatus":true,"discountFee":0,"extra":null,"totalFee":1,"actualFee":1}]}}

在http的header中服务端的加签数据 X-SIgn 为 sign = V67kYGO467voeTjCkK3FX5kKBZP1SjMtKxySBjwEvLWY/HxPd11eLd8tYUiruOevFBywaapHZx8QRl4kUo8rvpzjPNRKAAhnVS+qD/+IA9kvV4lSE47nqWYXsYdz6LvZO1E613ngddPM2YEsJwnc9Z9hWavMI4RWI+vUnB7qH2Q=

调用我们提供的验签方法：

boolean result = SignUtils.rsaCheck(httpResponseStr, sign, signKey);

signKey是服务端发给我们的公钥。result = true表示验签成功，否则验签失败。

4、通用接口参数

4.1 通用请求参数

通用header请求参数，每个http请求时，header都带这些参数。

参数	参数名称	类型	必须	参数说明
X-Sign	数字签名	String	Y	请求的数字签名，确保数据可靠性
X-MerchantCode	商家编码	String	Y
X-StoreCode	商家门店号	String	Y

通用Body请求参数，每个接口请求时都带这些参数。

参数	参数名称	类型	必须	参数说明
cashierNum	收银员号	String	N
posNum	收银机号	String	Y

4.2 通用返回参数

通用header返回参数，每个http响应时，header都带这些参数。

参数	参数名称	类型	必须	参数说明
X-Sign	数字签名	String	Y	请求的数字签名，确保数据可靠性

通用返回参数，每个接口返回时都带这些参数。

参数	参数名称	类型	参数说明
traceId	请求追踪ID	String
retCode	错误码	String	"0" - 请求成功；非"0" - 请求失败；
retMsg	错误码描述	String
data	返回数据对象	Object

5、接口定义

5.1 获取基本设置(getbaseinfo)

接口说明

返回系统参数，支付渠道、预置购物袋，等，为对应门店生成基础参数配置。

注：开机后只需启动一次。

请求参数说明

参数	参数名称	类型	必须	参数说明
posNum	收银机号	String	Y	参数用途，示ISV实现而定，
deviceSN	设备序列号	String	N	参数用途，示ISV实现而定，一般情况不需要用
shopId	门店ID	String	Y	参数用途，示ISV实现而定，
cashierNum	收银员号	String	N	参数用途，示ISV实现而定，一般情况不需要用

响应结果说明

参数			参数名称	类型	必须	参数说明
data			JSON Object
	paymentChannels		支付渠道列表	JSON Array	Y
		code	支付渠道代码	String	Y
		id	支付渠道ID	String	Y	"01" - 支付宝 "02" - 微信 "03" - 商家储值卡 "04" - 银联云闪付
		name	支付渠道名称	String	Y
	facePayParams		人脸付相关参数	JSON Object	Y
		merchantId	支付宝 PID(商户) --zfb_pid	String	Y
		partnerId	支付宝 PID(ISV) --zfb_sub_pid	String	Y
		appId	支付宝 APPID(ISV/商户)zfb_appid	String	Y
	shoppingBags		购物袋列表		N
		barcode	购物袋条码	String	N
		type	购物袋类型	String	N	"L" - 大号 "M" - 中号 "S" - 小号
		price	购物袋售价	long	N	单位：分
	sysParams		商家系统设置	JSON Object	N	备用

5.2 会员查询(querymember)

接口说明

会员查询接口，可以查询商家会员，和淘宝会员。在顾客录入会员（手机号／商家会员卡号）时，查询商家会员，POS服务中台将会员加入购物车。

在顾客扫付款码时，查询淘宝会员，返回结果POS端通过创单接口aliUserId传入，用于订单回流定向到指定淘宝用户。

请求参数说明

参数	参数名称	类型	必须	参数说明
tradeFlowNo	交易流水号	String	Y	交易流水号，可用作购物车ID，商户纬度唯一。生成规则：商户名称＋淘鲜达渠道店ID＋收银机号＋时间戳最大长度：64
qrCode	会员码	String	Y	扫入的二维码／条码
userType	会员类型	String	Y	默认传 ISV ISV：商家线下会员 TAOBAO：淘宝会员
sourceOfCode	会员码来源	String	N	PHONE：手机号 QR_CODE：会员卡号、条形码、二维码 MAGNETIC_TRACK：磁道（暂无这种来源）
extra	额外信息	String	N	备用

响应结果说明

参数		参数名称	类型	参数说明
data		JSON Object
	userId	会员ID	String
	userType	会员类型	String	默认传 ISV ISV：商家线下会员 TAOBAO：淘宝会员
	userNick	会员昵称	String
	cardNum	会员卡号	String
	phoneNum	会员手机号	String
	score	会员积分	String
	level	会员等级	String
	extra	额外信息	String	备用

5.3 商品查询(querycommodity)

接口说明

商品查询接口，每次传入商品条码进行商品查询，POS服务中台返回当前购物车的全商品列表数据。

合计金额带优惠计算后金额。购物车标准，请查看"7、购物车标准"。

错误码

当查询的商品不可售时，接口直接返回错误，不把不可售的商品加进购物车，通过错误码区分不可售类型。

错误码	类型说明	备注	App上的提示文案
101	商品不可在自助POS上售卖，但可在人工POS上售卖	retCode = "101"	该商品不支持自助购买
102	商品过了保质期不允许售卖	retCode = "102"	商品已过期，请勿购买
103	商品库存不够	retCode = "103"	系统库存不足，无法购买
104	商品售价为0	retCode = "104"	商品价格异常，无法购买
105	商品是加工原料不允许销售	retCode = "105"	很抱歉，加工原料不允许销售
106	商品促销处理错误	retCode = "106"	系统异常，商品添加失败
107	erp商品状态为停售，但是商品未来得及下架	retCode = "107"	很抱歉，该商品已停售
108	先录入了折扣码，后录入商品。注:折扣码必须跟在商品后面录入。	retCode = "108"	请先录入商品，再录入折扣码
109	服务端校验折扣码不通过	retCode = "109"	折扣码错误
110	折扣码未能关联到商品	retCode = "110"	折扣码未能关联到商品
111	商家自定义返回的错误提示	retCode = "111"	直接读取接口返回的错误信息

请求参数说明

参数	参数名称	类型	必须	参数说明
tradeFlowNo	交易流水号	String	Y	交易流水号／购物车ID
barcode	商品条码	String	Y	扫描码
extra	额外信息	String	N	备用

响应结果说明

参数		参数名称	类型	参数说明
data		JSON Object
	totalFee	合计总金额	long	单位：分
	discountFee	折扣总金额	long	单位：分
	actualFee	折扣后实际总金额	long	单位：分
	items	商品列表	JSON Array	List<Commodity>

5.4 商品数量更新(updatecommodity)

接口说明

商品数量编辑更新，按行号更新当前购物车商品数据，POS服务中台返回当前购物车的全商品列表数据。

合计金额带优惠计算后金额。

请求参数说明

参数	参数名称	类型	必须	参数说明
tradeFlowNo	交易流水号	String	Y	交易流水号／购物车ID
rowNo	商品行号	String	Y	商品行标识
quantity	商品数量	String	Y	商品数量。当商品数量为 0 时，删除该商品行。

响应结果说明

参数		参数名称	类型	参数说明
data		JSON Object
	totalFee	合计总金额	long	单位：分
	discountFee	折扣总金额	long	单位：分
	actualFee	折扣后实际总金额	long	单位：分
	items	商品列表	JSON Array	List<Commodity>

5.5 删除商品(deletecommodity)

接口说明

删除商品，按行号删除购物车商品数据，POS服务中台返回当前购物车的全商品列表数据。

合计金额带优惠计算后金额。

请求参数说明

参数	参数名称	类型	必须	参数说明
tradeFlowNo	交易流水号	String	Y	交易流水号／购物车ID
rowNo	商品行号	String	Y	商品行标识

响应结果说明

参数		参数名称	类型	参数说明
data		JSON Object
	totalFee	合计总金额	long	单位：分
	discountFee	折扣总金额	long	单位：分
	actualFee	折扣后实际总金额	long	单位：分
	items	商品列表	JSON Array	List<Commodity>

5.6 小计(subtotal)

接口说明

商品数量编辑更新，按行号更新当前购物车商品数据，POS服务中台返回当前购物车的全商品列表数据。

合计金额带优惠计算后金额。

请求参数说明

参数	参数名称	类型	必须	参数说明
tradeFlowNo	交易流水号	String	Y	交易流水号／购物车ID
userId	会员ID	String	N
userType	会员类型	String	N
extra	额外信息	JSON	N	calculateMode，合计模式不传或空，默认表示普通合计; normal，普通合计; promotion，触发营销计算，只有营销合计才会触发换购和赠品计算。详细信息参考文档： https://hema.open.taobao.com/doc?docId=118931&docType=1

响应结果说明

参数		参数名称	类型	参数说明
data		JSON Object
	totalFee	合计总金额	long	单位：分
	discountFee	折扣总金额	long	单位：分
	actualFee	折扣后实际总金额	long	单位：分
	items	商品列表	JSON Array	List<Commodity>

5.7 创单(createorder)

接口说明

创建交易订单，POS服务中台保留最全的交易订单数据，包含支付完成，和支付未完成的订单。

请求参数说明

参数	参数名称	类型	必须	参数说明
tradeFlowNo	交易流水号	String	Y	交易流水号／购物车ID
aliMerchantCode	淘鲜达商户号	String	Y	用于订单回流。
aliStoreId	淘鲜达渠道店ID	String	Y	用于订单回流。
deviceId	设备ID	String	Y	设备唯一ID，用于订单回流透传
aliUserId	淘宝会员ID	String	N	用于订单回流。在创单前，做一次淘宝会员查询。
userId	商家会员ID	String	N	没有会员录入时，匿名创单
extra	额外信息	String	N	备用

响应结果说明

参数		参数名称	类型	参数说明
data		JSON Object
	totalFee	合计总金额	long	单位：分
	discountFee	折扣总金额	long	单位：分
	actualFee	订单应付金额	long	单位：分
	orderId	交易订单号	String	交易订单号
	timestamp	订单创建时间	String	格式 yyyyMMddHHmmss

5.8 获取人脸付信息(getzimid)

接口说明

获取人脸付需要的zimId和zimInitClientData。

请求参数说明

参数	参数名称	类型	必须	参数说明
metaInfo	人脸付初始化参数	String	Y	支付宝端上sdk生成参数

响应结果说明

参数		参数名称	类型	参数说明
data		JSON Object
	zimId	人脸认证标识	String
	zimInitClientData	人脸认参数	String

5.9 支付(pay)

接口说明

支付接口在POS服务中台的实现，需要负责支付结果的轮询，直至支付结果确定，同时，支付成功后，POS服务中台负责推进订单状态，和订单回流淘鲜达。

支付渠道支持

支付宝
微信
商家储值卡

支付说明

根据具体商家需求，定是否实现组合支付

错误码

当支付请求出现明确系统业务错误，支付终止时，返回明确错误码，POS端上透出支付失败，不进行支付结果轮询。支付系统内部的错误码和错误信息，体现到接口返回的subCode，和subMsg上。

错误码

支付异常

备注

PAY_BIZ_ERROR

支付系统业务错误，支付终止

retCode = "PAY_BIZ_ERROR"；

支付系统内部的错误码和错误信息，体现到接口返回的subCode，和subMsg上。

请求参数说明

参数	参数名称	类型	必须	参数说明
tradeFlowNo	交易流水号	String	N	交易流水号／购物车ID
requestId	幂等请求ID	String	Y	支付请求ID，每笔支付唯一。生成规则：淘鲜达渠道店ID＋收银机号＋时间戳最大长度：64
orderId	交易订单号	String	Y
payFee	支付金额	String	Y	单位：分
payCode	支付码(或卡信息)	String	Y
sourceOfCode	支付码来源	String	Y	ALIPAY：支付宝扫码付 ALIPAY_FACE：支付宝人脸付 TAOBAO：手淘扫码付 WECHAT:微信 MAGNETIC_CARD: 储值卡/磁条卡 IC_CARD: IC卡 UNIONPAY:银联云闪付
paymentChannelCode	付款渠道编码	String	Y	从支付渠道接口获取，如：有的商家，支付宝支付方式代码为"0304"
terminalId	终端编号	String	Y	支付宝支付加签机具编号
terminalParams	机具管控参数	String	Y	支付宝支付加签
extra	额外信息	String	N	备用

响应结果说明

参数	参数名称	类型	参数说明
subCode	支付系统内部业务异常编码	String	默认值 null; 当支付业务异常报错（retCode：PAY_BIZ_ERROR），返回ISV支付系统内部错误编码。
subMsg	支付系统内部业务异常信息	String	默认值 null; 当支付业务异常报错（retCode：PAY_BIZ_ERROR），返回ISV支付系统内部错误信息。
data	支付结果	PayDetail	JSON Object

5.10 支付结果查询(querypayresult)

接口说明

查询单笔支付动作的支付结果。

请求参数说明

参数	参数名称	类型	必须	参数说明
tradeFlowNo	交易流水号	String	N	交易流水号／购物车ID
orderId	交易订单号	String	Y	交易订单号
requestId	幂等请求ID	String	Y	端上支付请求号

响应结果说明

参数	参数名称	类型	参数说明
data	支付结果	PayDetail	JSON Object

5.11 撤销整单交易(cancelpay)

接口说明

撤销整单交易接口在POS服务中台的实现，需要撤销该笔订单的关联支付，同时，更新订单状态。

错误码

针对业务上不支持撤销交易的场景（如已经支付完成并落库ERP的订单不支持撤销），返回明确错误码，POS端上做相应的处理。

错误码	类型说明	备注	App上处理
5001	已经支付完成并落库ERP的订单不支持撤销	retCode = "5001"	端上接收到5001，则发起支付查询流程，根据支付查询结果做后续操作

请求参数说明

参数	参数名称	类型	必须	参数说明
orderId	交易订单号	String	Y
payRequestId	需被撤销的支付请求Id	String	N	混合支付场景必传

响应结果说明

参数		参数名称	类型	参数说明
data		JSON Object
	orderId	交易订单号	String
	status	取消交易状态	String	SUCCESS - 取消成功 FAIL - 取消失败
	timestamp	时间戳	String	格式 yyyyMMddHHmmss

5.12 获取小票信息(getbillinfo)

接口说明

获取任一笔订单的小票数据，用于当笔交易小票打印和后续的小票补打。小票返回数据中，需包含该笔订单是否已完全支付的标识。已被撤销的订单，不支持补打小票，小票信息接口通过错误码和错误信息返回。

补打小票其中一个关键目的是解决由于网络或其他原因导致顾客被扣款了，而POS端上未打印小票的场景，提供通过支付宝账单商家订单号查询补打小票功能。

需要支持：

通过创单返回的订单号查询小票信息（正常交易打印小票场景）；
通过支付宝账单上的商家订单号查询小票信息（扣款未出小票的补打小票场景）；
如查询订单在POS服务系统里已是支付完成状态，直接返回小票信息；
如查询订单在POS服务系统里是未支付状态，需要POS服务系统到支付宝进一步核验支付结果，如已支付，推进订单状态，并返回小票信息。

请求参数说明

参数

参数名称

类型

必须

参数说明

orderId

订单号

String

创单返回的交易订单号，或支付宝账单的商家订单号

isReprint

是否补打标识

boolean

true：补打

false：非补打

默认值：false

响应结果说明

参数			参数名称	类型	参数说明
data			JSON Object
	reprintCount		补打次数	int	小票补打次数
	receiptNum		小票号	String
	orderId		交易订单号	String
	isFullPaid		是否已全部付款	boolean
	totalFee		订单总金额（包含优惠金额）	long	单位：分
	discountFee		优惠金额	long	单位：分
	actualFee		应付总金额	long	单位：分 actualFee = totalFee - discountFee
	actualPaid		实付总金额	long	单位：分实付金额一般都等于应付金额
	currentOrderScore		当次交易积分	String
	items		商品列表	JSON Array	List<Commodity>
	isvStoreCode		商家门店号	String
	cashierNum		收银员号	String
	posNum		款台号	String
	member		会员信息	JSON Object
		cardNum	会员卡号	String
		phoneNum	会员手机号	String
		score	会员积分	String	包含当次交易的累计积分
	payList		付款明细	JSON Array
		code	付款方式编码	String
		name	付款方式名称	String
		account	付款账号	String
		amount	付款金额	long	单位：分
	invoiceUrl		电子发票地址	String	用于生成电子发票二维码
	payMsg		支付额外信息	String	可通过 '\n' 换行符，在小票上换行打印文案。
	merchantInfo		商家自定义信息	String	这是一个JSON格式的字符串，根据一套协议编码，可以让商家自定义内容。详细信息参考文档：https://hema.open.taobao.com/doc?docId=118904&docType=1
	extra		额外信息	String	商家营销，备注等文案。可通过 '\n' 换行符，在小票上换行打印文案。

5.13 预置商品批量获取接口(getpresetinfo)

接口说明

针对非标品，如关东煮、包子、烤肠等无码商品，提供批量获取接口，自助POS端透出按类目点餐购买页面。

注：返回数据需提供类目、和商品的图片，方便UI展示和顾客选品。

请求参数说明

参数	参数名称	类型	必须	参数说明
cashierNum	收银员号	String	N
posNum	收银机号	String	N

响应结果说明

参数			参数名称	类型	参数说明
data			JSON Object
	column		商品布局列数	int	商品在POS UI上的透出布局，每一行摆放的商品列数。可设数值：1、2、3、4。默认值：3。
	categories		商品类目列表	JSON Array
		id	类目ID	String
		title	类目名称
		picUrl	类目图片
		items	商品列表	JSON Array	List<Commodity> 不需要商品行号rowNo

5.14 商品批量加购(buycommodities)

接口说明

针对非标商品点单，支持批量查询加购（对已在购物车商品，只需更新商品数量），返回当前购物车的全商品列表数据。合计金额带优惠计算后金额。购物车标准，请查看"7、购物车标准"。

请求参数说明

参数		参数名称	类型	必须	参数说明
tradeFlowNo		交易流水号	String	Y	交易流水号／购物车ID
data		商品列表	JSON Array	Y	接口单次上限支持100行
	rowNo	商品行号	String	Y	rowNo == "-1"：代表新加购商品，需要商品查询。 rowNo != "-1"：代表已在购物车商品，按行号更新数量。
	barcode	商品条码	String	Y
	quantity	商品数量	String	Y	商品数量。当商品数量为 0 时，删除该商品行。

响应结果说明

参数		参数名称	类型	参数说明
data		JSON Object
	totalFee	合计总金额	long	单位：分
	discountFee	折扣总金额	long	单位：分
	actualFee	折扣后实际总金额	long	单位：分
	items	商品列表	JSON Array	List<Commodity>

5.15 淘鲜达品牌营销

淘鲜达品牌营销，主要由ISV支付平台对接淘鲜达营销平台，在交易中，支持淘鲜达品牌营销。淘鲜达定义好营销接口，ISV支付平台来对接。具体细节方案，后面对焦。

5.16 对账功能

后台对账功能。支付订单和ERP销售订单对账，方便发现解决单边账问题。

5.17 日结功能（dailysettle）

接口说明

用于通知商家后台，该机台此时可以进行日结。

请求参数说明

参数	参数名称	类型	必须	参数说明
deviceSN	设备序列号	String	Y	设备序列号
posNum	设备通道号	String	N	设备通道号，非必传
shopId	门店ID	String	N	门店号，非必传
cashierNum	收银员号	String	N	收银员号，非必传
extra	额外信息	String	N	备用，非必传

响应结果说明

参数		参数名称	类型	参数说明
traceId		请求追踪ID	String
retCode		错误码	String	"0" - 请求成功；非"0" - 请求失败；
retMsg		错误码描述	String
data
	dailySettleBill	日结小票协议	String	按照小票协议组织数据，可自定义日结小票的内容和排版。这是一个JSON格式的字符串，根据一套协议编码，可以让商家自定义内容。详细信息参考文档(merchantInfo注意替换成dailySettleBill)：https://hema.open.taobao.com/doc?docId=118904&docType=1
extra		额外信息	String	备用

5.18 取消合计（cancelsubtotal）

接口说明

对不同的ISV，接口入参和返回数据必须一致，但是ISV可根据自己的实际情况和需求，赋予接口不同的含义。

请求参数说明

参数	参数名称	类型	必须	参数说明
tradeFlowNo	交易流水号	String	Y	交易流水号／购物车ID
userId	会员ID	String	N
userType	会员类型	String	N
extra	额外信息	JSON Object	N	备用

响应结果说明

参数		参数名称	类型	参数说明
data		JSON Object
	totalFee	合计总金额	long	单位：分
	discountFee	折扣总金额	long	单位：分
	actualFee	折扣后实际总金额	long	单位：分
	items	商品列表	JSON Array	List<Commodity>

需求	cancelsubtotal接口的业务逻辑	说明
ISV需要合计中返回赠品和换购品	cancelsubtotal删除购物车中的赠品和换购品，返回新的合计金额和商品列表。	本次需求需要实现
ISV需要合计后锁定购物车	cancelsubtotal解锁购物车
ISV对合计接口无特殊需求	cancelsubtotal只返回购物车数据，不做特殊处理

6、接口对象定义

6.1 商品（Commodity）

称重商品定义

1）商家商品系统有维护称重标识，以称重标识为准。

2）商家商品系统没有维护称重标识，以库存单位区分，单位为重量单位（如 g、kg、克、千克、斤、公斤）

的商品，为称重商品。

3）在1)和2)都不适用情况下，以商品条码识别区分，商品数量／重量从商品条码（数量金额码、金额重量码）

获取的商品，为称重商品。

称重商品交互

1）称重商品，每次扫码，即使条码一致，购物车条目也不合并

2）称重商品，不可手动编辑数量

3）称重商品，不管重量多少，1份只占商品总件数中的1件

参数	参数名称	类型	参数说明
rowNo	商品行号	String	商品行标识
barcode	商品条码	String	扫码出来的
isvSkuCode	商品编码	String
name	商品名称	String
picUrl	商品图	String
price	原价格	long	单位：分
promotionPrice	实际销售价格	long	单位：分
unit	单位	String
quantity	非称重商品购买数量	int	isWeight = true，默认值 0 isWeight = false，返回商品购买数量
weight	称重商品重量	float	单位：kg isWeight = true，返回商品重量 isWeight = false，默认值 0.0
isWeight	是否称重商品	boolean	true：称重商品；false：非称重商品
saleType	商品销售类型	int	0 - 正常商品， 1 - 赠品， 2 - 换购商品 3 - 享受额外打折（如折扣码、优惠券等）的折扣商品
totalFee	合计金额（含优惠金额）	long	单位：分商品行纬度的合计金额
discountFee	优惠金额	long	单位：分商品行纬度的优惠金额
actualFee	实际金额（不含优惠金额）	long	单位：分商品行纬度优惠后合计金额
extra	额外信息	String	备用，优惠明细等

6.2 支付结果（PayDetail）

requestId		幂等请求ID	String
orderId		交易订单号	String
payTotal		总支付金额（包含优惠金额）	long	单位：分
discountTotal		总优惠金额	long	单位：分渠道支付优惠（如：支付宝优惠）
remainFee		剩余支付金额	long	单位：分 remainFee = 0，支付完成
currentPay		当次支付结果	JSON Object
	outCheckOutId	渠道支付单号	String	支付新生成的渠道支付单号
	payFee	支付金额	long	单位：分
	discount	优惠金额	long	单位：分渠道支付优惠（如：支付宝优惠）
	status	支付状态	String	SUCCESS - 支付成功 FAIL - 支付失败 INPROGRESS - 等待支付结果
	timestamp	支付时间戳	String	格式 yyyyMMddHHmmss
payList		付款明细列表	JSON Array
	code	付款方式编码	String
	name	付款名称	String
	account	付款账号	String
	amount	付款金额	long	单位：分
extra		额外信息	Map<String,String>

7、购物车标准

7.1 购物车商品数据顺序

正常情况，先查询的商品排在前面，后查询的商品排在后面

有商品合并的情况，被合并的商品，当做最后查询的处理，排在最后面

删除某一行商品，购物车其他商品整体排序不变

修改购物车中的商品数量，购物车整体排序不变

7.2 购物车生命周期

购物车在交易未完成前，不能销毁。需支持以下场景：

交易失败，可以返回购物车，并可继续发起结算、创单、支付

同一笔订单，支付失败／超时／取消时，可以重新支付

8、示例

8.1 商品查询接口传参和返回示例

请求URL

https://essp-test.lhhspay.com.cn/isv/txd/v1/querycommodity

请求参数

Headers

X-Sign  hNJ9x8sUSZ5tcOX+xxrKKrB26sJWkiau6sITygAdzXnaoi3tBT9T2HkxFX40YefAU+mSwueC2z26NGEdWCAoM51e1R7RJwCFtrwYeZ6F5F/Ie6tA7uWtXLlYy2YmOx7eh1mSCgNrxlu69go6c5Uket02oreOaMRbn+s2olNBTVI=
X-MerchantCode  20180720hsmkjjw2
X-StoreCode 1007188

Body

{
    "barcode": "01010001",
    "tradeFlowNo": "HDFUQINGJIAYUAN2137924050049A190221111913065",
    "cashierNum": "9999",
    "posNum": "0049A"
}

响应结果

Headers

X-Sign  M1x9IHn6wj8kmHXCakyN4bkMse+mgcbuDxVTRl5EdBgTluKnpllVBqAQsNoQHHbZNILkJDLKk2c/6GOefL2k22B3nRY8UjxiKtphHd98YosqjX21/jiHXYnFw/qZhbUc5FonnLZVmkCCcA7yeYoOQ59W/fBpl74UKbBU+hXencY=

Body

{
    "traceId": "ba7a4d2d-c53a-42ec-9958-43e836efb42d",
    "retCode": "0",
    "retMsg": "接口调用成功",
    "data": {
        "totalFee": 30,
        "discountFee": 0,
        "actualFee": 30,
        "items": [{
            "rowNo": "a7f3a791-fd0b-458a-a5a0-790d86173593",
            "barcode": "01010001",
            "isvSkuCode": "01010001",
            "name": "特大号塑料袋",
            "picUrl": null,
            "price": 30,
            "promotionPrice": 30,
            "unit": "个",
            "quantity": 1,
            "weight": 0,
            "isWeight": false,
            "sellStatus": true,
            "discountFee": 0,
            "extra": null,
            "totalFee": 30,
            "actualFee": 30
        }]
    }
}

9、非标品集合码规则

二维码内容

<gr>混淆条码混淆条码混淆条码混淆条码</gr>

说明

起始位："<gr>" 二维码内容开始的标记.

结束位："</gr>" 二维码内容结束的标记.

条码分段位:" " 条码分割位（空格）.

混淆位："&" 单个条码每4位添加一个混淆位，不足4位不需添加.主要用于出现断码后命中其他商品导致顾客加购错误的商品，一般商品条码都超过5位，混淆位对4位以上的断码进行混淆，使其无法命中其他商品条码.

例如：条码1234567 添加容错位后为1234&567

处理步骤

例如:"<gr>2102&6632&2000&06 6901&2363&4158&2 2102&6632&2000&07</gr>"

1.扫码需要对内容做完成性校验,包含起始位<gr>和结束位</gr>，否则提示用户重新扫码。

2.对于完整的二维码内容进行解析

2.1 去除“起始位”“结束位”“混淆位”:21026632200006 6901236341582 21026632200007

2.2 按分段位进行分割：[21026632200006,6901236341582,21026632200007]

3.对解析后的多个条码使用批量加购接口(buycommodities)进行添加.

验收标准

假设：
可录入商品条码：10001 10002 10003
不可录入商品条码或机台禁售条码： 20001 20002 20003

场景1:所有商品可用
输入：二维码内容:<gr>1000&1 1000&2 1000&3</gr>
输出：购物车成功加入3个商品

场景2:首位商品不可售或条码错误

输入：二维码内容:<gr>2000&1 1000&2 1000&3</gr>

输出：以上3个条码商品均未加购成功

场景3:中间部分商品不可售或条码错误

输入：二维码内容:<gr>1000&1 2000&2 1000&3</gr>
输出：以上3个条码商品均未加购成功

场景4:末尾商品不可售或条码错误

输入：二维码内容:<gr>1000&1 1000&2 2000&3</gr>
输出：以上3个条码商品均未加购成功

场景5:集合码格式错误

输入：二维码内容:<gr>1000&1 1000&2 1000&3<gr>
输出：以上3个条码商品均未加购成功

场景6:集合码格式错误

输入：二维码内容:<gr1000&1 1000&2 1000&3</gr>