基础技术
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 |
taobao.trade.fullinfo.get |
taobao.trade.simple.get |
替换 |
2 |
taobao.trades.sold.increment.get |
taobao.trades.simple.sold.increment.get |
替换 |
3 |
taobao.trades.sold.get |
taobao.trades.simple.sold.get |
替换 |
4 |
taobao.trade.get |
回收 |
|
5 |
taobao.traderates.get |
修改 |
|
6 |
tmall.traderate.feeds.get |
修改 |
|
7 |
taobao.refunds.receive.get |
修改 |
|
8 |
taobao.refund.get |
修改 |
|
9 |
taobao.logistics.orders.get |
修改 |
|
10 |
taobao.logistics.orders.detail.get |
修改 |
|
11 |
taobao.opencrm.ctag.upload |
taobao.opencrm.ctag.upload.privy |
替换 |
12 |
taobao.opencrm.crowd.upload.bach |
taobao.opencrm.crowd.upload.bach.privy |
替换 |
13 |
taobao.opencrm.sms.post |
taobao.opencrm.sms.single.post |
替换 |
14 |
TMC_TOPIC_FEEDBACK |
修改 |
|
15 |
taobao.crm.members.increment.get |
taobao.crm.members.increment.get.privy |
替换 |
16 |
taobao.crm.members.search |
taobao.crm.members.search.privy |
替换 |
17 |
taobao.crm.members.get |
taobao.crm.members.get.privy |
替换 |
18 |
taobao.crm.membergrade.set |
taobao.crm.membergrade.set.privy |
替换 |
19 |
taobao.crm.memberinfo.update |
taobao.crm.memberinfo.update.privy |
替换 |
20 |
taobao.crm.member.identity.get |
taobao.crm.member.identity.get.privy |
替换 |
21 |
tmall.crm.member.front.unbind |
tmall.crm.member.front.unbind.privy |
替换 |
22 |
taobao.crm.point.available.get |
taobao.crm.point.available.get.privy |
替换 |
23 |
taobao.crm.point.change |
taobao.crm.point.change.privy |
替换 |
24 |
taobao.opencrm.point.detail.query |
taobao.opencrm.point.detail.query.privy |
替换 |
25 |
taobao.opencrm.point.update |
taobao.opencrm.point.update.privy |
替换 |
26 |
taobao.opencrm.member.get |
taobao.opencrm.member.get.privy |
替换 |
27 |
taobao.opencrm.point.available.query |
taobao.crm.point.available.get.privy.cp |
替换 |
28 |
taobao.crm.members.group.batchadd |
taobao.crm.members.group.batchadd.privy |
替换 |
29 |
taobao_opencrm_MemberJoin |
taobao_opencrm_MemberJoinPrivate |
替换 |
30 |
taobao.opencrm.member.get.omid |
新增 |
|
31 |
taobao.opencrm.sms.single.send |
新增 |
|
32 |
taobao.opencrm.sms.crowd.post |
新增 |
|
33 |
taobao.opencrm.coupon.send |
回收 |
|
34 |
taobao.opencrm.point.send |
回收 |
|
35 |
taobao.opencrm.sms.qresult |
回收 |
|
36 |
taobao.promotion.coupon.send |
修改 |
|
37 |
tmall.promotag.taguser.remove |
修改 |
|
38 |
tmall.promotag.taguser.save |
修改 |
|
39 |
tmall.promotag.taguser.judge |
修改 |
|
40 |
taobao.promotion.benefit.activity.send |
修改 |
|
41 |
taobao.weitao.follow.isrelation |
taobao.weitao.feed.isrelation |
替换 |
42 |
taobao.mixnick.change |
回收 |
|
43 |
taobao.opencrm.signature.adddelete |
新增 |
|
44 |
taobao.opencrm.signature.query |
新增 |
|
45 |
taobao_opencrm_Feedback |
新增 |
|
46 |
taobao_opencrm_NodeExecuteFinished |
新增 |
|
47 |
taobao_opencrm_ShortMessageBill |
新增 |
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（获取单笔交易的详细信息）。
入参改动：不变。
出参改动：减少消费者敏感信息，增加用户唯一身份标示字段。
去掉字段：
字段名称 |
类型 |
事例值 |
描述 |
所属结构体 |
buyer_nick |
String |
我在测试 |
买家昵称 |
trade |
receiver_name |
string |
东方不败 |
收货人姓名 |
trade |
receiver_address |
String |
淘宝城911号 |
收货人的详细地址 |
trade |
receiver_mobile |
String |
13512501826 |
收货人的手机号码 |
trade |
receiver_phone |
String |
13819175372 |
收货人的电话号码 |
trade |
新增字段：
字段名称 |
类型 |
事例值 |
描述 |
所属结构体 |
ouid |
String |
7428434234234 |
淘宝买家在当前店铺的唯一标识 |
trade |
其他字段参照现有taobao.trade.fullinfo.get接口定义。
API名称：taobao.trades.simple.sold.get（查询卖家已卖出的交易数据（根据创建时间））
入参
去掉字段：
字段名称 |
类型 |
事例值 |
描述 |
所属结构体 |
buyer_open_id |
String |
3452435234523 |
买家账号openID |
|
buyer_nick |
String |
我在测试 |
买家昵称 |
新增字段：
字段名称 |
类型 |
事例值 |
描述 |
所属结构体 |
ouid |
String |
7428434234234 |
淘宝买家在当前店铺的唯一标识 |
出参
去掉字段：
字段名称 |
类型 |
事例值 |
描述 |
所属结构体 |
buyer_nick |
String |
我在测试 |
买家昵称 |
trades |
receiver_name |
string |
东方不败 |
收货人姓名 |
trades |
receiver_address |
String |
淘宝城911号 |
收货人的详细地址 |
trades |
receiver_mobile |
String |
13512501826 |
收货人的手机号码 |
trades |
receiver_phone |
String |
13819175372 |
收货人的电话号码 |
trades |
新增字段：
字段名称 |
类型 |
事例值 |
描述 |
所属结构体 |
ouid |
String |
7428434234234 |
淘宝买家在当前店铺的唯一标识 |
trades |
其他字段参照现有 taobao.trades.sold.get接口定义。
API名称：taobao.trades.simple.sold.increment.get（查询卖家已卖出的增量交易数据（根据修改时间））
入参
去掉字段：
字段名称 |
类型 |
事例值 |
描述 |
所属结构体 |
buyer_open_id |
String |
3452435234523 |
买家账号openID |
|
buyer_nick |
String |
我在测试 |
买家昵称 |
新增字段：
字段名称 |
类型 |
事例值 |
描述 |
所属结构体 |
ouid |
String |
7428434234234 |
淘宝买家在当前店铺的唯一标识 |
出参
去掉字段：
字段名称 |
类型 |
事例值 |
描述 |
所属结构体 |
buyer_nick |
String |
我在测试 |
买家昵称 |
trades/order |
receiver_name |
string |
东方不败 |
收货人姓名 |
trades |
receiver_address |
String |
淘宝城911号 |
收货人的详细地址 |
trades |
receiver_mobile |
String |
13512501826 |
收货人的手机号码 |
trades |
receiver_phone |
String |
13819175372 |
收货人的电话号码 |
trades |
新增字段：
字段名称 |
类型 |
事例值 |
描述 |
所属结构体 |
ouid |
String |
7428434234234 |
淘宝买家在当前店铺的唯一标识 |
trades |
其他字段参照现有 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
老接口 |
新接口 |
变更点 |
taobao.opencrm.ctag.upload |
taobao.opencrm.ctag.upload.privy |
nick改ouid |
taobao.opencrm.crowd.upload.bach |
taobao.opencrm.crowd.upload.bach.privy |
nick改ouid |
taobao.opencrm.sms.post |
taobao.opencrm.sms.single.post |
灰度阶段两个接口共存，新接口入参deliverTargets由nick队列改为ouid队列，并且接口入参新增加了业务参数。此外接口出参不再返回nick队列，而是返回接口是否调用成功，具体参考接口说明。 |
消息 |
||
TMC_TOPIC_FEEDBACK |
老接口升级 |
消息体nick字段改为ouid字段，并且新增type:3 表明单条发送接口调用失败消息 |
会员
老接口 |
新接口 |
变更点 |
taobao.crm.members.increment.get |
取消原nick出参，增加ouid出参 |
|
taobao.crm.members.search |
taobao.crm.members.search.privy |
取消原nick入参，增加ouid入参 取消原nick出参，增加ouid出参 |
taobao.crm.members.get |
taobao.crm.members.get.privy |
取消原nick入参，增加ouid入参 取消原nick出参，增加ouid出参 |
taobao.crm.membergrade.set |
taobao.crm.membergrade.set.privy |
取消原nick入参，增加ouid入参 |
taobao.crm.memberinfo.update |
taobao.crm.memberinfo.update.privy |
取消原nick入参，增加ouid入参 |
taobao.crm.member.identity.get |
taobao.crm.member.identity.get.privy |
原入参nick、mixnick取消，增加ouid入参 |
tmall.crm.member.front.unbind |
tmall.crm.member.front.unbind.privy |
会员通接口待更新 |
taobao.crm.point.available.get |
taobao.crm.point.available.get.privy |
原入参nick、mixnick取消，增加ouid入参 |
taobao.crm.point.change |
taobao.crm.point.change.privy |
会员通接口待更新 |
taobao.opencrm.point.detail.query |
taobao.opencrm.point.detail.query.privy |
原入参nick、mixnick取消，增加ouid入参 |
tmall.mei.crm.member.sync |
tmall.mei.crm.member.sync.privy |
会员通接口待更新 |
taobao.opencrm.point.update |
taobao.opencrm.point.update.privy |
原入参nick取消，增加ouid入参 |
taobao.member.hismemberdata.get |
taobao.member.hismemberdata.get.privy |
会员通接口待更新 |
taobao.opencrm.member.get |
taobao.opencrm.member.get.privy |
原入参nick取消，增加ouid入参 |
taobao.opencrm.point.available.query |
taobao.crm.point.available.get.privy.cp |
原入参nick、mixnick取消，增加ouid入参 |
taobao.crm.members.group.batchadd |
taobao.crm.members.group.batchadd.privy |
原入参buyer_nicks取消，增加ouids入参 |
tmall.crm.member.point.change |
会员通接口待更新 |
|
tmall.mei.crm.callback.point.change |
会员通接口待更新 |
|
alibaba.member.cem.exit |
会员通接口待更新 |
|
SPI |
||
tmall.mei.crm.member.bind.query |
会员通接口待更新 |
|
tmall.mei.crm.bind |
会员通接口待更新 |
|
tmall.mei.crm.member.register |
会员通接口待更新 |
|
tmall.mei.crm.query |
会员通接口待更新 |
|
消息 |
||
taobao_opencrm_MemberJoin |
taobao_opencrm_MemberJoinPrivate |
新增消息，内容改动点：原contentMap中，key为user的value由buyer_nick改为ouid |
tmall_mei_PointChange |
会员通接口待更新 |
|
2）CRM新增接口
taobao.opencrm.member.get.omid |
获取omid |
taobao.opencrm.sms.single.send |
短信发送接口 |
taobao.opencrm.sms.crowd.post |
人群短信发送（注：仅限CEM-B版服务商） |
3）删除以下接口
taobao.opencrm.coupon.send |
优惠券发放 |
已禁用 |
taobao.opencrm.point.send |
积分发放 |
todo禁用 |
taobao.opencrm.sms.qresult |
查询主动营销投放明细 |
todo禁用 |
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互转）
四、通用场景升级说明
4.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;
}
}
4.2 用户识别
未来CRM应用的订单接口将不再提供用户隐私信息，但会获取一个ouid，指在一个商家中的唯一用户ID。即同一个用户，只要在同一个商家中，其获取到的ouid都是一样的。
场景示例：CRM应用对用户交易进行等级/积分计算，通过ouid去关联识别，但无法获取到个人用户信息。
4.3 跨店用户识别
对会员通业务中，增加一个用于跨多店的用户唯一ID【Open Merchant User ID，简称omid】，其中一个商业主体可以对应多个品牌，品牌也分别可以对应多个店铺，在会员通申请时，会要求提供此商业体和店铺的关联关系。此omid只要在同一个品牌主体中，在此商业体下关联的任意店，其获取到的omid都是一样的。
场景示例：对用户在品牌多店的用户身份进行统一分析，并对用户在多店内交易进行汇总的积分扣减。
4.4 短信服务
4.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服务商可进行接口传递签名发送（但前提仍需向平台提交签名审核，审核通过后才能执行对应签名发送使用）
任务发送示例：服务商先申请全变量权限并添加全变量模板，同时邮件报备全变量模板及开通免签能力，正式发送时需先向平台控制台上进行签名添加申请，申请后采用接口模式传递签名+全变量模板短信内容，进行短信最终下发。
4.4.2 短信能力对接说明
4.4.2.1 短信单点投放接口
top接口名
taobao.opencrm.sms.single.send
接口说明
该接口是基于ouid的单点投放接口，可以使用该接口发送1-100个人的短信，以日账单的形式3日之后通过消息返回账单消息。
接口入参
名称 |
参数类型/SDK类型 |
是否必须 |
示例值 |
描述 |
task_content |
ShortMessageDeliverTaskContent |
必须 |
短信息任务参数集合 |
|
└ tpl_plh |
String |
必须 |
content |
聚石塔申请的短信模板占位符 |
└ seller_tpl |
String |
必须 |
亲爱的${nick}， 兜家年货清仓五折起咯！ |
卖家设置的短信模板 |
└ deliver_targets |
String [] |
必须 |
["123456","233445"] |
ouid列表 |
└ signature |
String |
必须 |
jinse01官方旗舰店 |
短信签名 |
└ plh_val_short_link |
String |
可选 |
t.cn |
shortLink of placeholders（淘短链） |
└ tpl_code |
String |
必须 |
SMS_3385002 |
聚石塔申请的短信模板Code |
└ placeholders |
String [] |
可选 |
nick(对应plh_val_nick) |
短信模板占位符list只支持4种错一点都不行 |
└ out_node_inst_id |
Number |
必须 |
100015 |
节点实例ID（回执信息唯一标志） |
└ plh_val_point |
Number |
可选 |
1000 |
point of placeholders（买家积分） |
└ plh_val |
Json |
可选 |
{"nick":"jinse01","point":"10","gradeName":"普通会员","shortLink":"c.tb.cn/c.Kgsf"} |
需要传递的占位符对应的值（链接类占位符值必须通过这个参数传递） |
└ plh_val_level_name |
String |
可选 |
至尊会员 |
levelName of placeholders（买家等级名称） |
└ plh_val_nick |
String |
可选 |
知庸01 |
nick of placeholders（买家nick） |
└ msg_type |
Number |
必须 |
1 |
短信类型 |
└mobile_acquisition_rule |
Number [] |
可选 |
[3,1,2] |
自定义手机号获取规则 |
└logistics_order_id_list |
String [] |
可选 |
["233425645","233835645"] |
指定订单号列表 |
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"]
接口出参
名称 |
参数类型/SDK类型 |
是否必须 |
文档可见 |
示例值 |
描述 |
result |
Boolean |
否 |
是 |
false |
是否成功生成单点投递任务 |
result_error_code |
String |
否 |
是 |
90001 |
错误码 |
result_error_msg |
String |
否 |
是 |
系统异常 |
报错信息 |
is_successed |
Boolean |
否 |
是 |
false |
接口是否调用成功 |
整个接口链路的返回说明
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表示消息类型。
4.4.2.2 短信人群通投接口
功能迭代中，预计830提供。
短信签名增加删除
1）商家的短信签名appkey全局唯一；
2）商家变更店铺名称后可重新申请签名，但是新的签名生效后，之前的店铺签名作废；
3）如提示短信签名被占用，联系 @奈量；
4）接口不支持删除操作。
接口信息
taobao.opencrm.signature.adddelete
接口入参
名称 |
参数类型/SDK类型 |
是否必须 |
文档可见 |
默认值 |
示例值 |
更多限制 |
描述 |
signature |
String |
必须 |
是 |
jinse01官方旗舰店 |
短信签名只能3-12个中文、英文或数字，必须包含中文！ |
短信签名 |
|
operate_type |
Number |
必须 |
是 |
1 |
操作类型，1-添加，2-删除 |
接口出参
无
短信签名查询
接口信息
taobao.opencrm.signature.query
接口入参
名称 |
参数类型/SDK类型 |
是否必须 |
文档可见 |
默认值 |
示例值 |
更多限制 |
描述 |
status |
Number |
可选 |
是 |
4 |
状态： 1-待提交审核， 2-审核中， 3-审核不通过， 4-审核通过 ，status为空，则返回除删除状态外的所有签名 |
接口出参
名称 |
参数类型/SDK类型 |
是否必须 |
文档可见 |
示例值 |
描述 |
result_list |
CrmShortMessageSignatureDo[] |
否 |
是 |
短信签名列表 |
|
└error_message |
String |
否 |
是 |
签名不合法 |
审核不通过原因 |
└status |
Number |
否 |
是 |
4 |
短信签名状态 |
└signature |
String |
否 |
是 |
jinse01官方旗舰店 |
短信签名 |
短信占位符使用
全变量模板对应的短信内容需要放在参数seller_tpl中，例如参数示例“亲爱的${nick}， 兜家年货清仓五折起咯”，占位符即使用${*}的形式来使用占位符值将短信内容替换成具体的占位符值，*为具体的占位符符号。其中，占位符分为需要传递值和不需要传递值两种，不需要传递值的占位符由官方根据ouid生成。需要传递的占位符值则放在参数plh_val中，例如参数示例
{"nick":"jinse01","point":"10","gradeName":"普通会员","shortLink":"c.tb.cn/c.Kgsf"}。占位符列表如下。
占位符名称 |
占位符符号 |
占位符值是否必须要传递 |
淘宝昵称 |
nick |
否 |
收货人姓名 |
receiverName |
否 |
当前等级名称 |
gradeName |
否 |
店铺短链 |
shopShortLink |
否 |
买家积分 |
point |
否 |
其他链接 |
crmShortLink |
是 |
会员中心链接 |
memberCenterUrl |
是 |
优惠券领取链接 |
couponApplyLink |
是 |
裂变优惠券分享链接 |
couponFissionLink |
是 |
商品名称 |
itemTitle |
是 |
商品详情短链 |
itemLink |
是 |
淘宝直播短链 |
taobaoLiveLink |
是 |
淘短链 |
shortLink |
是 |
店铺首页链接 |
shopUrl |
是 |
之前的等级名称 |
preGradeName |
是 |
获得或消耗的积分数 |
deltaPoints |
是 |
优惠券金额 |
couponAmount |
是 |
推荐用券商品 |
recommendItemUrl |
是 |
单条短信反馈消息
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 错误信息
名称 |
参数类型/SDK类型 |
是否必须 |
描述 |
是否必须 |
type |
Number |
必须 |
消息类型 |
必须 |
node_inst_id |
Number |
必须 |
唯一标志，由isv自己提供自己控制，以便一一对应跟踪消息 |
必须 |
content |
基本类型 |
Json |
消息体 |
必须 |
出账说明： 在短信发送的三个自然日之后，通过定时消息返回三天前整天发送短信的日账单。
短信账单消息
TMC消息
taobao_opencrm_ShortMessageBill
智能营销短信节点执行成功，3天后发送智能营销账单。
事件关怀短信账单，每天凌晨1天发送往前数第三天的账单，比如7月25日凌晨1时发送7月22日短信账单。
消息体
名称 |
类别 |
类型 |
描述 |
示例值 |
是否必须 |
备注 |
bill_type |
基本类型 |
Number |
账单类型 |
1 |
必须 |
账单类型，1-人群通投类账单，2-单条接口类日账单 |
node_inst_id |
基本类型 |
Number |
节点实例ID |
4001 |
否 |
bill_type=1时必须 |
seller_id |
基本类型 |
Number |
卖家ID |
3633855148 |
否 |
bill_type=2时必须 |
bill_date |
日期类型 |
Date |
短信账单日期 |
2017-04-23 00:00:00 |
否 |
bill_type=2时必须 |
success_bill_count |
基本类型 |
Number |
成功条数 |
180 |
必须 |
|
unknown_status_bill_count |
基本类型 |
Number |
状态未知条数 |
4 |
必须 |
|
fail_bill_count |
基本类型 |
Number |
失败条数 |
16 |
必须 |
|
unknow_status_count |
基本类型 |
Number |
状态未知人数 |
2 |
必须 |
|
success_count |
基本类型 |
Number |
成功人数 |
90 |
必须 |
|
fail_count |
基本类型 |
Number |
失败人数 |
8 |
必须 |
注：发送失败短信阿里通信不计费。
4.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
接口入参
名称 |
参数类型/SDK类型 |
是否必须 |
示例值 |
描述 |
task_content |
ShortMessageDeliverTaskContent |
必须 |
短信息任务参数集合 |
|
└ tpl_plh |
String |
必须 |
content |
聚石塔申请的短信模板占位符 |
└ seller_tpl |
String |
必须 |
亲爱的${nick}， 兜家年货清仓五折起咯！ |
卖家设置的短信模板 |
└ deliver_targets |
String [] |
必须 |
["123456","233445"] |
ouid列表 |
└ signature |
String |
必须 |
jinse01官方旗舰店 |
短信签名 |
└ plh_val_short_link |
String |
可选 |
t.cn |
shortLink of placeholders（淘短链） |
└ tpl_code |
String |
必须 |
SMS_3385002 |
聚石塔申请的短信模板Code |
└ placeholders |
String [] |
可选 |
nick(对应plh_val_nick) |
短信模板占位符list只支持4种错一点都不行 |
└ out_node_inst_id |
Number |
必须 |
100015 |
节点实例ID（回执信息唯一标志） |
└ plh_val_point |
Number |
可选 |
1000 |
point of placeholders（买家积分） |
└ plh_val |
Json |
可选 |
{"nick":"jinse01","point":"10","gradeName":"普通会员","shortLink":"c.tb.cn/c.Kgsf"} |
需要传递的占位符对应的值（链接类占位符值必须通过这个参数传递） |
└ plh_val_level_name |
String |
可选 |
至尊会员 |
levelName of placeholders（买家等级名称） |
└ plh_val_nick |
String |
可选 |
知庸01 |
nick of placeholders（买家nick） |
└ msg_type |
Number |
必须 |
1 |
短信类型 |
└mobile_acquisition_rule |
Number [] |
可选 |
[3,1,2] |
自定义手机号获取规则 |
└logistics_order_id_list |
String [] |
可选 |
["233425645","233835645"] |
指定订单号列表 |
接口出参
名称 |
参数类型/SDK类型 |
是否必须 |
文档可见 |
示例值 |
描述 |
result |
Boolean |
否 |
是 |
false |
是否成功生成单点投递任务 |
result_error_code |
String |
否 |
是 |
90001 |
错误码 |
result_error_msg |
String |
否 |
是 |
系统异常 |
报错信息 |
is_successed |
Boolean |
否 |
是 |
false |
接口是否调用成功 |
人群投放接口
接口名：taobao.opencrm.sms.crowd.post
功能迭代中，预计830提供。
4.5 历史数据清洗
新增Nick转ouid，Nick转omid接口
taobao.crm.history.ouid.get
关于调用条件和调用上限控制请参考FAQ。
taobao.crm.history.omid.get
转化条件：当前商家是会员通商家，且用户在UIC判断为品牌会员。否则转化失败。
关于调用条件和调用上限控制请参考FAQ。
4.6 CRM人群相关接口
新增ouid方式上传接口，兼容老接口能力，并且删除nick上翻数据方式。
taobao.opencrm.ctag.upload --> taobao.opencrm.ctag.upload.privy
taobao.opencrm.crowd.upload.bach --> taobao.opencrm.crowd.upload.bach.privy
4.6.1 标签上翻
API名称： taobao.opencrm.ctag.upload.privy
API入参
名称 |
参数类型 |
是否必须 |
示例值 |
更多限制 |
描述 |
id |
Number |
可选 |
1 |
自定义标签属性id |
|
encrypt |
Number |
可选 |
0 |
0:不加密, 1:md5, 2:sha256 |
|
members |
String [] |
可选 |
1,2,3 |
最大列表长度：500 |
ouid / 手机号/ 安卓设备 |
status |
Number |
可选 |
1 |
0:删除，1:新增 |
|
type |
Number |
可选 |
6 |
3:open_id, 4:手机号, 5:安卓设备imei, 6:ouid |
|
open_ids |
String [] |
可选 |
1,2,3 |
最大列表长度：999 |
open_id |
API出参
名称 |
参数类型/SDK类型 |
描述 |
result |
Result |
接口返回model |
└result |
OpenTagAttributeDto |
result |
└id |
Number |
id |
└ext_info |
String |
extInfo |
└success |
Boolean |
是否成功 |
└code |
Number |
code |
└msg |
String |
msg |
4.6.2 人群上翻
API名称：taobao.opencrm.crowd.upload.bach.privy
API入参
名称 |
参数类型 |
是否必须 |
示例值 |
更多限制 |
描述 |
open_crowd_user_d_t_o |
OpenCrowdUserDto |
必须 |
人群上传参数 |
||
└crowd_id |
Number |
必须 |
1001 |
可上传会员人群id |
|
└user_count |
Number |
必须 |
1 |
上传数量 |
|
└type |
Number |
必须 |
1 |
3:open_id, 6:ouid |
|
└open_u_ids |
String [] |
可选 |
["1","2"] |
最大列表长度：500 |
订单中的openUId,根据商家计算得出 |
└open_ids |
String [] |
可选 |
["1","2"] |
最大列表长度：500 |
小程序中使用的openId，根据appkey加密得出 |
API出参
名称 |
参数类型/SDK类型 |
是否必须 |
文档可见 |
示例值 |
描述 |
客户数据等级 |
是否加密 |
result |
Result |
否 |
是 |
0 |
接口返回model |
S1 |
否 |
└result |
OpenCrowdUserDto |
否 |
是 |
0 |
返回结果 |
S1 |
否 |
└crowd_id |
Number |
否 |
是 |
1 |
人群id |
S1 |
否 |
└user_count |
Number |
否 |
是 |
1 |
成功上传人数 |
S1 |
否 |
└success |
Boolean |
否 |
是 |
true |
是否成功 |
S1 |
否 |
└code |
Number |
否 |
是 |
1000 |
错误码 |
S1 |
否 |
└msg |
String |
否 |
是 |
上传成功 |
错误描述 |
S1 |
否 |
。
