智慧门店
一、 内容概要
1.1 基本功能
该文档详细描述了品牌方开发者接入品牌会员中心所需的接口开发规范。请以该文档内容为准。主要包括会员绑定、查询、解绑、注册、积分变更等功能。
1.2 名词解析
- SPI（Service Provider Interface）：服务商提供接口，会员中心作为调用方。请求入参在request的body中，返回相应的json格式文本。注意：返回参数以该文档为准
- TMC：消息通知，会员中心发起的消息通知，主要用于积分变更等重要消息的发送，有重试机制保证消息一定到达。
- 飞行模式：消费者入会请求到阿里平台，不会请求到服务商系统，即服务商是没有此消费者信息的，飞行模式关闭后，平台将进行数据订正，将数据回传商家CRM
- 绑定和注册的区别
- 绑定：绑定是指品牌方有该会员信息(手机号码)，该类用户可绑定；建立淘宝账号与此会员的关联关系。
- 注册：注册是指品牌方无该会员，该类可注册；新增一条会员记录，并建立淘宝账号与此会员的关联关系。
1.3 开发者准备工作
- 消息订阅：商家入驻审批完成后，如果开发礼品兑换功能，则订阅会员中心积分变更消息。消息名称：tmall_mei_PointChange
二、 接口说明
2.1 绑定查询请求
SPI名称tmall.mei.crm.member.bind.query
场景说明 当用户在页面发起绑定操作时，会触发该请求。
请求查询参数
| 名称 | 类型 | 描述 |
| seller_name | 字符串 | 卖家昵称 |
| mobile | 字符串 | 明文手机号码（部分商家使用） |
| nick | 字符串 | 明文nick |
| extend | 字符串 | extend{"alipay_user_id":"2088702372175543", "flightMode":"1", "flightJoinTime":"2018-05-18 01:16:23" } |
flightMode：1 开启飞行模式 ；只有开启飞行模式，才会显示该字段
flightJoinTime：飞行模式开启期间，消费者真实的入会时间
body示例(不同权限会透出不同的组合参数，其他接口body示例类同，这里仅是其中一种)：
例 手机号权限方式： { "seller_name": "天猫精灵", " mobile ": "138XXXXX", "extend":"{"alipay_user_id":"2088702372175543" }" }
请求返回结果（所有字段均为必选）
| 名称 | 类型 | 描述 | 是否必填 |
| bindable | 布尔值 | 是否能绑定。如果返回true，则需要品牌方将明文的nick,mobile返回。 | 是 |
| bind_code | 字符串 | 必填 以下为不能绑定的代码，如果可绑定返回SUC。 E01:会员不存在 E02:会员已被绑定 E04:会员不存在，可注册 E05:系统繁忙或异常，可重试 其他原因可传F01，F02等， 系统统一识别为会员不存在 | 是 |
| member | 复杂类型 | 会员信息见下表 | 是 |
member信息：
| 名称 | 类型 | 描述 | 是否必填 |
| point | 数字 | 积分数值 | 是 |
| nick | 字符串 | 用户的淘宝nick | 是 |
| level | 数字 | 会员等级 | 是 |
| extend | 字符串 | json对象，如果商家有卡号需要同步落支付宝卡包，可以回传 "card_no":"10000"；一般建议直接传空值 | 是 |
| mobile | 字符串 | 会员明文手机号码 | 是 |
返回值示例(严格按照接口返回类型进行返回，其他接口返回值示例类同)：
{"bind_code":"SUC","bindable":true,"member":{"mobile":"15088551672","nick":"test","point":"2000","level":"1","extend":"{/"card_no/":/"1000001/"}"}}
2.2 绑定请求
SPI名称 tmall.mei.crm.bind
场景说明
- 当绑定查询返回可绑定时，触发该请求。
- 当用户解绑时，触发该请求。
请求查询参数
| 名称 | 类型 | 描述 |
| seller_name | 字符串 | 卖家昵称 |
| taobao_nick | 字符串 | 淘宝昵称 |
| type | 字符串 | 操作类型，1-绑定，2-解绑 |
| mobile | 字符串 | 明文手机号码（限部分商家使用） |
| extend | Json字符串 | 会员的拓展信息extend:{ "storeId":"140085107","source":"offline", "channel":"memberCode","salerId":"123","name":"张三","sex":1,"birthday":"04-01","birthDate":"1991-04-01","babyBirthday":"1999-07-01" ,"province":"330000","city":"330100","email":"123@taobao.com","employeeNo":"10141383", "flightMode":"1", "flightJoinTime":"2018-05-18 01:16:23"} |
注： 目前可以给到的用户拓展信息为姓名、性别、出生年月日、邮箱、宝宝出生年月日、省份，城市；商家如果需要，告知小二进行配置 name：消费者姓名；sex：1（男性）2（女性）；babyBirthday：宝宝的生日；birthday：出生月日，birthDate：出生年月日，province：省份，city：城市,employeeNo:导购工号（商家自用）
省份和城市透传区域编码，可以通过接口转换：taobao.areas.get
flightMode：1 开启飞行模式 ；只有开启飞行模式，才会显示该字段
flightJoinTime：飞行模式开启期间，消费者真实的入会时间
入会方式说明：
channel:memberCode + source:offline + storeId + employeeNo = 导购码入会
source：online + channel：memberCode = 会员码入会
source：online + channel：brandSite = 品牌号入会
source：online + channel：shop = 天猫旗舰店入会
source：offline + channel：scanCode + storeId = 扫门店码入会
source：offline + channel：memberCode + storeId = 支付成功页入会
请求示例： 手机号权限方式： { "seller_name": "天猫魔盒", "mobile": "15088909090", "taobao_nick": "super", "type": "1" }
请求返回结果（所有字段均为必选）
| 名称 | 类型 | 描述 | 是否必填 |
| member | 复杂类型 | 会员信息，见下表 | 是 |
| bind_code | 字符串 | 绑定结果代码： SUC:处理成功 E01:系统异常，可重试，E02:绑定失败，非品牌会员，不可绑定 E03:绑定失败，已被其他用户绑定 E04:绑定失败，该帐号已经绑定 其他原因可传F01，F02等， 系统统一识别为非品牌会员，不可绑定 | 是 |
member信息：
| 名称 | 类型 | 描述 | 是否必填 |
| point | 数字 | 积分数值 | 是 |
| nick | 字符串 | 用户的淘宝nick | 是 |
| level | 数字 | 会员等级 | 是 |
| extend | 字符串 | json对象，如果商家有卡号需要同步落支付宝卡包，可以回传 "card_no":"10000"；一般建议直接传空值 | 是 |
| mobile | 字符串 | 会员明文手机号码 | 是 |
返回值示例： {"bind_code":"SUC","member":{"point":"2000","extend":"{/"card_no/":/"1000001/"}","level":"1","mobile":"15088551672"}}
2.3 注册请求
SPI名称 tmall.mei.crm.member.register
场景说明 当绑定查询返回可注册时，会触发该请求。
请求查询参数
| 名称 | 类型 | 描述 |
| seller_name | 字符串 | 卖家昵称 |
| taobao_nick | 字符串 | 明文淘宝昵称 |
| mobile | 字符串 | 明文手机号码 |
| extend | 字符串 | 会员的拓展信息extend:{ "storeId":"140085107","source":"offline", "channel":"memberCode","salerId":"123","name":"张三","sex":1,"birthday":"04-01","birthDate":"1991-04-01","babyBirthday":"1999-07-01" ,"province":"330000","city":"330100","email":"123@taobao.com","employeeNo":"10141383", "flightMode":"1", "flightJoinTime":"2018-05-18 01:16:23"} |
注： 目前可以给到的用户拓展信息为姓名、性别、出生年月日、邮箱、宝宝出生年月日、省份，城市；商家如果需要，告知小二进行配置 name：消费者姓名；sex：1（男性）2（女性）；babyBirthday：宝宝的生日；birthday：出生月日，birthDate：出生年月日，province：省份，city：城市，employeeNo：导购工号（商家自用）
省份和城市透传区域编码，可以通过接口转换：taobao.areas.get
flightMode：1 开启飞行模式 ；只有开启飞行模式，才会显示该字段
flightJoinTime：飞行模式开启期间，消费者真实的入会时间
入会方式说明：
channel:memberCode + source:offline + storeId + employeeNo = 导购码入会
source：online + channel：memberCode = 会员码入会
source：online + channel：brandSite = 品牌号入会
source：online + channel：shop = 天猫旗舰店入会
source：offline + channel：scanCode + storeId = 扫门店码入会
source：offline + channel：memberCode + storeId = 支付成功页入会
请求示例： { "seller_name": "天猫魔盒", "taobao_nick": "super", "mix_mobile": "132xxxxx" }
请求返回结果（所有字段均为必选）
| 名称 | 类型 | 描述 | 是否必填 |
| register_code | 字符串 | SUC:完成注册 E01:系统异常，可重试 E02:注册失败，非品牌会员，不可注册 E03:注册失败，已被其他用户注册 E04:注册失败，该帐号已经注册 其他原因可传F01，F02等， 系统统一识别为不可绑定 | 是 |
| member | 复杂类型 | 会员信息，见下表 | 是 |
member信息：
| 名称 | 类型 | 描述 | 是否必填 |
| point | 数字 | 积分数值 | 是 |
| level | 数字 | 会员等级 | 是 |
| nick | 字符串 | 用户的淘宝nick | 是 |
| extend | 字符串 | json对象，如果商家有卡号需要同步落支付宝卡包，可以回传 "card_no":"10000"；一般建议直接传空值 | 否 |
| mobile | 会员手机号 | 会员明文手机号码 | 是 |
返回值示例： {"register_code":"SUC","member":{"point":"2000","extend":"{/"card_no/":/"1000001/"}","level":"1","mobile":"15088551672"}}
2.4 查询请求
SPI名称 tmall.mei.crm.query
场景说明 品牌方务必实现该接口，用于查询会员信息，校验会员中心和品牌方会员信息的一致性。
请求查询参数
| 名称 | 类型 | 描述 |
| seller_name | 字符串 | 卖家昵称 |
| nick | 字符串 | 淘宝昵称；注册用户查询无该字段 |
| mobile | 字符串 | 明文手机号码（限部分商家使用） |
请求示例body：
查询绑定类型的用户： { "seller_name": "天猫魔盒", "nick": "zhangsan", "mobile": "15088890012" }
查询注册类型的用户： { "seller_name": "天猫魔盒", "nick": "super" }
请求返回结果（所有字段均为必选）
| 名称 | 类型 | 描述 | 是否必填 |
| member | 复杂类型 | 会员信息，见下表 | 是 |
| query_code | 字符串 | 绑定结果代码： SUC:完成绑定 E01:不存在的会员 E02:会员未绑定 E04:系统异常，查询失败，可重试。 其他原因可传E05，E06等， 系统统一识别为查询失败 | 是 |
member信息：
| 名称 | 类型 | 描述 | 是否必填 |
| point | 数字 | 积分数值 | 是 |
| level | 数字 | 会员等级 | 是 |
| nick | 字符串 | 用户的淘宝nick | 是 |
| extend | 字符串 | json对象，如果商家有卡号需要同步落支付宝卡包，可以回传 "card_no":"10000"；一般建议直接传空值 | 是 |
| mobile | 会员手机号 | 会员明文手机号码 | 是 |
返回值示例： {"query_code":"SUC","member":{"point":"2000","extend":"{/"card_no/":/"1000001/"}","level":"1","mobile":"15088551672"}}
2.5支付识别接口（选做）
API名称 tmall.mei.crm.member.getbypaycode( 支付码获取会员信息 )
使用场景 线下消费者去使用会员码需要识别会员身份并把权益核销 输入参数
| 名称 | 类型 | 描述 | 是否必须 |
| pay_code | 字符串 | 会员码 | 是 |
输出参数
| 名称 | 类型 | 描述 | 是否必须 |
| result | ResultDTO | result | 是 |
| buyer_nick | 字符串 | 消费者nick | 消费者真实nick |
| mix_mobile | 字符串 | 加密手机号 | 不是会员(淘宝注册或者绑定过的会员)，给密文手机号 |
| clear_mobile | 字符串 | 真实手机号 | 如果已经是会员（淘宝绑定或者注册会员），会给明文手机号 |
result结构： {"tmall_mei_crm_member_getbypaycode_response":{ "result":{"total":1,"result":{"mix_mobile":"b92ec3fe6b45d0218d05174aa82b5ade","buyer_nick":"nick"}, "code":"0","msg":"msg"}}}
2.6同步会员信息API接口
API名称tmall.mei.crm.member.sync
API调用说明
调用此接口前商家一定要先在客户运营平台设置会员等级，设置链接：https://ecrm.taobao.com/p/member/uniLoyalty.htm?spm=a1za3.8218582
任何时候，可主动使用该接口同步会员信息。
多店铺共用一套积分系统，线下积分变动后，品牌方可以及时调用该接口同步会员信息中最新的积分数据。同时会员中心会主动给消费者发送积分变更消息。
输入参数
| 名称 | 类型 | 描述 | 是否必填 |
| mobile | 字符串 | 明文手机号码 | 是 |
| nick | 字符串 | 明文昵称 | 是 |
| point | 字符串 | 积分数值 | 是 |
| level | 字符串 | 会员等级 | 是 |
| extend | 字符串 | json对象，会员的拓展信息 | 否 |
| version | 字符串 | 版本信息，建议用时间戳(必须保证递增) | 是 |
注：mobile和nick至少必填一个，extend非必填
输出参数
| 名称 | 类型 | 描述 |
| is_success | 布尔 | 是否成功 |
| mei_extra_info | 复杂类型 | 会员信息，见下表 |
mei_extra_info信息：
| 名称 | 类型 | 描述 |
| nick | 字符串 | 淘宝nick |
| mobile | 数字 | 手机号 |
返回示例 仅一种返回示例，具体参考API调用说明。 {"is_success":true,"mei_extra_info":"{"mobile":"138XXXXXX"}"}
错误码
| 错误码 | 错误描述 | 解决方案 |
| isv.invalid-parameter | 参数错误 | 请检查参数后再试 |
| isv.no-support-isv | 不受支持的开发者 | 请联系接口开发提供支持 |
| isv.no-exsit-member | 找不到的用户信息 | 确认会员信息的正确性 |
| isv.invalid-version | 失效的版本 | 更新版本信息再试 |
2.7 积分变更通知消息
消息名称 tmall_mei_pointChange
消息说明 会员中心系统发起的积分变更，比如积分兑换礼品、优惠券、支付宝红包、流量钱包，签到送积分等。
消息输出参数
| 名称 | 类型 | 描述 |
| mobile | 字符串 | 明文会员手机号码,作为变更的查询依据 |
| nick | 字符串 | 明文淘宝昵称 |
| seller_name | 字符串 | 卖家名称 |
| point | 整型 | 变更的积分值，大于零 |
| Type | 数字 | 积分变更类型，1-扣减，2-增加 |
| record_id | 数字 | 记录ID，唯一 |
| biz_type | 字符串 | 详见下面biz_type说明 |
| ext_info | 字符串 | 拓展信息，json格式，根据业务类型有相应格式。 |
biz_type值:
| 权益类型 | 兑换 | 取消兑换 |
| 支付宝红包 | red_packet_exchange | cancel_red_packet_exchange |
| 流量钱包 | flow_wallet_exchange | cancel_flow_wallet_exchange |
| 优惠劵 | coupon_exchange | cancel_coupon_exchange |
| 礼品 | gift_exchange | cancel_exchange |
| 优酷会员卡 | youku_exchange | cancel_youku_exchange |
| 淘票票 | tao_piao_piao_exchange | cancel_tao_piao_piao_exchange |
| 天猫超市卡 | market_coupon_exchange | cancel_market_coupon_exchange |
| 淘金币 | tao_coin_exchange | cancel_tao_coin_exchange |
ext_info结构：
| 名称 | 类型 | 描述 |
| order_id | 字符串 | 订单号，兑换礼品和取消兑换礼品时传入，其他情况为空 |
| biz_detail | 业务描述 | 签到和玩游戏等传入，其他情况为空 |
消息体格式示例
给绑定类型的用户发送： { "nick": "super","mobile": "15089990091", "point": "100", "type": "1","record_id": 3234, "biz_type": "gift_exchange","ext_info": "{\"order_id\":\"VCsdd03289328\"}"}
给注册类型的用户发送： { "nick": "super","mix_mobile": "sadjkajfiasnmdsasdmas","point": "100","type": "1","record_id": 3234,"biz_type": "gift_exchange","ext_info": "{\"order_id\":\"VCsdd03289328\"}"}
2.8 积分变更回调API接口
API名称tmall.mei.crm.callback.point.change
API调用说明 处理完积分变更业务后，发起该调用返回业务处理结果。该回调无须立刻处理，暂无失效时间。等业务确认完毕后，再进行回调即可。
特别说明：用户付款成功后，积分变更扣减消息会发送给品牌方处理，品牌方如果对消息处理过慢，如果此时商家的订单已经是已发货阶段，则取消订单会失败。请品牌方系统及时消费积分变更消息并向会员中心系统确认该消息。
注：返回的数据增加买家现有的积分数据，会员中心系统不会主动查询买家积分，需要品牌方在积分变动后把现有的积分总数同步给会员中心系统。 输入参数
| 名称 | 类型 | 描述 | 是否必须 |
| mix_mobile | 数值 | 加密手机号码 | 否 |
| record_id | 数值 | 记录ID | 是 |
| Result | 数值 | 0-成功，1-失败 | 是 |
| error_code | 字符串 | 处理失败的错误码. | 否 |
| point | 数值 | 买家现有的品牌积分(变更之后最新) | 否 |
| ext_info | 字符串 | 拓展信息，json格式，根据业务类型有相应格式。 | 否 |
错误：
| 错误码 | 描述 |
| no-exsit-member | 不存在的会员 |
| deduct-fail:point-no-enough | 扣减失败：积分不足 |
| deduct-fail:no-exist-order | 扣减失败：不存在的订单 |
| deduct-fail:order-illegal | 扣减失败：非法的订单 |
| deduct-fail:other | 扣减失败：其他原因 |
| increase-fail | 累加积分失败（这个场景表现为取消订单，返还积分） |
注：我们不希望有累加积分失败的错误返回，这个错误意味系统异常了。如订单已完成，我们不会发起返回的。
record_id为唯一标识，也就意味着，如果消息接收场景中，会员中心透传给品牌商明文的nick等信息，品牌商根据自己的业务场景使用该信息，但消息回调这里不需要传入明文nick等非必要信息。
输出参数 无
错误码
