全渠道
1.背景
1.1业务背景
商家在门店的日常经营中，期望通过线下ERP/POS管理系统统一管理会员，识别用户并将交易进行电子化，为后续的二次营销触达提供数据基础。为此，阿里全渠道推出手淘Passport支付方案，并开放接口与线下ERP/POS管理系统进行对接。
1.2 对接前期准备
1.2.1 申请TOP应用
TOP：Taobao open platform（淘宝开放平台）。门店支付链路主要在门店POS端完成，因此对接支付一般由POS系统完成对接，目前，门店POS系统基本上还都没有与淘宝开放平台对接过，因此首先需要申请TOP的应用，申请标签“门店信息化”，定向申请地址：http://my.open.taobao.com/common/applyIsv.htm?appTag=122&accessCode=CFF55A285DCE08572589D37D934D60FE
拿到应用后，向阿里小二申请接口的权限包“Passport解决方案”。TOP接口的调用方法可参考文档：//open.taobao.com/docs/doc.htm?spm=a219a.7629140.0.0.T52mlu&treeId=49&articleId=101618&docType=1
1.2.2 授权信息
淘宝接口的调用，需要获取商家的授权（access_token/sessionkey）,获取的方式参看授权说明文档。
说明：
- 授权时长一般和应用的订购时长保持一致，一般是一年，授权时长到期前需提醒商家进行重新授权（ISV需要为商家提供授权的页面）。
- B/S架构授权参看server-side flow，C/S架构授权参看client-side flow。
1.2后台及接口说明
1.2.1 全渠道商品库同步后台
- 单个商品发布功能
- 批量导入功能
- 接入方式
1) 全渠道中心入驻-商家操作（如果之前已经入住过了可以直接进入“运营中心”），地址：https://omnichannel.taobao.com
1.2.2 系统接入架构图
- 接入模式
-支付链路正向流程图
-支付链路逆向流程图
2.接口规范
2.1全渠道商品库
接口开发阶段，需要商家先在全渠道中心发布1-2个测试门店商品，为POS进行支付链路测试使用。待正式运行系统后，需商家将门店在售商品全量上传（天猫已发布过的商品可以不用重复上传），并上传一个保底替换商品“其他”，作为搜索不到商品时候的替换品。详细介绍见“3.1门店商品导入操作说明”。
2.2扫码识别商品接口
接口名：taobao.daogoubao.item.scan
功能描述：扫商品条形码识别商品信息
说明：
1. 如果门店扫码时候发现该商品查询不到淘宝平台对应的商品（比如没有在淘宝平台发过该商品），则无法完成后面的创建订单。解决方案：商家可以在全渠道中心门店商品管理中创建一个“其他”商品作为冗余备用商品，如果把枪扫码查不到淘宝商品ID，则可以使用“其他”商品临时替代，如果同一笔订单出现多个未找到商品，则使用多个“其他”商品替代，价格设置成不同。
2. operator_id字段获取方式见交易创建接口说明。
3. 商品查询的规则：
a. 如果商品上含有sku信息，商品编码和条码必须传入SKU粒度的，否则报错。
b. 如果一个商品编码对应对应多个不同商品，那么会优先匹配最近修改过的门店商品库商品，如果没有对应门店商品库商品但有线上商品，那返回最新修改过的线上商品。
4. 商品查询的测试用例：
a. 门店商品无SKU，通过条形码或者商家编码查询。如下图（来自全渠道中心）：
b. 门店商品有SKU（包括1个SKU或多个SKU），需要通过SKU粒度的条形码或者商家编码查询，用item粒度查询会报错。如下图：
a) 1个SKU：
b）多个SKU：
c. 条形码或者商家编码有重复的情况下查询结果的优先级验证（查看“商品查询规则”）。
2.3创建即时到账交易订单接口
接口名：taobao.daogoubao.tradeorder.create
功能描述：创建即时到账交易订单
说明：
1. response返回信息中的status的枚举值如下：
a. "success"："支付成功"，同步接口返回。支付链路结束。
b. "fail":"支付失败"，同步接口返回，对于失败订单，平台会自动关闭该订单（手淘订单状态为“交易关闭”），POS可换其他支付方式，也可以重新扫码重新创建订单支付。
c. "unknown"："支付未决"，场景：例如支付金额超出消费者免密支付额度（默认是1000元）的情况下，需要消费者输入密码等情况，因此，需要接口调用方做异步轮询支付状态，见轮询接口。
2. 交易类型：
a. 如果是passport扫码支付，订单会进入消费者手淘的订单列表中，但仅仅是订单详情的展现，还无法查看商品详情。
b. 订单生成后是会通过数据推送将消息推送给ERP系统，ERP系统也可以通过trade.fullinfo.get接口获取到该笔订单。该类订单的区分字段：O2O=crm，o2opassport=1。这里需ERP对订单类型进行区分，请注意!
3. 关于商品价格：
a. 支付环节的实扣金额以POS系统回传的价格为准.
b. 关于total_amount、price： 如果商家传入总价和商品单价，平台会按照商品总价下单，如果总价和商品单价求和有差异，平台会把总价和传入的单价求和的差值按商品价格均摊差异；b. 如果商家只传入商品单价，订单金额就是单品价格求和。逆向退款按商品单价退款。
c. 目前不支持商品价格为0。
d. 示例：一笔订单购买了三个商品A：300元，B：300元，C：500元，让利100元。
a）情况1：创建订单时传入总金额1000，A300，B300， C500，则平台进行分担分摊金额计算是 300-（1100-1000）*（300/1100）≈ 272.73，300-（1100-1000）*（300/1100）≈ 272.73，500-（1100-1000）*（500/1100）≈ 454.55。平台扣款按照1000元扣款，退款则按照子订单的金额退款。
b）情况2：创建订单时传入A 272.73，B 272.73，C454.55，平台扣款按求和后的1000.01扣款，退款则按子订单的金额退款。
4. 关于合并商品的处理： 场景举例：购买商品A第一件5元，第二件4元，第三件2元，消费者购买了三件，总共是11元，pos如果调用该接口传入3次商品A，则会报“合并商品”的提示。解决方案：
a. POS合并商品：POS系统合并为一个商品买3件，每个商品的价格POS做均摊告知平台。
b. 平台兜底合并商品：如果POS未做均摊，调用该接口传了三次商品A，平台合并商品A，均摊总金额11元到每个商品上，按四舍五入计算，即67*3 =11.01，最终总金额会有一些偏差。退款时候，消费者根据要退的件数和导购员协商退款金额，不能超过11.01元。
5. operator_id门店子账号ID获取方式：接口：taobao.place.account.query,//open.taobao.com/docs/api.htm?spm=a219a.7629065.0.0.fXJa4S&apiId=27592，入参demo：query_d_o= { "account_nick": "****旗舰店:璐璐"}。
6. operatorId子账号ID字段一定要正确填写，不同门店创建的订单要用该门店的子账号来发起，因为这里会涉及到后面的分账，分账账单会透出子账号对应的门店ID，如果使用了错误的子账号，则会影响分账。
2.4支付结果查询接口
接口名：taobao.daogoubao.paystatus.polling
功能描述：对于支付未决的订单，需要轮询支付结果
说明：
1. 轮询查询订单支付结果可能收到的支付状态也有success、fail、unknow。
2. POS可以自己定义轮询多少次，轮询多少时间，直到平台返回success或fail，如果多次查询结果都是unknow，POS可决定将该笔订单关闭（使用关单API），按fail流程执行。
2.5 关闭订单接口
接口名：taobao.daogoubao.tradeorder.close
功能描述：关闭订单接口
说明：
1. 只有状态为“待付款”的订单可以执行关单操作，已关单和交易完成的订单不能关单。
2. 订单如果支付没有成功，一定要关单，因为不关单门店优惠券会始终被占用，只有关单后优惠券才能重新释放。
2.6根据主单号查询子单退款列表
接口名：taobao.daogoubao.refund.query
功能描述：根据主订单号查询子订单退款列表
2.8同意退款接口
接口名：taobao.daogoubao.refund.agree
功能描述：门店导购员发起同意退款请求
2.9拒绝退款接口
接口名：taobao.daogoubao.refund.refuse
功能描述：passport订单拒绝退款
2.10扫码付款码识别用户信息接口
接口名：tmall.mei.crm.member.getbypaycode
功能描述：扫码付款码识别用户信息
说明：
1. 该接口是会员通接口，前提条件是授权的账号已经入驻会员通，会员通目前使用的是品牌号的账号，因此需要使用品牌号的账号进行授权获取sessionkey，未入驻会员通的账号调用该接口，返回为空。
2. POS扫码识别消费者身份的对接方案有三种，商家根据自己的情况选择最合适的方案：
a）POS与CRM实时同步，每笔交易前POS用会员身份标识字段去CRM查询会员信息：该场景只需要门店POS将串码传递给CRM，由CRM调用该接口查询返回会员信息给POS。
b）POS与CRM没有实时同步，哪一方有变更后再同步给对方以保证数据同步，该场景需要POS做加密手机号的双向加密匹配，POS通过调用该接口获取到的加密手机号进行身份验证，需要POS服务商从商家那里拿到会员通商家密钥（商家如果不知道如何拿可以咨询CRM），POS识别会员身份之后将会员信息进行变更后的结果（交易用积分/赚积分等）同步给CRM。
c）商家没有CRM只用POS来管理会员：该场景需要POS服务商另外申请会员相关应用，拿到手机号加密算法，进行身份识别。
3. 重要说明
1. 关于商品发布，需要商家多发布一个“其他”商品，作为查询不到itemId和skuid的备用商品。
2. 关于子账号，接口入参里的operatorId子账号ID字段要正确填写，不同门店创建的订单要用该门店的子账号来发起，因为这里会涉及到后面的分账，分账账单会透出子账号对应的门店ID，如果使用了错误的子账号，则会影响分账。
3. 关于订单类型，订单生成后是会通过数据推送将消息推送给ERP系统，ERP系统也可以通过taobao.trade.fullinfo.get接口获取到该笔订单。该类订单的区分字段：O2O=crm，o2opassport=1。这里需ERP对订单类型进行区分，请注意！
4. 关于关单操作，订单如果支付没有成功，一定要关单，因为不关单门店优惠券会始终被占用，只有关单后优惠券才能重新释放。
4. 系统开发完毕后，请参考下面的测试用例：
4. 其他说明
4.1加密手机号的双向加密策略
出于安全考虑，消费者手机号在特定情况下仅能提供加密手机号，如何识别这个人的身份？ISV可以通过使用相同加密算法，进行双向加密后匹配密文，如果可以匹配上则可以推导出明文手机号，如果匹配不上，则说明是会员库里没有的新用户。
平台为每个已入驻会员通的品牌商家分配一个密钥，并使用MD5做两次加密，加密结果为 MD5(MD5("tmall"+$content+$key))，加密后的字符串为 32 位小写。tmall 为固定字符 串，key 为手机号加密密钥(会员中心开发者后台、测试平台可见)、content为需要加密的内容(这里是 moblie)。
代码示例：DigestUtils.md5Hex(DigestUtils.md5Hex("tmall" + "15089990091"+ "abcd"));
