CRM类应用处理方案

一、背景说明

近期国家陆续出台了个人信息保护和数据安全相关的法律法规，对保障消费者个人信息权益、规范数据处理活动提出了更明确的责任要求。平台将启动订单链路的消费者敏感信息保护方案，对涉及消费者个人敏感信息采取加密、去标识化等安全技术措施。

新的方案将会把订单中涉及消费者的敏感信息进行处理，订单中消费者敏感信息主要为消费者订单中的收件人信息。CRM应用中的原有订单接口将被回收，平台将提供新的不包含：Buyer_nick、收件人姓名、收件人手机号、收件人电话(固定号码)、收件人详细地址（不包含省市）等字段的订单接口，用以支持客户管理等业务场景。

而为了确保商家CRM对客户进行管理、运营、服务等相关业务正常运行，平台将在接口中新增CRM系统用于识别用户的ID字段【Open User ID，简称ouid】，此ouid为全新ID，同一用户在同一店铺中此ID唯一（无论是在哪个app中）。同时对会员通业务中，增加一个用于跨多品牌多店的用户唯一ID【Open Merchant User ID，简称omid】，注意omid需要是会员通中的注册入会用户才能获取。

ouid、omid为本次升级新增的核心字段，升级后CRM系统可以利用其进行用户识别、管理、运营、服务等业务。以此保障CRM原有业务链路正常运行，同时确保消费者隐私信息得到保护。

二、方案概述

1.CRM类目开发者从淘宝开放平台API或推送服务中将不能再获取到订单中的消费者敏感信息（Buyer_nick、收件人姓名、收件人手机号、收件人电话、地址等），原从老订单接口中获取的存量收件人消费者敏感信息（以上字段）需要删除，同时平台将提供新的不包含敏感字段的订单接口，用以支持客户管理等业务场景。

2.在店铺内用户的识别可以通过ouid，有多店的可以通过会员通中获取到的omid联合ouid做用户识别。

3.涉及必要通知服务以及会员运营需要发送短信的，可以使用ouid通过淘宝开放平台提供的密文发送短信接口来实现。

4.为了支持CRM能够对会员通商家多店的客户进行跨店识别，提供ouid转omid的转化接口，用于跨店识别同一用户做用户管理及分析。

5.CRM服务商原存量数据处理，将临时提供nick转ouid能力，支持将原存量数据进行清洗。

改造前后链路变化情况：

改造前：三方CRM有订单权限，能够获取用户手机号及nick，通过nick进行用户识别和分析，利用订单中收件人手机号发短信等。

改造后：回收订单中敏感权限（并与交易链路解耦），提供新接口。三方CRM获取消费者信息走会员主动授权入会链路，官方CRM提供ouid密文发送短信能力。

三、升级实施流程

请通过【淘宝开放平台后台 -> 支持 -> 平台通知 -> 待办任务】，查询平台下发的升级任务。

未接收到改造任务，可在【淘宝开放平台后台 -> 支持 -> 服务中心 -> 提交工单】页面提交：隐私保护升级任务申请。

实施操作流程

请结合实施方案涉及的改造点内容所涉及的接口、功能点环节做技术方案产出后，依据如下的实施流程开启升级改造。并在任务中心同步推进每个节点的进展。平台会在过程中关注每个服务商实时所处的环节和节点，并在需要时提供对应的实施咨询和支持帮助。

四、涉及接口和字段说明

注意原APP中没有的API此次更改后也不会单独提供，将按原有权限范围进行调整。

涉及改造接口总览如下。

1. 订单相关API

1）将回收以下接口

① taobao.trade.fullinfo.get（获取单笔交易的详细信息）；

② taobao.trades.sold.increment.get（查询卖家已卖出的增量交易数据（根据修改时间））；

③ taobao.trades.sold.get（查询卖家已卖出的交易数据（根据创建时间））；

④ taobao.trade.get（获取单笔交易的部分信息(性能高)，直接回收，该接口不提供替换接口）。

2）新增接口

API名称：taobao.trade.simple.get（获取单笔交易的详细信息）。

入参改动：不变。

出参改动：减少消费者敏感信息，增加用户唯一身份标示字段。

去掉字段：

新增字段：

其他字段参照现有taobao.trade.fullinfo.get接口定义。

API名称：taobao.trades.simple.sold.get（查询卖家已卖出的交易数据（根据创建时间））

入参

去掉字段：

新增字段：

出参

去掉字段：

新增字段：

其他字段参照现有 taobao.trades.sold.get接口定义。

API名称：taobao.trades.simple.sold.increment.get（查询卖家已卖出的增量交易数据（根据修改时间））

入参

去掉字段：

新增字段：

出参

去掉字段：

新增字段：

其他字段参照现有 taobao.trades.sold.increment.get接口定义。

3）修改以下接口

① taobao.traderates.get（搜索评价信息）；

② tmall.traderate.feeds.get（查询子订单对应的评价、追评以及语义标签）；

③ taobao.refunds.receive.get（查询卖家收到的退款列表）；

④ taobao.refund.get（获取单笔退款详情）;

⑤ taobao.logistics.orders.get（批量查询物流订单）；

⑥ taobao.logistics.orders.detail.get（批量查询物流订单,返回详细信息）。

改动点：

入参有buyerNick/buyer_open_id替换成ouid；

出参如果有nick/user_nick/buyerNick，则增加ouid，改造完成后屏蔽nick/user_nick/buyerNick；

taobao.traderates.get 接口出参获取Ouid，需要在入参的fields里带上nick ；

taobao.refund.get 接口出参获取Ouid，需要在入参的fields里带上buyer_nick 。

i）taobao.logistics.orders.get（批量查询物流订单）

ii）taobao.logistics.orders.detail.get（批量查询物流订单,返回详细信息）

以上2个接口返回的出参中相关的字段不再开放收货人敏感信息。

2. CRM及会员相关API

1）修改以下接口

注意表格中未标注新接口的，均使用原接口改造，出入参如果有buyerNick，则增加ouid，改造完成后屏蔽buyerNick；如果标注有新接口的，则明确后续用新接口替代老接口，灰度阶段两个接口共存，改造完后回收老接口。、

CRM

会员

2）CRM新增接口

3）删除以下接口

3. 营销相关API

1）修改以下接口

① taobao.promotion.coupon.send（店铺优惠券发放接口）

② tmall.promotag.taguser.remove（给用户移除优惠标签）

③ tmall.promotag.taguser.save（给用户打上优惠标签）

④ tmall.promotag.taguser.judge（用户标签判断接口）

⑤ taobao.promotion.benefit.activity.send（活动权益发放接口）

改动点：

入参增加ouid，

出参如果有buyerNick，则增加ouid，改造完成后屏蔽buyerNick。

4. 其他API

1）新增以下接口

taobao.weitao.follow.isrelation（微淘是否关注）替代taobao.weitao.feed.isrelation。

2）删除以下接口

taobao.mixnick.change（新旧mixnick互转）

五、通用场景升级说明

5.1 订单查询

1）Top API链路

crm自行切换商家进行灰度（灰度策略和开放平台任务中心保持一致），出参中包含buyerNick和ouid的api，默认不设置灰度策略，即buyerNick和ouid并存。但会员相关的api会对灰度商家隐藏buyerNick，建议改造过程中，crm忽略灰度商家接口调用返回的buyerNick。

2）推送改造

1.关于数据推送（开通和使用）

点击查看

2.rds拉单改造

crm交易权限回收后，api-sdk中不在有taobao.trade.fullinfo.get对应的类，而推送RDS中jdp_response报文仍为trade_fullinfo_get_response结构，对于使用sdk解析jdp_response数据的用户，拉单程序需要特殊处理。

{
"trade_fullinfo_get_response": {
"trade": {
"tid": 123
"tid_str": "123"
}
}
}

改造方案：

crm会增加新查询接口taobao.trade.simple.get，需要使用此接口对应的SDK中TaobaoResponse类。

TradeSimpleGetResponse进行解析，具体方式如下：

String jdpResp = "{\n" + 
"\t\"trade_fullinfo_get_response\": {\n" +
"\t\t\"trade\": {\n" +
"\t\t\t\"tid\": 123,\n" +
"\t\t\t\"tid_str\": \"123\"\n" +
"\t\t}\n" +
"\t}\n" +
"}";
JSONObject apiResp = JSON.parseObject(jdpResp);
JSONObject tradeBody = apiResp.getJSONObject("trade_fullinfo_get_response");
//Trade对象来自taobao.trade.simple.get对应的TaobaoResponse中的Trade类
Trade trade = JSON.parseObject(tradeBody.getString("trade"), Trade.class);
System.out.println(trade.getTid());

3）数据推送链路

数据推送不支持商家维度灰度，只能全量切换，crm在推送库转业务库的期间，需要根据灰度商家做调整。

1.对于灰度店铺，从推送库中获取订单后，需要查询新交易接口获取数据，使用新交易接口数据做业务处理（rds中数据还是老的api数据，没有ouid）。

2.全量店铺灰度完成后，对推送链路做切换（这个步骤不支持灰度，只能全量切），切换后增量变更数据有ouid，可以直接使用做业务处理，不再需要通过api回补。

伪代码示例：

List<Trade> trades =
(   select tid,jdp_response from sys_info.jdp_tb_trade where jdp_modified>= time_start
and jdp_modified<=time_end);
for(Trade trade:trades){
if(trade.ouid != null){
do work;
}else{
trade = ( get api from ?taobao.trade.simple.get );
do work;
}
}

5.2 用户识别

未来CRM应用的订单接口将不再提供用户隐私信息，但会获取一个ouid，指在一个商家中的唯一用户ID。即同一个用户，只要在同一个商家中，其获取到的ouid都是一样的。

场景示例：CRM应用对用户交易进行等级/积分计算，通过ouid去关联识别，但无法获取到个人用户信息。

5.3 跨店用户识别

对会员通业务中，增加一个用于跨多店的用户唯一ID【Open Merchant User ID，简称omid】，其中一个商业主体可以对应多个品牌，品牌也分别可以对应多个店铺，在会员通申请时，会要求提供此商业体和店铺的关联关系。此omid只要在同一个品牌主体中，在此商业体下关联的任意店，其获取到的omid都是一样的。

场景示例：对用户在品牌多店的用户身份进行统一分析，并对用户在多店内交易进行汇总的积分扣减。

5.4 短信服务

5.4.1 短信服务开通及配置

开发前对接流程如下。

服务商获取平台通过ouid发送短信的能力，需要提前向小二提交以下信息：

应用名；

appkey；

申请appkey的淘宝账号（nick或id）；

全变量模版信息（tpl_code：申请的短信模板ID，tpl_plh：申请的短信模板占位符），需要提供截图；

服务商公司名称、服务商接口人及联系电话、邮箱。

信息提交请发送邮件至wb-syl580498@alibaba-inc.com，抄送jishu.zr@alibaba-inc.com。

全变量模版信息截图示意如下。

1.申请全变量模板流程全变量权限

开通后可支持申请全变量模板，如${content}，该模板可支持自定义内容发送。其中${content}为需要提交信息中的模版占位符信息。

①发送邮件至xuanyu.hc@alibaba-inc.com，内容注明开放平台淘宝账号名称、接口人联系人及联系电话，内部对于短信内容安全的管控措施，并注明申请短信内容全变量权限开通

②经官方评估后将邮件回复开通结果，如成功开通权限，请于短信服务控制台中，进行对应类型的全变量模板申请（可参考：${content}），并注意区分通知全变量模板和营销全变量模板的使用，混用可能引发短信失败现象

③申请全变量模板成功后，将得到SMS_xxxxxx 的模板ID，用于接口中的对应字段填写使用

2.申请免签流程

免签权限：开通后可支持接口传商家签名发送（开放平台本身的签名审核流程不变）

①发送邮件至xuanyu.hc@alibaba-inc.com，内容注明开放平台淘宝账号名称、接口人联系人及联系电话，内部对于短信签名使用及审核的管控措施，并注明申请短信全变量模板ID

②经官方评估后将邮件回复开通结果，开通后ISV服务商可进行接口传递签名发送（但前提仍需向平台提交签名审核，审核通过后才能执行对应签名发送使用）

任务发送示例：服务商先申请全变量权限并添加全变量模板，同时邮件报备全变量模板及开通免签能力，正式发送时需先向平台控制台上进行签名添加申请，申请后采用接口模式传递签名+全变量模板短信内容，进行短信最终下发。

5.4.2 短信能力对接说明

5.4.2.1 短信单点投放接口

top接口名

taobao.opencrm.sms.single.send

接口说明

该接口是基于ouid的单点投放接口，可以使用该接口发送1-100个人的短信，以日账单的形式3日之后通过消息返回账单消息。

接口入参

out_node_inst_id, 外部结点实例ID，由调用方控制唯一性，每次调用都传入一个新的唯一值，用来作为双方的调用唯一键标识。

msg_type参数 用来表示短信的类型，示例值：1

1 : 服务类短信

2 : 营销类短信

mobile_acquisition_rule列表参数，用来自定义手机号获取规则，列表中的参数顺序即为手机号获取方式顺序。示例值：[3,1,2]。该参数为可选参数，如果不传，营销类短信默认为 [1]，服务类短信默认为[1,2]。

1 : 通过会员关系获取手机号

2：通过最新订单获取常用手机号（两年内）

3：通过指定订单获取手机号（三个月内）

logistics_order_id_list列表参数，用来在mobile_acquisition_rule中包含3时，为每一位deliver_targets传递指定订单号，注意的是，deliver_targets的大小和logistics_order_id_list必须相同，且传入ouid和订单对应为同一买家时才能获取到手机号

参数seller_tpl中，不能写入URL链接(不论是长链还是短链)，否则将无法通过调用校验，发送失败。

参数plh_val中，必须为每一个链接类占位符提供相应的链接值，且提供的链接需要符合白名单，否则将发送失败。

白名单：["taobao.com","tmall.com","jaeapp.com","tmall.hk","g.alicdn.com","taobao.net","tmall.net","etao.com","m.duanqu.com"]

接口出参

整个接口链路的返回说明

1）在调用接口时，通过result出参同步返回接口对入参的初步校验，如果result为false，则可以判断接口调用失败，检查参数正确性。

2）调用接口成功后，会对接口入参做进一步的校验，默认成功，如果校验参数有误，则会通过TMC消息taobao_opencrm_Feedback返回校验勘误消息，并通过type:3标识消息类型。

3）在短信发送阶段，如果被限制或发送失败，则会通过taobao_opencrm_Feedback消息返回相应的ouid，并通过type:1表示消息类型。

4）在短信回执阶段，会通过taobao_opencrm_Feedback消息返回明细，以ouid标识，并且通过type:2表示消息类型。

5.4.2.2 短信人群通投接口

功能迭代中，预计830提供。

短信签名增加删除

1）商家的短信签名appkey全局唯一；

2）商家变更店铺名称后可重新申请签名，但是新的签名生效后，之前的店铺签名作废；

3）如提示短信签名被占用，联系 @奈量；

4）接口不支持删除操作。

接口信息

taobao.opencrm.signature.adddelete

接口入参

接口出参

无

短信签名查询

接口信息

taobao.opencrm.signature.query

接口入参

接口出参

短信占位符使用

全变量模板对应的短信内容需要放在参数seller_tpl中，例如参数示例“亲爱的${nick}， 兜家年货清仓五折起咯”，占位符即使用${*}的形式来使用占位符值将短信内容替换成具体的占位符值，*为具体的占位符符号。其中，占位符分为需要传递值和不需要传递值两种，不需要传递值的占位符由官方根据ouid生成。需要传递的占位符值则放在参数plh_val中，例如参数示例

{"nick":"jinse01","point":"10","gradeName":"普通会员","shortLink":"c.tb.cn/c.Kgsf"}。占位符列表如下。

单条短信反馈消息

taobao_opencrm_Feedback消息说明：

type:1，发送阶段返回被限制和失败目标人，消息体字段：

node_inst_id（外部结点实例id, 同接口传入值out_node_inst_id）

type:1

content

ouid

status 0-受限制 3-发送失败

errorCode 错误码

type:2，回执阶段返回发送明细，消息体字段：

node_inst_id（外部结点实例id, 同接口传入值out_node_inst_id）

type:2

content

ouid

status 1-成功，2-失败

errorCode 错误码

sendTime 消息发送时间

bill_count 短信条数

type:3，调用接口成功后进一步校验阶段，消息体字段：

node_inst_id（外部结点实例id, 同接口传入值out_node_inst_id）

type:3

content

errorCode 错误码

errorMsg 错误信息

出账说明： 在短信发送的三个自然日之后，通过定时消息返回三天前整天发送短信的日账单。

短信账单消息

TMC消息

taobao_opencrm_ShortMessageBill

智能营销短信节点执行成功，3天后发送智能营销账单。

事件关怀短信账单，每天凌晨1天发送往前数第三天的账单，比如7月25日凌晨1时发送7月22日短信账单。

消息体

注：发送失败短信阿里通信不计费。?

5.4.3 CEM平台版服务商短信能力说明

注意此部分仅限CEM平台版服务商涉及改造。

基于ouid的单点投放新接口

接口名

taobao.opencrm.sms.single.post

接口说明

该接口是基于ouid的单点投放接口。相比较于旧版单点投放接口taobao.opencrm.sms.post，在接口的出入参和消息返回机制上都有变化。

--在接口入参方面，task_content有以下变化：

deliver_targets 由传递nick列表，修改为传递ouid列表。

新增加msg_type参数 用来表示短信的类型，示例值：1

1 : 服务类短信

2 : 营销类短信

新增加mobile_acquisition_rule列表参数，用来自定义手机号获取规则，列表中的参数顺序即为手机号获取方式顺序。示例值：[3,1,2]。该参数为可选参数，如果不传，营销类短信默认为 [1]，服务类短信默认为[1,2]。

1 : 通过会员关系获取手机号

2：通过最新订单获取手机号（两年内）

3：通过指定订单获取手机号（三个月内）

新增加logistics_order_id_list列表参数，用来在mobile_acquisition_rule中包含3时，为每一位deliver_targets传递指定订单号，注意的是，deliver_targets的大小和logistics_order_id_list必须相同，且传入ouid和订单对应为同一买家时才能获取到手机号。

参数seller_tpl中，不能再写入URL链接(不论是长链还是短链)，否则将无法通过调用校验，发送失败。

参数plh_val中，必须为每一个链接类占位符提供相应的链接值，且提供的链接需要符合白名单，否则将发送失败。

白名单：["taobao.com","tmall.com","jaeapp.com","tmall.hk","g.alicdn.com","taobao.net","tmall.net","etao.com","m.duanqu.com"]

--在接口出参方面，有以下变化：

result参数改为Boolean对象，其结果表示是否通过的接口的参数初步校验，如果失败，则有相应的result_error_code和result_error_msg返回。

--整个接口链路的返回说明：

1）在调用接口时，通过result出参同步返回接口对入参的初步校验，如果result为false，则可以判断接口调用失败，检查参数正确性。

2）调用接口成功后，会对接口入参做进一步的校验，默认成功，如果校验参数有误，则会通过TMC消息taobao_opencrm_Feedback返回校验勘误消息，并通过type:3标识消息类型。

3）在短信发送阶段，如果被限制或发送失败，则会通过taobao_opencrm_Feedback消息返回相应的ouid，并通过type:1表示消息类型。

4）在短信回执阶段，会通过taobao_opencrm_Feedback消息返回明细，以ouid标识，并且通过type:2表示消息类型。

--taobao_opencrm_Feedback消息说明：

type:1，发送阶段返回被限制和失败目标人，消息体字段：

node_inst_id

type:1

content

ouid

status

errorCode

type:2，回执阶段返回发送明细，消息体字段：

node_inst_id

type:2

content

ouid

status

errorCode

sendTime

bill_count

type:3，调用接口成功后进一步校验阶段，消息体字段：

node_inst_id

type:3

content

errorCode

errorMsg

接口入参

接口出参

人群投放接口

接口名：taobao.opencrm.sms.crowd.post

功能迭代中，预计830提供。

5.5 历史数据清洗

新增Nick转ouid，Nick转omid接口

taobao.crm.history.ouid.get

关于调用条件和调用上限控制请参考FAQ。

taobao.crm.history.omid.get

转化条件：当前商家是会员通商家，且用户在UIC判断为品牌会员。否则转化失败。

关于调用条件和调用上限控制请参考FAQ。

5.6 CRM人群相关接口

新增ouid方式上传接口，兼容老接口能力，并且删除nick上翻数据方式。

taobao.opencrm.ctag.upload --> taobao.opencrm.ctag.upload.privy

taobao.opencrm.crowd.upload.bach --> taobao.opencrm.crowd.upload.bach.privy

5.6.1 标签上翻

API名称： taobao.opencrm.ctag.upload.privy

API入参

API出参

5.6.2 人群上翻

API名称：taobao.opencrm.crowd.upload.bach.privy

API入参

API出参

六、灰度验证说明

本环节需要结合任务中心的改造任务节点，来做相应的衔接。整体的改造流程节点图如下：其中标红的几个节点的含义以及需要服务商进行对应的设置动作，在下文逐一进行说明。

6.1 CRM应用代码升级开发

此环节不会在任务节点上体现，红框标出说明，主要是告知服务商在研读技术方案和计划提交之后，是需要先完成升级或改造代码的调整和开发编写工作，完成代码开发是后面节点开始的前提。

6.2 提交配置测试店铺&API测试验证确认

a.提交配置测试店铺

从提交配置测试店铺节点开始，就进入灰度测试验证阶段。

简单说明定义的灰度模式，细分为3种：商家白名单形式，商家取模（线上铺量）形式，全量切换形式。

当前开始着手的提交配置测试店铺节点，属于灰度中的商家白名单形式。在此步骤需要服务商填写自己可以用来做测试验证的商家店铺。平台侧收到商家的配置，会将原来调用的老接口中要替换的字段进行替换，同时服务商侧需要自行切换对应店铺流量调用新接口，从新接口获取数据。此步骤用于验证应用可以接收本次改造新增接口的数据，以及老接口上字段调整的接收和逻辑适配。

b.API测试验证确认

在提交配置测试店铺做完相应的接口切换和字段适配，服务商开始进行数据的获取和内容测试验证，当确保单店铺测试没有问题的情况下，在API测试验证确认节点点击确认。表示单店铺的功能测试验证没有问题，开始推进下一个节点的工作。PS：提交配置测试店铺页面提供回滚功能，如发现切换有问题可在页面剔除配置店铺。然后平台侧老接口字段回切，服务商侧可以视情况是否将调用新接口换回老接口。待二次代码调整无误再重新配置推进测试验证。

6.3 线上多店铺API验证&按比例灰度验证

a.线上多店铺API验证

此环节依然是灰度验证中的白名单形式，相比之前的提交配置测试店铺环节，此节点我们在切换API后可以加入更多的线上店铺进行测试验证，目的是将测试范围扩大，通过多店铺验证链路是否有未覆盖到的问题和风险。

b.按比例灰度验证

此环节是对应灰度验证中的商家取模（线上铺量）形式，按照10000取模百分比形式切换店铺流量测试，当填入10000表示100%灰度，所有应用覆盖的店铺都切换。请谨慎执行。

6.4 RDS推送调整验证&RDS全量结构切换

a.RDS推送调整验证

此步骤主要完成单点验证RDS推送数据结构变更后的数据获取，服务商侧确认是否能兼容。

具体方案参考：本文档中的五、通用场景升级说明中的5.1、订单查询。

b.RDS全量结构切换

此步骤是执行整个RDS数据结构切换到新结构的操作，请在前序验证和确认都无误后在提交此节点的操作。此步骤涉及RDS的重大结构调整变更，执行前务必反复确认和谨慎触发。