开发接入
服务商接入流程
| 场景 |
子模块 |
执行方 |
说明 |
| 接收任务 |
根据项目排期，接收并执行任务 |
服务商/自研商家 |
登录淘宝开放平台，确认排期并执行 |
| 当面付API对接 |
1、POS的工作 |
服务商/自研商家 |
支付宝收银，正向下单与逆向退款接口的调整 |
| 准备应用 |
1、申请并创建"新零售交易"应用 |
服务商/自研商家 |
申请应用，获取接口调用权限 |
| 商品管理 |
1、商品维护策略 |
服务商/自研商家 |
维护商品信息到新零售工作台 |
| 其它 |
1、门店API管理 |
服务商/自研商家 |
选做功能，调用奇门接口CRUD线下门店信息 |
| 联调与门店预演 |
通过联调测试和门店预演CASE |
服务商/自研商家 |
预演需要门店导购配合，模拟消费者下单 |
注：该文档主要面向服务商和自研商家的IT、研发、运维、系统实施工程师，详细的接口内容，请看接口开发指南。
1.接收任务
服务商用企业开发者账号登录淘宝开放平台后，选择控制台-场景化对接，确认支付排期并执行；同时登录的开发者账号如果没有申请应用，可用于申请“新零售交易”应用，方便对接商品和门店API。
2.当面付API对接
2.1 POS的工作
通常线下门店具备支付宝收银的都支持了当面付能力，如果还未支持的，可以先对接支付宝开放平台的API接口：支付宝开放平台
1）支付宝当面付接口增加商品id、门店id、商品单价、商品个数、商品名称
2）门店优惠券、购物津贴（商家出资）和红包（平台出资）的使用，收银小票需展示出资内容，订单记录优惠信息用于对账
3）逆向流程，带有门店优惠券、津贴、红包等优惠的订单退款金额由POS计算
4）逆向接口POS需传入商品信息
2.2 当面付收单API调整
2.2.1 消费者被扫模式（导购用把枪扫消费者支付码）
接口：alipay.trade.pay
接口名称：统一收单交易支付接口
支付链路接入的前提条件是门店具备支付宝当面付收银能力。该接口属支付宝开放平台API。
入参需增加的5个字段：store_id、goods_id、goods_name、quantity、price
2.2.2 消费者主扫模式（生成订单二维码，买家扫码）
接口：alipay.trade.precreate
接口名称：统一收单线下交易预创建
支付结果的返回信息参看，当面付异步通知-仅用于扫码支付，需增加字段与被扫接口一致，通常被扫与主扫对接二选一。
2.3 当面付退款API调整
接口：alipay.trade.refund
接口名称：统一收单交易退款接口
逆向接口POS推荐传入商品信息，部分退场景中，退款的优先级顺序：实付>红包>购物津贴>优惠券
2.4 支付宝相关问题开发者大群
具体智慧门店当面付升级对接细节，请开发者扫码加入开发者大群咨询，特别说明：用钉钉扫描，钉钉账号需要与支付宝账号对应一致的手机号。
3.准备应用
3.1申请并创建“新零售交易”应用
使用API管理门店与商品信息，需要企业开发者账号申请淘宝开放平台（TOP）的“新零售交易”应用。注意：如果是ISV开发需ISV来申请，如果是自研则由商家来申请，对于ISV服务商开发而由商家来申请应用会引起工作量统计错乱，谨慎申请。
3.2设置应用回调地址
应用回调地址的作用是在用户通过淘宝授权地址登录授权后跳转至回调地址，并传递相应的参数；正确的回调地址须满足域名中不含有“taobao、ali、alibaba、hitao、koubei”等官方英文字母，回调地址须能正常打开和访问到您相对应的服务器应用。在【淘宝开发平台-控制台-应用管理-应用设置-基本信息】可设置回调URL。
3.3应用获取授权
1）授权的作用是：当前登录账号授权指定APPKEY可以拉取属于自己的业务数据（如门店、商品、会员等）。业务数据属于哪个账号，就用哪个账号进行授权，比如：门店、商品数据属于旗舰店则用旗舰店来授权；线下通的会员数据归属于品牌号br账号则用br来授权；全打通的会员数据归属于旗舰店则用旗舰店来授权。
2）旗舰店和br的授权，在开放平台进行：可通过授权工具手动授权（到期前需要人工重新授权，不建议该方案）；也可以通过代码对接实现系统自动授权（推荐该方案，可自动监控过期时间），获取授权的方式参看授权说明文档。TOP接口的调用方法参考文档。
3）无旗舰店的商家，数据归属于EA企业账号，由于没有登陆账号和密码，因此不能通过开放平台授权，需要在新零售工作台-企业管理-应用中心-应用授权，授权到期前需重新手动重新授权，将生成的授权sessionkey信息提供给服务商。如下图：
4）服务商注意：授权时长一般和应用的订购时长保持一致，一般是一年；新零售交易应用不用走订购，默认授权1年；权时长到期前需提醒商家进行重新授权（ISV需要为商家提供授权的页面）。
4.商品管理
4.1商品维护策略
新零售工作台根据商家编码(skuOuterId)和货号(outId)，对上传的商品信息有重复校验功能，所以要求同一品牌下商品的商家编码和货号具有唯一性，不能重复；上传到新零售工作台的商品数据池，需能覆盖线下门店的全量可交易商品，包括：赠品和购物袋；商品API上传不要求实时性，针对应季更新的商品，推荐用定时任务，空闲自动上传。
说明：
1.智慧门店交易入参里的good_id匹配商品的规则：先在智慧门店后台商品库里找，找不到再到天猫商品库里找。
2.如果都找不到，则该笔订单记为无效订单（无效订单不影响优惠券核销）。
3.无论天猫商品还是智慧门店商品库商品，需确保所有商品的SKU已配置了“商家编码”，且和支付接口中传入的good_id保持一致。
4.2商品API
商品量级大，发布要用接口来管理，否则商家运营人员的人肉成本非常高。商品管理API如下：
1）taobao.omniitem.item.publish (全渠道门店商品轻发布)
2）taobao.itemcats.get(获取后台供卖家发布商品的标准商品类目)
3）taobao.omniitem.item.image.upload (全渠道商品上传图片)
4）taobao.omniitem.item.fullupdate (全渠道商品全量更新)
5）taobao.omniitem.item.delete (全渠道商品删除)
6）taobao.omniitem.item.get (获取全渠道门店商品)
7）taobao.omniitem.sku.get (获取全渠道门店商品sku)
关于接口的特别说明：
1）taobao.itemcats.get接口可返回标准商品类目；
2）商品发布和更新接口中的【规格】和【型号】PID对应的上传字段为【规格】＝-1，【型号】＝-2，PID=20000不需要上传；
3）可优先实现商品发布(publish)接口，该接口使用最频繁，注意：
a.要保证商品和sku的商家编码outerid不为空且唯一；
b.商品图片仅支持url上传，且必须是图片空间的url地址，如果门店商品不好取图片，可以先上传品牌logo的统一图片；
c.如果要上传本地图片，可以在publish后再调用upload接口。
5.其它
5.1门店API管理
门店信息管理支持三种方式，包括：客户端页面发布、Excel批量导入、奇门API发布；调用奇门接口前，需联系阿里小二，提供您的应用名称、appkey和商家旗舰店名称，小二进行接口调用授权后方可调用，具体可参考接口开发指南：
1）新增门店taobao.qimen.store.create
2）更新门店taobao.qimen.store.update
3）查询门店taobao.qimen.store.query
4）删除门店taobao.qimen.store.delete
5）门店类目获取taobao.qimen.storecategory.get
5.2会员码身份识别接口
接口：tmall.mei.crm.member.getbypaycode
接口名称：支付码(会员码)识别
该接口属于会员通接口，前提条件是授权的账号已经入驻会员通，POS扫码识别消费者身份的对接方案有三种，商家根据自己的情况选择最合适的方案：
1）每笔交易前POS用会员身份标识字段去CRM查询会员信息：该场景只需要门店POS将会员码串号发给CRM，由CRM调用该接口查询返回会员信息给POS。
2）POS与CRM没有实时同步，哪一方有变更后再同步给对方以保证数据同步，该场景需要POS本地查询会员信息，POS通过会员码串号调用该接口获取加密手机号进行身份识别。需要POS服务商从商家那里拿到会员通商家密钥（商家如果不知道如何拿可以咨询CRM）。
3）商家没有CRM只用POS来管理会员：该场景需要POS服务商另外申请会员通应用，拿到手机号加密算法，进行身份识别，即POS替代了CRM的工作。
5.3获取智慧门店交易订单
为了避免对ERP系统的影响，平台目前暂不通过消息推送、TMC消息和订单详情API（taobao.trade.fullinfo.get）开放门店订单，但是通过taobao.trades.sold.get、taobao.trades.sold.increment.get获取订单列表时，可以拉取到门店订单的列表详情。
对于有在调用taobao.trades.sold.get、taobao.trades.sold.increment.get的商家，解决方案：两个接口中分别增加is_o2o_passport字段，返回值：true、null；如果返回true,则表示此订单为passport订单。isv在调用taobao.trades.sold.get、taobao.trades.sold.increment.get两个接口，监测is_o2o_passport字段是否为true，若为true，则屏蔽该订单，若为null，则正常处理。注意订单类型选择o2o_offlinetrade（O2O交易）。
6.联调与门店预演
联调和预演CASE
部署、升级好系统，配合商家通过联调测试和门店预演的CASE，请点击这里。
