注意:以下文档只适用于TOP接口,请谨慎使用!

文档中心 > 基础技术

一、背景说明


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

新的方案将会把订单中涉及消费者的敏感信息进行脱敏处理,订单中消费者敏感信息是指消费者订单中的收件人信息。具体脱敏信息字段包含:收件人姓名、收件人手机号、收件人电话(固定号码)、收件人详细地址(不包含省市区)。为了确保商家订单履约正常运行,平台将新增收件人ID字段【简称OAID】。OAID是本次升级新增的核心字段。升级后可以通过OAID进行订单合单,电子面单生成打印,服务短信发送、必要场景的信息解密功能等。

升级使用脱敏的订单数据+OAID方案后,可确保订单履约的全链路作业顺畅不受影响,同时能确保消费者的敏感信息受到保护。


二、方案概述


1.开发者(软件服务商、自研商家)从淘宝开放平台API或订单推送服务中获取的订单消费者敏感信息(收件人姓名、收件人手机、收件人电话、地址等)均为脱敏数据,本地不允许存储明文消费者敏感数据。

2.开发者(软件服务商、自研商家)的相关系统页面只能展示平台脱敏后的信息,如需展示明文需通过平台解密方案获得,并且要做好明文数据查看权限的隔离。

3.涉及三方仓的发货履约场景,订单处理类应用(ERP、OMS等)与仓储物流类应用(WMS等)之间的数据通信,必须通过淘宝开放平台定义的奇门相关接口来实现。

4.OAID可用于菜鸟电子面单产品的生成和打印。

5.开发者(软件服务商、自研商家)向消费者发送服务短信,可使用OAID通过淘宝开放平台提供的密文发送服务短信接口来实现。


三、升级实施流程


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


046A45F8-06CB-42b2-85A9-235BC8CC73D1.png


未接收到改造任务,可以选择淘宝开放平台控制台 —>支持—> 服务中心 —> 提交工单】,提交【隐私保护升级任务申请】工单


image.png


必填项(带*内容)填写完毕之后,点击下方的【提交工单】按钮。提交之后,可以在【控制台-支持-服务中心-我的工单】查看工单处理进程。


image.png


实施操作流程

image


四、涉及接口和字段说明

1.订单相关API


API名称:taobao.trade.fullinfo.get(获取单笔交易的详细信息)

入参改动:新增参数include_oaid。

名称

参数类型

示例值

描述

include_oaid

Boolean

true

appkey未对接oaid加密则忽略该字段。对接oaid加密情况下,(收货人+手机号+座机+收货地址+create)5个字段组合成oaid,原始订单上座机为空也满足条件。传true,代表必须返回oaid,生成不了就报isv.oaid-field-miss错误;默认或者传false,满足生成条件则返回oaid,否则为空


出参改动:新增参数oaid、收件人信息脱敏。

名称

参数类型

示例值

描述

trade

Trade[]



└ oaid

String

2w2RYE45iahnF4aiaJ7pHKCJ3Hwnbgnq2PH3AfpQVyWZNHKS9wNgAAOUfCVt9XZMetogNHwc

入参fields字段必须包含receiver_name、receiver_address、created、receiver_mobile、receiver_phone 5个字段,否则无法生成oaid。

└ receiver_name

String

张**

收货人的姓名

receiver_mobile

String

*******5678

收货人的手机号码

└ receiver_phone

string

****5678

收货人的电话号码

└ receiver_address

string

文**路**城***号

收货人的详细地址


API名称:taobao.trades.sold.get(根据创建时间-查询已卖出的交易数据)

入参改动:对接oaid加密情况下,出参要获取oaid,在入参fields中就需要包含(receiver_name、receiver_mobile、receiver_phone、receiver_address、created)5字段,否则生成oaid会报错。

出参改动:新增参数oaid、收件人信息脱敏。

名称

参数类型

示例值

描述

trades

Trade[]



oaid

String

2w2RYE45iahnF4aiaJ7pHKCJ3Hwnbgnq2PH3AfpQVyWZNHKS9wNgAAOUfCVt9XZMetogNHwc

入参fields字段必须包含receiver_name、receiver_address、created、receiver_mobile、receiver_phone 5个字段,否则无法生成oaid。

receiver_name

String

张**

收货人的姓名

receiver_mobile

String

*******5678

收货人的手机号码

receiver_phone

String

****5678

收货人的电话号码

receiver_address

String

文**路**城***号

收货人的详细地址


API名称:taobao.trades.sold.increment.get(根据修改时间-查询已卖出的增量交易数据)

入参改动:对接oaid加密情况下,出参要获取oaid,在入参fields中就需要包含(receiver_name、receiver_mobile、receiver_phone、receiver_address、created)5字段,否则生成oaid会报错。

出参改动:新增参数oaid、收件人信息脱敏。

名称

参数类型

示例值

描述

trades

Trade[]



oaid

String

2w2RYE45iahnF4aiaJ7pHKCJ3Hwnbgnq2PH3AfpQVyWZNHKS9wNgAAOUfCVt9XZMetogNHwc

入参fields字段必须包含receiver_name、receiver_address、created、receiver_mobile、receiver_phone 5个字段,否则无法生成oaid。

receiver_name

String

张**

收货人的姓名

receiver_mobile

String

*******5678

收货人的手机号码

receiver_phone

String

****5678

收货人的电话号码

receiver_address

String

文**路**城***号

收货人的详细地址


API名称:taobao.trades.sold.incrementv.get(根据入库时间-查询已卖出的增量交易数据)

入参改动:对接oaid加密情况下,出参要获取oaid,在入参fields中就需要包含(receiver_name、receiver_mobile、receiver_phone、receiver_address、created)5字段,否则生成oaid会报错。

出参改动:新增参数oaid、收件人信息脱敏。

名称

参数类型

示例值

描述

trades

Trade[]



oaid

String

2w2RYE45iahnF4aiaJ7pHKCJ3Hwnbgnq2PH3AfpQVyWZNHKS9wNgAAOUfCVt9XZMetogNHwc

入参fields字段必须包含receiver_name、receiver_address、created、receiver_mobile、receiver_phone 5个字段,否则无法生成oaid。

receiver_name

String

张**

收货人的姓名

receiver_mobile

String

*******5678

收货人的手机号码

receiver_phone

String

****5678

收货人的电话号码

receiver_address

String

文**路**城***号

收货人的详细地址


API名称:taobao.trades.sold.query(根据收件人信息查询交易单号)

有些场景比如退货无头件的处理,需要根据收件人的手机号反向查询对应的订单。可通过此接口获取相应店铺的订单号。

入参

名称

参数类型

示例值

描述

query_list

OrderQuery[]


查询条件列表,多个条件之间是OR关系,最多支持20个。receiver_name、receiver_mobile、receiver_phone至少有一个值不为空。

start_created

Date

2000-01-01 00:00:00

查询三个月内交易创建时间开始。格式:yyyy-MM-dd HH:mm:ss

end_created

Date

2000-01-01 23:59:59

查询交易创建时间结束。格式:yyyy-MM-dd HH:mm:ss

receiver_name

String

张三

收件人的姓名

receiver_mobile

String

13012345678

收件人的手机号

receiver_phone

String

010-12345678

收件人的电话号码


出参

名称

参数类型

示例值

描述

tid_list

String[]

["1111","2222"]

订单ID列表。按照订单创建时间倒序,最多返回最近的100笔订单。


2.电子面单相关API


菜鸟电子面单相关如下接口已升级,在兼容目前现状的基础上,新增了可选的OAID和tid入参。当前未接入新方案的订单,需传入空的OAID,和明文的收件人信息。接入新方案的订单,需传入不为空的 OAID和交易单号tid,新方案中OAID和tid必填。


API名称:cainiao.waybill.ii.get(电子面单云打印接口)

入参改动:新增参数oaid

名称

参数类型

示例值

描述

trade_order_info_dtos

TradeOrderInfoDto[]


请求面单信息,数量限制为10

recipient

UserInfoDto


收件人信息

oaid

String

2w2RYE45iahnF4aiaJ7pHKCJ3Hwnbgnq2PH3AfpQVyWZNHKS9wNgAAOUfCVt9XZMetogNHwc

收件人ID

tid

String

1527014522198024829

淘宝交易订单号,针对淘宝订单敏感加密场景使用,非必填,如果填写则必须是淘宝真实的交易订单ID


API名称:cainiao.waybill.ii.update(电子面单云打印更新接口)

入参改动:新增参数oaid。

名称

参数类型

示例值

描述

recipient

RecipientInfoDto


收件人信息

oaid

String

2w2RYE45iahnF4aiaJ7pHKCJ3Hwnbgnq2PH3AfpQVyWZNHKS9wNgAAOUfCVt9XZMetogNHwc

收件人ID


API名称:cainiao.reachable.batchjudge(是否派送可达判定批量查询接口)

入参改动:新增参数oaid。

名称

参数类型

示例值

描述

address_and_service_list

ReachableAddressAndServiceDto[]


收发地址和服务列表

oaid

String

2w2RYE45iahnF4aiaJ7pHKCJ3Hwnbgnq2PH3AfpQVyWZNHKS9wNgAAOUfCVt9XZMetogNHwc

收件人ID


API名称:cainiao.pickup.business.callguoguo(菜鸟商家寄件下单并呼叫裹裹运力)

入参改动:新增参数encrypted_customer_info。

名称

参数类型

示例值

描述

guo_guo_package_info

GuoGuoPackageInfo[]


包裹信息,最多传30个

encrypted_customer_info

EncryptedCustomerInfo


淘宝加密字段(如果无法取到明文的收件人信息,可以本字段代替,否则勿使用本字段。若本字段下属2个字段都不为空,则取解密后的地址为收件人地址。否则此字段无效,依然取上面的full_address_detail等信息为收件人信息。若下属2个字段都不为空但有误,会下单失败)

oaid

String

abcdefghij

收件人ID (Open Addressee ID),长度128位字符之内

taobao_order_id

String

123456

淘宝订单ID


API名称:cainiao.pickup.business.preorderview.get(菜鸟商家寄件下单前获取预览信息)

入参改动:新增参数encrypted_customer_info

名称

参数类型

示例值

描述

package_info_list

GuoGuoPackageInfo[]


批量下单时包裹信息列表,最多传30个

encrypted_customer_info

EncryptedCustomerInfo


淘宝加密字段(如果无法取到明文的收件人信息,可以本字段代替,否则勿使用本字段。若本字段下属2个字段都不为空,则取解密后的地址为收件人地址。否则此字段无效,依然取上面的full_address_detail等信息为收件人信息。若下属2个字段都不为空但有误,会下单失败)

oaid

String

abcdefghij

收件人ID (Open Addressee ID),长度128位字符之内

taobao_order_id

String

123456

淘宝订单ID


3.奇门相关API


订单相关的奇门API,已新增OAID的出入参,订单接口中Create、batchcreate接口用于衔接订单处理类应用(ERP、OMS等)仓储物流类应用(WMS等)之间的发货订单数据传输。

如果仓储物流类应用(WMS等)接到的密文数据因为业务需要,需要对某笔订单进行解密时,需要调用receiverinfo.query接口反向调用订单处理类应用(ERP、OMS等)的解密接口完成明文获取。receiverinfo.query接口需要订单处理类应用(ERP、OMS等)对接来实现解密功能。

每个接口的具体入参内容,请点击如下接口链接查看

奇门API

API名称

taobao.qimen.deliveryorder.create

发货单创建

taobao.qimen.deliveryorder.batchcreate

发货单创建批量接口

taobao.qimen.order.query

根据收件人信息查询交易单号接口

taobao.qimen.receiverinfo.query

OAID 收件人信息解密接口


4.解密API


API名称:taobao.top.oaid.decrypt

通过新增TOP接口taobao.top.oaid.decrypt实现根据OAID来做消费者敏感信息解密,获取OAID对应的收件人明文信息。

入参

名称

参数类型

示例值

描述

query_list

ReceiverQuery[]


解密请求列表,最多支持20个。

oaid

String

2w2RYE45iahnF4aiaJ7pHKCJ3Hwnbgnq2PH3AfpQVyWZNHKS9wNgAAOUfCVt9XZMetogNHwc

收件人ID (Open Addressee ID)

tid

String

1111

交易编号


出参

名称

参数类型

示例值

描述

receiver_list

Receiver[]



name

String

张三

收件人的姓名

mobile

String

13012345678

收件人的手机号

phone

String

010-12345678

收件人的电话号码

address_detail

String

淘宝城911号

收件人的详细地址

town

String

三墎镇

收货人街道地址

district

String

西湖区

收货人的所在地区

city

String

杭州市

收货人的所在城市

state

String

浙江省

收货人的所在省份

country

String

中国

收货人国籍

oaid

String

2w2RYE45iahnF4aiaJ7pHKCJ3Hwnbgnq2PH3AfpQVyWZNHKS9wNgAAOUfCVt9XZMetogNHwc

收件人ID (Open Addressee ID),字符长度128位以内。

tid

String

123456

交易编号

matched

Boolean

true

oaid是否和tid当前的oaid匹配。true:匹配,false:不匹配。当不匹配时,建议通过taobao.trade.fullinfo.get获取最新的oaid。


5.合单校验API


API名称:taobao.top.oaid.merge(合单校验)

同一个消费者在同一店铺内的待发货订单中,OAID相同的可以直接合单,不同的可调用订单合单接口:taobao.top.oaid.merge进行判断。

入参

名称

参数类型

示例值

描述

merge_list

OrderMerge[]


合单请求列表,最多支持100个。

oaid

String

2w2RYE45iahnF4aiaJ7pHKCJ3Hwnbgnq2PH3AfpQVyWZNHKS9wNgAAOUfCVt9XZMetogNHwc

收件人ID (Open Addressee ID)

tid

String

1111

交易编号


出参

名称

参数类型

示例值

描述

tid_list

String[]

["1111,2222","3333"]

合单结果。可合单的订单ID列表用逗号分隔的字符串表示。比如,"1111,2222"表示订单1111和订单2222可合并发货。


6.密文发送短信API


API名称:taobao.jst.sms.oaid.message.send(OAID发送短信 )

该接口仅可用来发送订单履约相关的短信,不可用来发送营销短信的。消费者订单上的手机号仅是用来购买商品的,在没有得到消费者同意的情况下,不得用于和该笔订单履约无关的场景。

入参

名称

参数类型

示例值

描述

param_send_message_by_o_a_i_d_request

SendMessageByOaidRequest



extend_name

String

12345

拓展Name

order_id

Number

1590159531380428537

订单号

extend_code

String

12345

拓展Code

sms_free_sign_name

String

聚石塔测试签名

短信签名

template_code

String

SMS_12345

短信模板

params

Json

{"content":"您好! "}

短信占位符,替换短信模板里的占位符

extend

String

123

拓展信息

oaid

String

3mwdUE03cfGGuH4A4DrWWjcL8lxkl3bH29SM1RHqDNo5RgXYTdCQj1ZMN8wbv7qnLeiX6Dr

收件人ID(Open Addressee ID),长度128字符之内。


出参

名称

参数类型

示例值

描述

module

String

1234567890^0

短信拓展码

req_id

String

1235

top请求id


五、订单隐私保护相关场景和策略

1.OAID解密场景和对应策略


场景编码

场景名称

返回的隐私字段

1001

顺丰电子面单发货

消费者手机号,姓名,详细地址

1002

4通一达电子面单发货

消费者手机号,姓名,详细地址

1003

EMS电子面单发货

消费者手机号,姓名,详细地址

1004

其他电子面单发货

消费者手机号,姓名,详细地址

1005

线下门店发货

消费者手机号,姓名,详细地址

1006

手工单发货

消费者手机号,姓名,详细地址

1007

代发货

消费者手机号,姓名,详细地址

1008

改地址

详细地址

1009

查看收件人姓名

收件人姓名

2001

客户售后服务

消费者手机号

2002

客户关怀

消费者手机号

3001

奇门

消费者手机号,姓名,详细地址


若taobao.qimen.receiverinfo.query中scene参数为空时(调用方系统未改造完毕),下游系统请设置scene = 3001。


2.根据收件人信息查询交易单号(taobao.trades.sold.query)的场景


场景编码

场景名称

返回结果

1001

客服咨询

返回最近7天的订单号

1002

售后服务

返回最近3个月的、最多100个订单号。


如有新增场景需要平台给出标准码定义,请开发者通过提交工单【开放平台-订单隐私保护升级】进行反馈。



六、通用场景升级说明


由于每个应用的功能范围存在差异,此章节仅提供整体性介绍和常见或关键改造点的改造建议,不同的功能改造点涉及到使用不同的接口,还需要开发者(软件服务商、自研商家)根据自身产品情况做具体的实施和落地。


整体数据推送链路

image


1.脱敏后订单数据查询


平台提供订单推送服务、API等方式查询订单数据,升级后查询到的消费者敏感信息以脱敏+OAID的形式返回。

查询订单详情数据可通过调用taobao.trade.fullinfo.get接口实现。

查询待发货订单数据可通过调用taobao.trades.sold.get接口实现。


2.订单脱敏数据展示


通过平台订单推送服务与API接口获取到的数据都是OAID+脱敏的形式,并按照此样式展示在相关页面,不做不必要的解密,不做明文展示。

通过taobao.trades.sold.get接口的调整使用,完成应用订单列表页或待发货订单列表页,信息的脱敏展示。

通过对taobao.trades.sold.query接口的调整使用,完成针对退货无头件场景查询时的模糊搜索功能的数据脱敏展示,实现各端、页面、列表按姓名搜索订单数据脱敏展示,实现各端、页面、列表按手机号搜索订单数据的脱敏展示,目前该接口只用于退货无头件场景的使用,不可用于非此场景的模糊查询。

通过对taobao.trade.fullinfo.get接口的调整使用,完成各端、页面、列表查看订单详细信息时对收件人信息展示平台脱敏的数据。


3.脱敏后订单发货场景


通过订单推送、taobao.trade.fullinfo.get、taobao.trades.sold.get、taobao.trades.sold.increment.get获取OAID+脱敏订单信息,然后调用菜鸟电子面单相关接口:cainiao.waybill.ii.get获取电子面单号,最后调用淘宝物流发货接口:alibaba.ascp.logistics.offline.send、taobao.logistics.offline.send进行订单发货。


4.脱敏后订单合单处理


同一个消费者在同一店铺内的待发货订单中,OAID相同的可以直接合单,不同的可调用订单合单接口:taobao.top.oaid.merge进行判断。


5.退款场景根据手机号或姓名搜索订单


按手机号模糊搜索订单数据可通过调用taobao.trades.sold.query接口实现。

按收件姓名模糊搜索订单数据可通过调用taobao.trades.sold.query接口实现。


6.奇门数据传输脱敏


主要实现订单处理类应用(ERP、OMS等)-》奇门-》仓储物流类应用(WMS等)三方数据的互通传递,需要保证数据在脱敏+OAID的形式下完成

订单处理类应用(ERP、OMS等)需要支持仓储物流类应用(WMS等)对特殊订单通过奇门解密接口:taobao.qimen.receiverinfo.query的反向解密需求。


7.电子面单


电子面单的获取接口兼容脱敏数据的处理,当前未接入新方案的订单,需传入空的OAID,和明文的收件人信息。接入新方案的订单,需传入不为空的OAID和交易单号tid。新方案中OAID和tid必填。


8.短信功能


通过taobao.jst.sms.oaid.message.send接口实现OAID短信通知功能,该接口仅可用来发送订单履约相关的短信,不得用于和该笔订单履约无关的场景。

如果要确认消息是否投递成功,要通过监听消息来确认。目前用到短信能力的开发者(软件服务商、自研商家)应该都可以通过module回执码,匹配监听的消息对应查询这笔的发送状态。如需了解整体的短息服务对接可参考:通信服务使用介绍


9.订单解密查看


敏感数据查看通过解密接口:taobao.top.oaid.decrypt实现,功能上涉及到的几个比较明确的场景是:订单列表页可对指定的某笔订单做解密、订单详情页可对某笔指定的订单详情数据的解密、打印普通快递单,可实现对订单进行解密。如上解密功能实现过程中注意数据的隔离保护,解密后的明文只对发起解密的账户可见,其它账户登录后对同一笔订单数据看到的必须还是脱敏信息,做到数据的安全隔离不泄露。


七、灰度验证说明(仅对老用户适用)


为帮助开发者(软件服务商、自研商家)保证升级的质量、功能逐步完善、数据切换的平稳过渡,平台通过开放平台任务中心向开发者(软件服务商、自研商家)下发改造管理流程。提供整体的过程测试店铺配置能力,支持通过比例灰度逐步完成升级。

整体由功能单测到最终全量完成升级的流程图

image

1.单点测试店铺配置


此环节用于配置单点测试店铺,用于开发者(软件服务商、自研商家)改造初期的功能和数据传输验证。输入对应的测试店铺提交后,相应测试店铺的订单敏感数据即刻生效,返回为密文+OAID。

image

2.产品功能审核


在单点测试店铺联调完成数据和功能准确性校验后,开发者(软件服务商、自研商家)依据对应场景,将系统实现的效果展示截图上传。平台依据上传的内容,进行初步的功能实现准确性及完整性判定。


image


3.小范围线上验证


完成产品功能的审核后,进入下一步少量线上店铺的配置切换。开发者(软件服务商、自研商家)沟通和选取少量线上店铺进行升级切换,通过实际的功能使用和数据获取来进行线上验证。


image

4.线上规模化覆盖


线上小范围验证稳定无问题的前提下,订单处理类应用(ERP、OMS等)开发者(软件服务商、自研商家)可以开始批量灰度直至逐步将店铺都迁移升级完成。

image


FAQ

关于此文档暂时还没有FAQ
返回
顶部