1 平台指南
1.1 概述
淘宝全球开放平台是一个提供端到端的 API 开发与营运的整合平台，主要提供开发人员透过程式设计的方式存取平台卖家、经销商在商品、订单、发货、物流和结算方面的数据，并为使用者提供一个通过 API 系统整合应用程式的开发环境，以提供更多元的卖家需求，并分享您的应用程式给更多淘宝全球卖家。
开放平台具有以下特点和优势：
- 开放的 API 库：可覆盖电商领域丰富的 API 接口，包括商品、订单、用户、营销和物流管理，最高可支持日达千万级的呼叫量。
- 稳定的性能：具有高并行性和极佳 API 呼叫成功率，确保阁下的应用程式性能。
- 安全框架：用于保护卖方业务数据的可靠安全框架。
- 数据看板：应用程式发起的对 API 呼叫的成功和失败率统计信息。
2 新手指南
2.1 接入流程
如果您是一名淘宝全球开放平台的新手，本指南可以帮助您快速地了解如何开始使用 API 开发您的应用程式、部署上线以及将您的应用程式分享给淘宝全球业务的用户。
2.2 入驻跨境供货平台
入驻跨境供货平台，注意，需提前注册，要走审批（大概1～2人日），一般找自身业务同学进行注册。注册完成之后，通过开放平台的授权地址链接，找业务同学登录跨境供货平台进行相应授权，并通过回调地址获取到授权码code，有了code就可以调用创建Token的接口生成令牌了！：）https://distributor.taobao.global/apps/register/registration
跨境供货平台帮助文档：
https://helpcenter-globalsupply.taobao.global/page/knowledge?pageId=216&category=1000005768&knowledge=1000056110&language=zh
2.3 入驻开放平台
如果您是第三方开发者，希望通过 API 开发接入淘宝全球开放平台业务相结合的应用程序，那么您可以在淘宝全球开放平台注册成为开发者。首先，您可以让自身业务同学注册一个开发者帐号并签署平台的开发者协议。
通过以下步骤在淘宝全球开放平台注册开发者帐号：
1) 打开淘宝全球开放平台主页 https://open.taobao.global，然后点击「立即入驻」。
2) 在打开的页面上输入您的电子邮箱地址和验证码，然后点击「发送电子邮件」进行验证。
3) 打开您电子邮箱的验证邮件并点击验证链接，会再次打开帐号注册页面。注意：验证邮件可能在垃圾邮 件中。
4) 在帐号注册页面上设置密码、阅读并勾选同意接受[淘宝全球开放平台开发者协议]。
5) 点击「完成」，即帐号注册完成。
2.4 创建开发者应用
描述：开放平台开发者帐号新增完成后，您可以开始在淘宝全球开放平台上注册您的应
用程序了。
- 申请应用类型“全球供销平台”类目
描述：应用程式类型用于在新增应用程式时初始化数据配置。它是一个定义了应用程序的授权策略、授权期限、API 许可权组、API 呼叫限制策略等信息的模板。一个应用程式只能属于一个应用类型。供销平台应用类型为“全球供销平台”。
具体步骤细节：
- 登录淘宝全球开放平台，打开 APP 控制台；
- 单击「新增」将显示可申请的应用类型清单；
- 阅读应用类型描述，找到您要申请的应用类型后点击「申请」；
- 在应用视窗的「原因」栏位中输入申请该应用类型的业务需求；
- （可选）根据需要为此请求附加文档。文档可以是市场分析、业务计画或应用程式的设计；
- 点击「OK」提交请求；
- 应用程式类型的状态会显示为「待审核」，您的申请将由平台管理员进行审核（约2-3个工作日）。如果您无法为您的应用程式找到合适的类别，请与淘宝全球开放平台运营团队联络。
- 创建开发者应用
描述：一旦应用程式类型的请求被审核通过，应用程式类型的状态将变更为「有效」，之后您可以提交关于您的申请的详细信息。步骤如下：
创建应用细节：
- 在请求的类型页面上，点击「新增APP」；
- 输入有关应用程式的信息，包括：应用程式名称、回调地址（用于卖方授权的重定向URL）、应用程式 LOGO。
- 点击「提交」；
- 应用程式新增成功后，点击「APP概述」对应用程式清单进行查看，包括应用程式名称、APP金钥、类型和每个应用程式的状态。
2.5 应用管理
2.5.1 获取 AppKey 和 AppSecret
AppKey：是淘宝全球开放平台上应用的唯一标识。 App Key 是发出 API 呼叫请求时必须包含的参数之
一，且应用程式将由淘宝全球开放平台通过 App Key 进行识别。
AppSecret：是淘宝全球开放平台分配给应用的密码，以确保应用源的安全性和可靠性。您必须妥善保管
APP 金钥，切勿与其他第三方共用。
一旦您的应用程式注册完成，App Key 和App Secret将自动产生。您可以在应用主控台/应用预览页面查看或重置 App Key。
- 从应用程式清单中，点击「管理」进入应用预览页面。
- 在应用预览页面将直接显示 App Key。
- 在 App Secret 点击「查看」可查看您的APP金钥。
- 点击「重置」可重置应用程式的 APP 金钥。如有「APP金钥过期」栏位，请选择旧 APP 金钥的过期时间（以小时为单位）。
- 重置 App 金钥后，您必须更新应用程式的相关信息。
如图所示：
2.5.2 申请 API 许可
在淘宝全球开放平台上，API 权限组定义了一组具有特定权限绑定的 API 组。没有 API 许可，应用程式发起的 API 呼叫将会被拒绝。
一个应用程式类型可以包含多个 API 权限组。应用程式被新增的同时，会被授予部分 API 权限权组，但其它权限组则需要单独申请。API 权限组的状态如下：
- 有效： API 权限组预设可用或已申请通过可用。
- 无效： API 权限组需要单独申请或申请未通过。
2.6 卖家授权
2.6.1 授权说明
配置卖家授权如果您的应用程式需要存取卖家业务数据，则您的应用程式需要获得卖家的授权，您需要指导他们完成「使用淘宝全球帐号登录授权」流程。在淘宝全球开放平台注册您的应用程式之后，您就可以开始您的应用程式开发了。API参考 – 每个 API 的完整参考文档。
2.6.2 授权策略
淘宝全球开放平台使用 OAuth 2.0 协议进行使用者身份验证，并为不同的应用程式类别提供不同的授权策略，这些策略是为您的应用程式所属的应用程式类别预先定义的。您可以在授权管理页面查看应用程式的详细授权策略，包含以下：
- 授权策略：应用程式的整体策略
- 「Access Token」週期：应用程式的 Access Token 有效期
- 「Refresh Token」週期：Refresh Token 有效期（有关详细信息请参阅 OAuth 文档）
- 授权页：是否显示授权页（预设显示授权页）
- 授权协议：OAuth2.0 授权类型
- 授权使用者限制：授权应用程式的最大卖家数
重点注意，以下两种授权策略适用于不同的APP类别：
- 允许绑定用户授权：此授权策略适用于直接与大卖家内部应用程式对接或“客户服务”的类别。此策略只有在“授权卖家白名单”中设定过的卖家才能授权您的应用程式。
- 允许登录用户授权：此授权策略适用于“商品管理”“订单管理”“物流管理”等ERP系统相关的应用程式类别。
2.6.3 指定白名单授权
如果您为特定的卖家开发了一个应用程式，您可以通过在淘宝全球开放平台上指定卖家白名单来限制授权范围，那麽只有这些卖家可以授权您的应用程式存取他们在淘宝市场上的业务数据。在您的应用程式被线上部署之后，您需要向卖家提供授权URL。当卖家第一次登入您的应用程式时，他们将被提示完成授权流程。
採取以下步骤用来指定可以授权您的应用程式存取其业务数据的卖家的短代码：
- 打开 APP 控制台，点击APP管理 -> 身份验证管理
- 在授权信息部分，查看应用程式授权策略描述。
- 在授权卖家白名单部分，在授权字段中输入卖家帐号。多个卖家帐号可以用分号分隔。
- 点击「提交」
注意：如果您是第三方开发者，并且您的应用程式对所有淘宝全球开放平台业务的用户开放，那麽您只需要在应用程式线上部署时向卖家提供您的应用程式的 URL。卖家可以按照 URL 完成授权流程。授权流程请参考卖家授权的介绍。
2.6.4 卖家授权步骤
描述：如果您的应用程式需要透过淘宝全球开放平台访问卖家的业务数据（如商品和订单信息），您需要获得卖家的授权，即，访问卖家信息所需要的「Access Token」。您需要指导卖家完成「使用跨境供货平台登录授权申请」流程。此过程使用国际 OAuth 2.0 标准协议进行使用者身份验证和授权。
淘宝全球开放平台采用「Code for token」模式，具体描述如下：
服务器地址：https://api.taobao.global/oauth/authorize
授权步骤（如图所示）：
2.6.4.1 拼接授权 URL
按照以下规则拼装授权URL，并引导业务同学访问：
注意：请将「appkey」及「redirect_url」替换为您的开发者应用程式配置。
授权 URL 参数列表说明如下：
| 参数 |
是否必须？ |
值 |
描述 |
| client_id |
是 |
xxx |
由开放平台分配的您的应用程序 App Key。 |
| redirect_url |
是 |
创建应用程式时提供的回档URL。 |
redirect_url 是卖方完成授权时回传给您的接收代码，它必须与在淘宝全球开放平台上创建应用程式时提供的回档 URL 相同。 |
| response_type |
是 |
code |
值为「code」的授权类型。 |
| force_auth |
否 |
true |
刷新 Web 流览器 Cookie 以获得新的授权流程。 |
| state |
否 |
可自定义，如1212. |
应用程式的状态，与输入和回应的相同。 |
| uuid |
否 |
uuid283118319 |
分配给卖方的身份，可以保护返回的授权码。 |
2.6.4.2 引导卖家授权
引导分销商通过 Web 流览器打开上述授权 URL，会出现如下图所示的授权登录页面。左侧显示了授权之后卖家授予应用程式的权限，需输入2.2步骤注册的跨境供货平台账号和密码（注意不是开放平台账号！否则无法正常采购），点击「登录并授权」后，完成对应用程式的授权。
2.6.4.3 获取授权码code
卖家完成授权后，淘宝全球开放平台会返回授权码到回传 URL 地址。您的应用程式会通过授权码来获取 AccessToken。网址将为您所设定的 APP 回调地址 + 授权码（code）
例如：
注意：
- 此授权码将在 30 分钟内过期。您需要在过期前使用此代码获取 Access token。
2.6.4.4 根据code获取AccessToken
描述：使用API「/auth/token/create」 来获取 AccessToken
注意：Access Token 将在一定时间范围内有效。在过期之前，卖家不需要再次授权应用程式。您需要妥善
保管最新的 Token。
IopClient client = new IopClientImpl("https://api.taobao.global/rest", appkey, appSecret);
IopRequest request = new IopRequest("/auth/token/create");
request.addApiParameter("code", "0_TryzT8Vd9T1pwS7VWZ2qlMOS5");
IopResponse response = client.execute(request);
System.out.println(response.getBody());
出参（仅供参考）：
{
"code": "0",
"access_token": "50000601c30atpedfgu3LVvik87Ixlsvle3mSoB7701ceb156fPunYZ43GBg",
"refresh_token": "500016000300bwa2WteaQyfwBMnPxurcA0mXGhQdTt18356663CfcDTYpWoi",
"account_id": "7063844",
"user_Id": "1001",
"account_platform": "seller_center",
"refresh_expires_in": "60",
"error_code": "error_code",
"expires_in": "10",
"request_id": "0ba2887315178178017221014",
"seller_Id": "10011",
"account": "xxx@126.com",
"short_code": "HK001"
}
下表列出了 Token 的参数和描述：
| Key |
Type |
Sample |
描述 |
| access_token |
string |
50000601c30atpedfgu3LVvik87Ixlsvle3mSoB7701ceb156fPunYZ43GBg |
Access token. |
| refresh_token |
string |
500016000300bwa2WteaQyfwBMnPxurcA0mXGhQdTt18356663CfcDTYpWoi |
Refresh token, 用于在「refresh_expires_in」>0 时刷新。 |
| expires_in |
number |
25920 (expires in 25920 seconds) |
Access token 的过期时间以秒为单位. 「测试」状态的应用程式, 该值是7天. 「在线」状态的应用程式，该值是 30天. |
| refresh_expires_in |
number |
25920 (expires in 25920 seconds) |
refresh token的过期时间. 「测试」状态的应用程式，该值是 30天.「在线」状态的应用程式，该值是180天. |
| account_id |
string |
706388888 |
User ID, 当 “account_platform” = “seller_center” 时可以忽略。 |
| account |
string |
xxx@126.com |
User account. |
| account_platform |
string |
seller_center |
用户平台，支持多个平台。 |
查看实际有效时长：
注意：未发布上线的开发者的应用（测试阶段），其有效时长会比已上线的应用要短，故开发者对接完毕后要申请应用发布上线！并相应的调整刷新token策略，如自身业务需要延长Token或刷新令牌有效时间可找开放平台负责人进行调整即可。
示例（测试阶段）：
2.6.4.5 令牌刷新策略
描述：使用API「/auth/token/refresh」 来更新 AccessToken。
IopClient client = new IopClientImpl(UrlConstants.API_GATEWAY_URL_TW, appkey, appSecret);
LazopRequest request = new LazopRequest();
request.setApiName("/auth/token/refresh");
request.addApiParameter("refresh_token", "50001600212wcwiOabwyjtEH11acc19aBOvQr9ZYkYDlr987D8BB88LIB8bj");
LazopResponse response = client.execute(request);
System.out.println(response.getBody());
出参（仅供参考）：
{
"code": "0",
"access_token": "50000601c30atpedfgu3LVvik87Ixlsvle3mSoB7701ceb156fPunYZ43GBg",
"refresh_token": "500016000300bwa2WteaQyfwBMnPxurcA0mXGhQdTt18356663CfcDTYpWoi",
"account_id": "7063844",
"user_Id": "1001",
"account_platform": "seller_center",
"refresh_expires_in": "60",
"error_code": "error_code",
"expires_in": "10",
"request_id": "0ba2887315178178017221014",
"seller_Id": "10011",
"account": "xxx@126.com",
"short_code": "HK001"
}
通过 「/auth/token/refresh」 返回的数据结构与通过授权代码获取访问权限返回的数据结构相同。您将获得新的「access_token」和「refresh_token」。您必须保存最新的「refresh_token」以获取新的「access_token」。请注意，access_token 的时长会被重置，但 refresh_token 的时长不会被重置。refresh_token 过期后，卖家需要重新授权您的应用程式来生成新的 access_token 和 refresh_token。
2.6.4.6 令牌时效说明
注意事项：
- 在 RefreshToken 过期前，卖家不需要再次授权。
- 如果 「refresh_expires_in」= 0，则无法刷新 Access Token。只有当 「refresh_expires_in」> 0时，才可以呼叫/auth/token/refresh API 来刷新 access
token。
- 如果需要更新 AccessToken，建议在 AccessToken 过期前一周内进行刷新。
- 如当前令牌有效时长对自身业务影响较大，可找供货平台负责人进行时效延长。
| 字段 |
应用状态：测试（时效） |
应用状态：上线（时效） |
| code |
30分钟 |
30分钟 |
| access_token |
30天 |
30天 |
| refresh_token |
60天 |
180天 |
3 开发文档
3.1 用法一：使用SDK请求（推荐）
描述：SDK 是为您的应用程式自动生成的，包括组合请求、生成加密、响应诠释、信息监控等功能。使用 SDK 来
呼叫 API 的操作简单易懂，建议您使用官方 SDK 进行 API 的呼叫。
环境要求：
- JAVA SDK 需要 JAVA SE/EE 1.5 或更新版本；
- .Net SDK 需要 .Net Framework 2.0 或更新版本（不支援 Windows Phone 台）；
- PHP SDK 需要 PHP 5 或更新版本；
- Python 需要 Python 3.0 或更新版本；
- 对于 Ruby，您可以直接安装。
3.1.1 SDK下载
在下载 SDK 之前，您需要注册为开发者并以此身份登录。下载的 SDK 与应用程式直接关联。
为应用程式下载 SDK 可以采取以下步骤：
3.1.2 调用请求地址
描述：使用 SDK 调用之前，请将请求服务器修改为（注意点）
调用请求地址：https://api.taobao.global/rest
3.1.3 调用示例
3.2 用法二：使用HTTP 请求API
3.2.1 API调用流程
通过 HTTP 请求呼叫淘宝全球开放平台的 API。您可以使用平台提供的 SDK 来呼叫 API（推荐），或者根据淘宝全球开放平台协议自定义格式来组装请求（仅限此编程语言未提供官方 SDK 的情况下）。本节主要介绍如何组装 HTTP 请求来呼叫。
API呼叫需要输入数据并返回数据作为输出回应。通过生成HTTP请求来呼叫API的一般步骤如下：
- 填写参数和值
- 签名加密演算法
- 组装 HTTP 请求
- 启动 HTTP 请求
- 获取 HTTP 回应
- 解释 JSON/SML 回应
有关更多开放平台的 API 呼叫的详细信息，请参阅 API 教程。
3.2.2 调用请求地址
淘宝全球开放平台提供了一个线上生产环境，在该环境下产生的资料都是真实有效的线上资料，并提供限量的调用次数和许可权。该生产环境与线上系统共用数据资料，线上店铺的真实资料直接受 API 操作的影响，请务必谨慎操作。
调用请求地址为：https://api.taobao.global/rest
3.2.3 请求与响应
淘宝全球开放平台 API 同时支援 HTTP 和 HTTPS 通信协定。为了确保资料安全性，建议使用 HTTPS 协定发出 API 请求。虽然大多 API 是通过 GET 呼叫的，一些获取额外请求资料的呼叫是通过 POST 发送的，但有时需要提供的资料比可以在请求参数中传输的资料要多。很多情况下，额外资料是通过 POST 请求发送到伺服器的。请求的主体必须采用 XML 格式，所有资料（包括参数名和值）必须是 utf8 编码。
每个 HTTP 请求 URL 必须包含 API 路径。例如，对 /order/get API 的请求应该是https://api.taobao.global/rest/order/get。通用参数和业务资料包含在请求中或通过 POST 发送。
所有 API 呼叫都返回一个回应文档，该文档显示操作的状态（成功或错误），以及可能提供与指定操作相关的结果和/或详细资讯。回应格式是 JSON。
3.2.4 请求入参
除了与应用程式关联的参数外，对 API 的呼叫还必须包含系统参数。不同的API需要不同的应用程式特定参数。
系统参数
每个 API 呼叫的 HTTP 请求都需要系统参数，如下表：
| Name |
类型 |
是否強制 |
描述 |
| app_key |
String |
Yes |
分配给应用程式的App key。 |
| access_token |
String |
Conditional |
对于需要卖家授权的 API 来说，卖家授权 token 是必需的。 |
| timestamp |
String |
Yes |
请求被发送的时间，采用 UTC 或数位格式，如“2018-11-11T12:00:00Z或1517886554000”。注意，时间戳记和 UTC 时间之间的差异不应该超过 7200 秒。 |
| sign_method |
String |
Yes |
用于签名加密的演算法。 |
| sign |
String |
Yes |
密码签名，用于验证请求。 |
业务参数
除了必须包含在 API 呼叫请求中的系统参数外，还需要请求业务参数。有关每个 API 的业务参数的详细资讯，请参阅API文档。
3.2.5 参数签名
淘宝全球开放平台会对每个 API 请求的身份进行验证，服务器也将验证呼叫参数是否有效。因此，每个 HTTP 请求必须包含签名资讯，签名无效的请求将被拒绝。
淘宝全球开放平台通过 App Key 和分配给应用程式的金钥来验证请求的身份。 App 金钥用于在 HTTP 请求 URL 和伺服器端签名字串时生成签名字串。请严格保密您的金钥。
如果手动编写 HTTP 请求（而不使用官方 SDK），则需要了解以下签名算法。
生成签名的过程如下：
- 根据 ASCII 表中的参数名称对所有请求参数(包括系统和应用程式参数，但“符号”和带位元组阵列类型的参数除外)进行排序。
Before sort:
foo=1, bar=2, foo_bar=3, foobar=4
After sort:
bar=2, foo=1, foo_bar=3, foobar=4
- 将排序后的参数及其值连接到一个字串中。举例：bar2foo1foo_bar3foobar4
- 在连接的字串前面添加API名称。举例，添加API名称“/test/api”:
/test/apibar2foo1foo_bar3foobar4
- 用UTF-8格式编码连接的字串，并通过签名演算法(使用HMAC_SHA256)进行摘要。举例：
hmac_sha256(/test/apibar2foo1foo_bar3foobar4)
hex("helloworld".getBytes("utf-8")) = "68656C6C6F776F726C64"
JAVA 示例代码：
/**
* Sign the API request with body.
*/
public static String signApiRequest(Map<String, String> params, String body, String appSecret, String signMethod, String apiName) throws IOException {
// first: sort all text parameters
String[] keys = params.keySet().toArray(new String[0]);
Arrays.sort(keys);
// second: connect all text parameters with key and value
StringBuilder query = new StringBuilder();
query.append(apiName);
for (String key : keys) {
String value = params.get(key);
if (areNotEmpty(key, value)) {
query.append(key).append(value);
}
}
// third：put the body to the end
if (body != null) {
query.append(body);
}
// next : sign the whole request
byte[] bytes = null;
if(signMethod.equals(Constants.SIGN_METHOD_HMAC)) {
bytes = encryptWithHmac(query.toString(), appSecret);
} else if(signMethod.equals(Constants.SIGN_METHOD_SHA256)) {
bytes = encryptHMACSHA256(query.toString(), appSecret);
}
// finally : transfer sign result from binary to upper hex string
return byte2hex(bytes);
}
private static byte[] encryptHMACSHA256(String data, String secret) throws IOException {
byte[] bytes = null;
try {
SecretKey secretKey = new SecretKeySpec(secret.getBytes(Constants.CHARSET_UTF8), Constants.SIGN_METHOD_HMAC_SHA256);
Mac mac = Mac.getInstance(secretKey.getAlgorithm());
mac.init(secretKey);
bytes = mac.doFinal(data.getBytes(Constants.CHARSET_UTF8));
} catch (GeneralSecurityException gse) {
throw new IOException(gse.toString());
}
return bytes;
}
/**
* Transfer binary array to HEX string.
*/
public static String byte2hex(byte[] bytes) {
StringBuilder sign = new StringBuilder();
for (int i = 0; i < bytes.length; i++) {
String hex = Integer.toHexString(bytes[i] & 0xFF);
if (hex.length() == 1) {
sign.append("0");
}
sign.append(hex.toUpperCase());
}
return sign.toString();
}
C# 示例代码：
public static string SignRequest(IDictionary<string, string> parameters, string body, string appSecret, string signMethod, string apiName)
{
// first : sort all key with asci order
IDictionary<string, string> sortedParams = new SortedDictionary<string, string>(parameters, StringComparer.Ordinal);
// second : contact all params with key order
StringBuilder query = new StringBuilder();
query.Append(apiName);
foreach (KeyValuePair<string, string> kv in sortedParams)
{
if (!string.IsNullOrEmpty(kv.Key) && !string.IsNullOrEmpty(kv.Value))
{
query.Append(kv.Key).Append(kv.Value);
}
}
// third : add body to last
if (!string.IsNullOrEmpty(body))
{
query.Append(body);
}
// next : sign the string
byte[] bytes = null;
if (signMethod.Equals(Constants.SIGN_METHOD_SHA256))
{
HMACSHA256 sha256 = new HMACSHA256(Encoding.UTF8.GetBytes(appSecret));
bytes = sha256.ComputeHash(Encoding.UTF8.GetBytes(query.ToString()));
}
// finally : transfer binary byte to hex string
StringBuilder result = new StringBuilder();
for (int i = 0; i < bytes.Length; i++)
{
result.Append(bytes[i].ToString("X2"));
}
return result.ToString();
}
PYTHON 示例代码：
def sign(secret,api, parameters):
#===========================================================================
# @param secret
# @param parameters
#===========================================================================
sort_dict = sorted(parameters)
parameters_str = "%s%s" % (api,
str().join('%s%s' % (key, parameters[key]) for key in sort_dict))
h = hmac.new(secret.encode(encoding="utf-8"), parameters_str.encode(encoding="utf-8"), digestmod=hashlib.sha256)
return h.hexdigest().upper()
其他程式设计语言的签名样例代码，请参阅官方 SDK 的原始程式码。
3.2.6 HTTP 请求样例
以 撞库接口(/product/get) API请求为例，组成 HTTP 请求的步骤如下：
第一步：填充基本参数
Common parameters:
- app_key = “000000”
- access_token = “test”
- timestamp = “1517820392000”
- sign_method = “sha256”
Business parameters:
第二步：根据ASCII表中的参数名称对所有参数和值进行排序
- access_token = “test”
- app_key = “000000”
- item_id = “676648141230”
- sign_method = “sha256”
- timestamp = “1517820392000”
第三步：将排序后的参数及其值连接到一个字串中
access_tokentestapp_key000000item_id676648141230sign_methodsha256timestamp1517820392000
第四步：在连接的字串前面添加API名称
/product/getaccess_tokentestapp_key000000item_id676648141230sign_methodsha256timestamp1517820392000
第五步：签名加密算法 - 生成签名
假设AppSecret = helloworld，则生成的签名为：
hex(sha256(/product/getaccess_tokentestapp_key000000item_id676648141230sign_methodsha256timestamp1517820392000))=4190D32361CFB9581350222F345CB77F3B19F0E31D162316848A2C1FFD5FAB4A
第六步：组装HTTP请求
使用 UTF-8 格式（参数的顺序可以是任意的）对所有参数和值进行编码（使用「sign」参数）。
http://api.taobao.global/rest/order/get?app_key=000000&access_token=test×tamp=1517820392000&sign_method=sha256&item_id=676648141230&sign=4190D32361CFB9581350222F345CB77F3B19F0E31D162316848A2C1FFD5FAB4A
第七步：请求与响应
response = {"data":{"quantity":600,"mp_id":"600130437909441230","item_id":676648141230,"item_type":"WITHOUT_MATERIAL","begin_amount":0,"shop_name":"Singor4","title":"印花抽绳短裤","user_nick":"惺惺相惜00","promotion_price":18800,"shop_id":36564296,"price":18800,"sku_list":[{"mp_skuId":4871614981760,"quantity":200,"price":18800,"postFee":800,"sku_id":4859054248495,"pic_url":"https://img.alicdn.com/bao/uploaded/i3/141330460/O1CN010dQVtm1FGix4S9yll_!!141330460.jpg","properties":[{"prop_name":"颜色","prop_id":1627207,"value_id":28338,"value_name":"蓝色"},{"prop_name":"尺码","prop_id":20518,"value_id":27432,"value_name":"1"}],"promotion_price":18800,"status":"active"},{"mp_skuId":4871614981761,"quantity":200,"price":18800,"postFee":800,"sku_id":4859054248496,"pic_url":"https://img.alicdn.com/bao/uploaded/i3/141330460/O1CN010dQVtm1FGix4S9yll_!!141330460.jpg","properties":[{"prop_name":"颜色","prop_id":1627207,"value_id":28338,"value_name":"蓝色"},{"prop_name":"尺码","prop_id":20518,"value_id":22027,"value_name":"2"}],"promotion_price":18800,"status":"active"},{"mp_skuId":4871614981762,"quantity":200,"price":18800,"postFee":800,"sku_id":4859054248497,"pic_url":"https://img.alicdn.com/bao/uploaded/i3/141330460/O1CN010dQVtm1FGix4S9yll_!!141330460.jpg","properties":[{"prop_name":"颜色","prop_id":1627207,"value_id":28338,"value_name":"蓝色"},{"prop_name":"尺码","prop_id":20518,"value_id":27433,"value_name":"3"}],"promotion_price":18800,"status":"active"}],"status":"active"},"success":true,"code":"0","request_id":"2101144116576106138264400"}
3.3 错误代码
所有 API 呼叫都会返回一个值，该值显示操作的状态（成功或错误），同时可能提供与指定操作相关的结果和/或详细信息。
当 API 呼叫失败时，系统也会返回请求 ID 和错误代码。常见的 API 呼叫错误有三类:
- SYSTEM：API 平台错误
- ISV：业务数据错误
- ISP：后端服务错误
API platform error (ISV errors)
The API platform errors usually occur because the request from a user does not fulfill the basic verification. When encountering such errors, check the authority, frequency and other conditions of the applications. Then, check the uploaded parameters for completeness and validity based on the API documentation.
Business data error (ISP errors)
These errors are the result of a business logic error, these errors are caused if you do not follow the certain business rules set out by the Lazada Platform (e.g. product creation rules, platform policy rules, etc).
When encountering such errors, check whether the corresponding information is uploaded based on the error information. It is recommended to try again after correcting such errors. Should you still receive the error messages, please reach out to the Lazada Partner Seller Support to find out the business
Backend service error
The backend service errors are usually caused by the availability of API service. Please try again after some time, if the issue persists, please contact our technical support team.
例如：
| 错误码 |
错误信息 |
描述 |
| ServiceTimeout |
The request has failed due to RPC timeout. |
接口调用超时。 |
| 502 Bad Gateway |
The proxy server received an invalid response from an upstream server. Sorry for the inconvenience. |
Qps过高，导致请求到网关失败，建议分销商做重试处理。 |
| InternalError |
The request processing has failed due to some unknown error, exception or failure. |
Api调用失败，请详细核对入参跟API文档是否正确。 |
4 调试与维护
4.1 API 测试工具
淘宝全球开放平台为您提供了一个「API测试工具」来测试平台上的 API，启动 API 测试工具的步骤如下：
- 打开应用程式控制台并点击应用程式的「管理」按钮；
- 在 APP 管理页面，从左侧导航条中找到并点击「API 测试工具」；
- 在 API 测试工具上，输入 API 名称，点选取得参数，系统会自动带出 API 的参数。
注意：API 测试工具使用对是来自生产环境的线上数据。
参数说明，API 测试工具参数描述如下：
| 名称 |
描述 |
值范例 |
| API Path |
要测试的 API 的路径。 |
/brands/get |
| HTTP Method |
大多数 API 是通过 GET 呼叫的，而一些获取额外请求数据的呼叫是通过 POST 发送的。 |
GET or POST |
| App Key |
您的应用程式在开放平台上的唯一标识，是在创建应用程式时生成的。 |
100126 |
| Access Token |
您的应用程式访问卖方敏感性数据所需的token。 |
|
| Business parameters |
要测试的 API 的业务参数。 |
依照选择的 API 会带出不同的参数栏位可以填写 |
| Request |
当指定了参数后，点击「开始测试｜按钮，请求 URL 将生成并显示在请求栏位中。 |
|
| Response |
指定参数的 API 回应正文。 |
|
4.2 部署应用程序
部署应用程序当您的应用程式开发和测试完成后，您可以将您的应用程式线上部署到托管环境中。
采取以下步骤来完成部署流程：
- 在应用程式清单中，点击「管理」打开应用程式的概述页面。
- 在 APP 概述页面，您可以在基本信息部分找到「APP 状态」字段。
- 点击线上申请。
- 在申请框的「原因」字段中输入要线上部署的应用程式的描述。
- （可选）根据需要为申请附加一个文档，可以是应用程式的测试报告。
- 点击「OK」。
一旦线上部署请求被批准，应用程式的状态将更改为线上。然后可以将应用程式部署到请求或计划的托管环境。
4.3 监控应用程序数据
应用程式线上发佈后，您可以通过 Data Dashboard 页面监控应用程式发起的 API 呼叫的统计数据。
数据仪錶盘提供以下类别的统计数据：
APP 统计 - 按一段时间内的API呼叫统计
- 日期
- 应用程式呼叫的API总数
- 总成功呼叫数
- 总失败呼叫数
- 平均QPS（每秒查询）
卖家统计 - 卖家在一段时间内的API呼叫统计
- 日期
- 卖方
- 卖方呼叫的API总数
- 平均QPS（每秒查询）
错误代码统计 - 在一段时间内的API错误代码统计
- API 名称
- 错误类型
- 错误代码
- 错误消息
- 每个错误的总数量
4.4 分销商测试账号借用
由于目前尚未提供测试环境，分销商没法进行下单、逆向等场景化测试。因此，跨境供货平台对外提供了分销商测试账号以及测试商品数据，方便进行OpenAPI下单及逆向的调试。但由于账号合规，不能对外披露账号及密码，所以需要分销商提供授权地址，由阿里内部人员进行授权，分销商基于阿里内部人员提供好的授权码code去生成相应的token，就可以进行下单、逆向等场景化测试了，如有疑问，请联系技术负责人。
- 拼接授权URL获取code（阿里内部人员进行分销商测试账号授权）
按照以下规则拼装授权URL（注意：请将「appkey」及「redirect_url」替换为您的开发者应用程式配置。）将拼接好的地址发给阿里内部人员进行相应授权。
| 淘宝商品ID |
供货平台商品ID |
SKU |
| 673822568257 |
600126025042468257 |
4852260841445,4852260841444 |
| 672991141190 |
600126245031041190 |
5016042822040,5016042822039 |
| 669105471437 |
600124745519971437 |
4988025539521 |
| 666852298083 |
600123880024398083 |
4812222941338,4812222941337 |
| 666821470073 |
600129202197070073 |
4860968496627,4860968496626 |
{
"error_msg": "[2101144116564048484455584d0793] errorMsg=测试账号不允许采购真实商品",
"data": {},
"success": false,
"error_code": "TEST_ACCOUNT_CAN_NOT_PURCHASE_REAL_PRODUCT",
"code": "0",
"request_id": "2101144116564048484456245"
}
5 API主要场景
5.1 正向交易场景
5.1.1 代购模式
快速采购流程（推荐1）：商品撞库-交易
场景描述：根据淘宝商品Id 通过以撞库（撞库：查询商品）的形式，获取淘宝商品所对应在跨境供货平台渠道商品模型，并对撞库成功的商品进行采购。
快速采购流程（推荐2）：淘宝相似款推荐-交易
场景描述：该场景主要为解决分销商通过商品图片搜索从而找到相关的同款产品，接口入参为商品图片或淘宝商品Id ，底层结合图搜能力获取该商品在淘宝全量商品池中的批量同款产品，用户可根据自身需要从返回的这批商品中进行下单采购。（类似用户在淘宝购物时，通过一张目标商品图片进行搜索，然后淘宝检索出对应相似的商品）。
5.1.2 导购模式
快速采购流程（推荐1）：导购铺货-交易
场景描述：平台根据用户需求，从商品池中选取一批商品铺给分销商，或分销商自己在跨境供货平台上手动选择所需商品进行铺货；铺货成功后供销平台系统会发送铺货成功消息给分销商，分销商可在开放平台开发者应用中订阅铺货消息，并对消息进行相应解析。获取商品信息（消息体主要有渠道商品Id、分销商Id等），在根据渠道商品Id调用跨境供货平台商品详情接口获取SKU等商品明细,持久化到自身系统平台，然后对商品进行下单采购。
快速采购流程（推荐2）：导购图搜-交易
场景描述：用户可根据采购商品图片或渠道商品ID搜索跨境供货平台商品池中的同款商品，然后拿到返回的商品Id在调用跨境供货平台导购商品详情接口获取SKU等商品明细，然后对商品进行采购交易。
5.2 逆向交易场景
5.2.1 售后流程
业务描述：分销通过供销平台发起的采购订单，其可通过供销平台界面进行相关售后操作，其次，也可采用如下图所示的场景，通过自身分销平台售后能力建设，接入跨界供销平台对外OpenAPI完成采购单的售后。在接入OpenAPI之前，需前往跨界供销平台体验界面化的售后流程，确保对整体流程的熟悉，方便之后的售后接口对接。（下图仅展示整体流程，其他逆向单查询、留言查询等查阅相关接口即可，同时不要忘记逆向消息的同步。）
6 API接口明细
6.1 相关API
API接口文档地址：
https://open.taobao.global/doc/api.htm#/api?cid=8&path=/auth/token/refresh&methodType=GET/POST
6.1.1 系统服务
6.1.2 商品服务
6.1.3 订单服务
| API名称 |
描述 |
Version版本（必看） |
| /purchase/order/asyn/cancel |
取消采购单。 注意：商家发货后，将无法通过该接口进行取消，需前往跨境供货平台发起售后逆向.（建议已支付采购单一律走售后接口）。 |
|
| /purchase/order/batch/pay |
采购单批量支付 注意：入参为跨境供货平台采购单ID，该接口为异步执行，仅作为支付的提交，并过滤掉不能支付的采购单，返回的结果仅供参考，最终必须通过采购查询接口去做信息同步，否则会出现数据一致性问题。 |
|
| /purchase/order/render |
订单渲染 描述:传入下单的商品信息、商品数量、以及收货地址来渲染订单信息。可以用于提前检验和过滤出库存不足、商品下架等原因引起的商品。另外渲染成功的订单信息包含商品原价、优惠价、订单优惠价信息、订单实付价。 订单错误码见第9章版本说明订单常见错误码 |
2023-01-11-订单渲染 灰度中 详细说明见第9章升级说明2023-01-11订单渲染 |
| /purchase/order/create |
创建采购单。 注意： 1.该接口背后采取的异步逻辑，成功与否可通过订阅采购单状态变更消息去同步数据（消息详情请看第8点消息服务）。 2.入参中的商品明细（商品ID一定要查商品接口返回的mp_id，sku_id也是取的mp_sku_id,否则无法正常创单！因为采用铺货后的数据模型） 3.outer_purchase_id 是幂等字段，记得每次创单必须保证自身唯一性。 4.市场 channel_order_type 主要看你具体应用场景：代购场景填：PANAMA_DG，导购场景：PANAMA（默认） |
|
| /purchase/orders/query |
采购单查询接口。 注意：注意该接口出参，已发货订单会有相应物流。 订单错误码见第9章版本升级说明2023-01-11订单常见错误码 |
2022-07-14-订单查询 |
6.1.4 售后服务
（1）整体业务流程
（2）售后接口明细
（3）逆向状态枚举
退款类型（refundType）
货物状态（goodsStatus）
描述：申请退款时，退款类型与货物状态可根据具体场景传对应值
退款类型和货物状态传参介绍
逆向单状态（refund_status）
7 场景问题
解决问题方案思路：
7.1 撞库常见问题
接口：/product/get
常见QA：
1.撞库失败常见问题
| 错误码 |
错误描述 |
解决方案 |
| SYSTEM_ERROR |
未查到淘宝商品 |
说明该淘系商品已删除或下架，请更换其他卖家进行购买 |
| SYSTEM_ERROR |
此商家商品不能通过分销方式售卖，请更换商家 |
根据提示更换一个商家进行商品采购 |
| SYSTEM_ERROR |
暂不支持购买淘特商品 |
目前暂不支持淘特商品 |
| SYSTEM_ERROR |
撞库不是供销平台签约商品 |
根据提示更换一个商家进行商品采购 |
| SYSTEM_ERROR |
铺货失败 |
联系相关供销平台技术负责人进行协助 |
| SYSTEM_ERROR |
批量撞库未查询到该商品的mpId |
联系相关供销平台技术负责人进行协助 |
7.2 创单常见问题
接口：/purchase/order/create
入参注意：
- 该接口背后采取的异步逻辑，成功与否可通过订阅采购单状态变更消息去同步数据（消息详情请看第8点）。
- 入参中的商品明细（商品ID一定要查商品接口返回的mp_id，sku_id也是取的
mp_sku_id,否则无法正常创单。）
- outer_purchase_id 是幂等字段，记得每次创单必须保证自身唯一性。
- 市场 channel_order_type 主要看你具体应用场景：代购模式填：PANAMA_DG，导购
模式：PANAMA（默认）
接口常见QA：
| 错误码 |
错误描述 |
解决方案 |
| GOODS_UN_BUILD_RELATION_OR_NOT_CORRECT |
商家未和该商品建立关系，请检查商品的正确性（用跨境供货平台商品ID）后重试创单600037765030623443 |
（1）检查渠道 channel_order_type 是否填错，根据API具体应用场景填写 （2）渠道正确的情况下，检查商品参数是否正确；着重看itemI（mp_id）, skuId (mp_sku_id), 是否都为跨境供货平台渠道商品模型属性。 （3）检查商品状态是否正常。 （4）前面几步都没问题都情况下，找技术负责人解决。 |
| B-10-00-005 |
GSP拆单异常 |
（1）检查渠道 channel_order_type 是否填错，具体应用场景。 （2）渠道正确的情况下，检查商品参数是否正确；着重看itemId（mp_id）, skuId (mp_sku_id), 是否都为跨境供货平台商品模型属性。 （3）检查商品是否正常。 （4）检查授权账号是否为跨境供货平台账号（而不是开放平台账号），两个平台账号是 分开的，不是同一个 （5）前面几步都没问题都情况下，找技术负责人解决。 |
7.3 采购单创单入参问题
接口：/purchase/order/create
| 名称 |
描述 |
| outer_purchase_id |
分销商自身系统所生成的订单ID，需保持唯一性。 |
| purchase_amount |
预估采购金额 |
| seller_order_number |
分销商自身系统所生成的订单号 |
| order_source |
订单来源 |
| order_line_list |
订单明细[商品ID一定要查商品接口返回的mp_id，sku_id也是取的mp_sku_id,否则无法正常创单。] |
| receiver |
收件人信息 |
| warehouse_address_info |
分销商国内代收仓地址（一般发往这个） |
| channel_order_type |
主要看你具体应用场景： [代购模式：PANAMA_DG｜导购模式：PANAMA] |
| support_partial_success |
如果客户填写默认参数（false/空），线上创单逻辑走“一个子单失败，整个主单失败” 如果客户填写指定参数（true），线上创单逻辑走“一个子单失败，部分子单成功，主单返回成功” |
| order_remark |
供应商留言备注（限制35字以内） |
7.4 查询淘宝商品详情常见问题
接口：/item/get
常见QA：
| 错误码 |
错误描述 |
解决方案 |
| SYSTEM_ERROR |
商品详情未查到淘宝商品 |
说明该淘系商品已删除或下架 |
| SYSTEM_ERROR |
商品详情暂不支持购买淘特商品 |
目前暂不支持淘特商品 |
7.5 支付常见问题
接口：/purchase/order/batch/pay
描述：入参为跨境供货平台采购单ID，该接口为异步执行，仅作为支付的提交，并过滤掉不能支付的采购
单，返回的结果仅供参考，最终必须通过采购查询接口去做信息同步，否则会出现数据一致性题。
出参：
注意：will_pay_purchase_order_ids 并非表示支付成功！而是提交了支付订单。
pay_failure_purchase_order_ids 表示无法提交支付！支付校验未通过。
详细出参：
{
"error_msg": "",
"code": "0",
"data": {
"will_pay_purchase_order_ids": "200001911633",// 已提交支付订单
"pay_failure_purchase_order_ids": "200000229005" // 提交失败订单
},
"success": "true",
"error_code": "BATCH_PAY_ERROR",
"request_id": "0ba2887315178178017221014"
}
8 消息接口文档
8.1 配置消息服务
开发者可在开放平台上配置一个回调 URL 来接收消息请求。该方式可以减少开发者通过轮询机制获取订单更新的尝试。
- 以开发者身份登入淘宝全球开放平台；
- 选择 APP console（APP 控制台）；
- 选择应用列表右侧的 Manage（管理）；
- 选择 Message service（消息服务）；
- 填写回调地址，选择 Verify（验证），若返回 HTTP 200 状态码，则会提示验证成功；
- 从列表中选择需要订阅的消息；
- 选择 Save（保存）。
例如：
有关消息接收通道的设计，请参考：
消息结构，请参考：
8.2 使用 HTTP 接收消息
注意：开发者需提供消息接收通道，接收推送形式为 HTTPS POST 请求。
8.2.1 回调地址
使用消息服务，需要准备一个接收消息的回调接口，请严格按以下要求执行：
- 请使用 https 协议的回调地址；
- 请使用 CA 签发的证书，需要 OV/EV 级；
- 收到消息后请返回 HTTP 200 状态码，确认签收消息。
8.2.2 消息的处理
- 请勿在收到消息的同时进行业务处理；
- 请收到消息后，存储至待处理队列中，并返回 HTTP 200 状态。在此之后异步消费消息；
- 订单中仅包含必要的标识信息，业务的详细情况请使用对应的查询接口查询。
消息示例 #1.正向交易信息示例（下单，付款，发货，收货等正向交易行为产生）
POST /example/uri HTTP/1.1
Host: www.example.com
Content-Type: application/json
Content-Length: 1238
Authorization: 34f7b258df045d4ed9341850ca85b866f34828fd7d51862f11137216294a894c
#消息体
{
"seller_id":"1234567", #卖家ID
"message_type":0,
"data":{
"order_status":"unpaid", #订单状态
"trade_order_id":"260422900198363", #主单Id
"trade_order_line_id":"260422900298363", #子单id
"status_update_time":1603698638 #订单状态更新时间 时间戳
},
"timestamp":1603766859530, #推送时间 时间戳
"site":"lazada_vn" # 站点信息
}
消息示例 #2.逆向交易信息示例（取消，退货退款，等逆向交易行为产生）
POST /example/uri HTTP/1.1
Host: www.example.com
Content-Type: application/json
Content-Length: 1238
Authorization: 34f7b258df045d4ed9341850ca85b866f34828fd7d51862f11137216294a894c
#消息体
{
"seller_id":"1000114855",
"message_type":0,
"data":{
"order_status":"canceled",
"reverse_order_id":"501977696648153", #逆向主单id
"reverse_order_line_id":"502491640048153", #逆向子单id
"status_update_time":1603703663,
"trade_order_id":"252883361348153", #关联正向单id
"trade_order_line_id":"252883361948153" #关联逆向单id
},
"timestamp":1603715010436,
"site":"lazada_vn"
}
8.2.3 重试及补偿
- 超过 500ms 服务端未收到 200 确认，服务端则认为消息推送失败；
- 失败后消息会在半个小时后重试推送，最大重试 12 次；
- 若系统中断超过 12 次重试，则请通过相关查询接口重新获取数据。
8.2.4 签名
建议开发者对收到的消息进行签名校验，以确保消息的合法性。
特别注意：在收到消息之后，切勿对消息体进行相应转换和修改！否则再次签名就不会不一致了。
使用 AppKey 拼接请求 Body 作为消息体，以 AppSecret 作为密钥，签名加密算法为 HMAC-SHA256。
签名产生 Sample Code
/*
其中Base = {your_app_key} + "{message_body_you_receieved}"
Secret = {your_app_Secret};
*/
Authorization = HEX_ENCODE(HMAC-SHA256(Base, Secret));
请使用下述代码生成签名与 Header 中的「Authorization」进行比较。
数据將使用明文传输，为安全起见，请对接收的消息作签名比对！
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
/**
* 签名工具类
* @author jianyan
* @date 2020/12/01
*/
public class SignatureUtil {
private static final String HMAC_SHA256 = "HmacSHA256";
private static final Logger LOGGER = LoggerFactory.getLogger(SignatureUtil.class);
/**
* 产生基于Hmac-SHA256，并经过16进制编码的签名。
* @param base {AppKey} + {messageBody}
* @param secret {AppSecret}
* E.g.: AppKey = 123456, AppSecret = 3412gyo124goi3124
* 收到的消息体Json ：{"seller_id":"1234567", "message_type":0, "data":{...}..}
*
* base = "123456" + "{\"seller_id\":\"1234567\", \"message_type\":0, "data":{...}..}"
* secret = 3412gyo124goi3124
* signature = getSignature(base, secret);
* signature = f3d2ca947f16a50b577c036adecd18bec126ea19cadedd59816e255d3b6104ab
* @return 签名
*/
public static String getSignature(String base, String secret) {
try {
Mac sha256Hmac = Mac.getInstance(HMAC_SHA256);
SecretKeySpec secretKey = new SecretKeySpec(secret.getBytes(), HMAC_SHA256);
sha256Hmac.init(secretKey);
return byteArraytoHexString(sha256Hmac.doFinal(base.getBytes()));
} catch (Exception e) {
LOGGER.error("Failed to generate signature");
}
return null;
}
/**
* 十六进制Encode
* @param bytes
* @return
*/
private static String byteArraytoHexString(byte[] bytes) {
if(bytes == null) {
return null;
}
StringBuilder sb = new StringBuilder();
String stmp;
for (byte aByte : bytes) {
stmp = Integer.toHexString(aByte & 0XFF);
if (stmp.length() == 1) {
sb.append('0');
}
sb.append(stmp);
}
return sb.toString().toLowerCase();
}
}
8.3 消息服务订阅
描述：分销商在调用开放平台API的同时，需搭配消息服务进行使用，主要核心为同步平台数据到自身系统平台，保持两边的数据一致性。
8.3.1 商品服务消息
注意点，仅支持场景：导购模式
分销商选品
message_type：2
触发节点：分销商在跨境供货平台铺货/取消铺货（PANAMA渠道）
{
"seller_id":"12345", // 分销商授权时可取得「seller_id」，详情参见：接口 AccessToken 。
"message_type":2,
"data":{
"seller_id":"12345",
"spu_ids_list":[
"223244",
"54543342"
]
},
"timestamp":123456789
}
临界库存变更
message_type：1
触发节点：每次触发库存更新。分别在“100”、“20”、“0”四个节点发送（PANAMA渠道）
{
"seller_id":"12345",
"message_type":1,
"data":{
"seller_id":"12345",
"item_id":"323434",
"sku_list":[
{
"sku_id":"123422"
}
],
"status":"STOCK_CHANGED"
},
"timestamp":123456787
}
商品上下架
message_type：0
触发节点：商家或平台小二触发商品上下架
{
"seller_id":"12345",
"message_type":0,
"data":{
"seller_id":"12345",
"item_id":32242,
"sku_list":[
"223244",
"54543342"
]
},
"timestamp":123456789
}
其中商品类消息，因为通过 API 推送数据给开发者，无法保证开发者收到消息的顺序性，所以请收到商品类消息后来反查 API，再做相关业务处理。
商家授权时可取得商家的「seller_id」，请参见：接口 AccessToken 。
商品价格变更
message_type：7
触发节点：供应商商品价格变更
{
"seller_id":"12345",
"message_type":7,
"data":{
"item_id":600027239042390035,
"seller_id":2100000978004,
"sku_list":[
4511721254067,
5466335674566
]
},
"timestamp":123456789
}
8.3.2 订单服务消息
订单状态变更
message_type：3
触发节点：采购单状态发生变更
消息体：
{
"seller_id": "2100000927014",
"message_type": 3,
"data": {
"business_time": 1650939687564,
"outer_purchase_id": "FY20220426002",
"purchase_id": 200002638011,
"seller_id": 2100000927014,
"sku_list": [{
"item_id": 600123256363335043,
"logistic_company_name": "顺丰速运",
"logistic_number": "SF4548527307631",
"order_line_no": "1",
"sku_id": 4808332513272,
"status": "WAIT_BUYER_CONFIRM_GOODS"
}],
"status": "WAIT_SELLER_SEND_GOODS"
},
"timestamp": 1650939687,
"site": "taobao_hk"
}
其中订单相关消息会给具体的状态，开发者可以信任直接使用，前提是已经做好以下处理：
-消息无序，需要通过反查 API（/purchase/orders/query）获取采购单进行同步。
采购单status的值：
| 采购单状态 |
描述 |
| BULIDING |
采购单创建中 |
| WAIT_BUYER_P |
等待付款 |
| WAIT_SELLER_SEND_GOODS |
已付款，待发货 |
| WAIT_BUYER_CONFIRM_GOODS |
已付款，已发货 |
| TRADE_CLOSED |
交易关闭 |
订单改价变更消息
注意：消息是无序的。最终需要反查 API（/purchase/orders/query）获取采购单进行同步。
message_type：8
触发节点：创建订单，联系淘宝卖家进行订单改价，支付后的订单不支持订单改价！
{
"seller_id": "2100000927014",
"message_type": 8,
"data": {
"features": {},
"salesOrderId": "500000-GSP2021031415594",
"salesSellerId": 2100000927014,
"purchaseMarket": "PANAMA",
"purchaseOrderId": 200002372069,
"purchaseOrderPriceDTO": {
"purchaseCurrency": "CNY",
"purchaseTotalFee": 1,
"purchaseProductFee": 1,
"purchaseShippingFee": 0
},
"purchaseOrderLinePriceChangeMessageDTOList": [{
"features": {},
"salesOrderLineIdList": ["1"],
"purchaseOrderLineId": 200002372070,
"purchaseOrderItemPriceDTO": {
"purchaseCurrency": "CNY",
"purchaseTotalFee": 1,
"purchaseProductFee": 1,
"purchaseProductUnitFee": 1,
"purchaseShippingFee": 0
},
"bizFeatures": {}
}],
"actionTime": 1647306796326,
"bizFeatures": {
"appKey": "500000",
"orderSource": "taobao",
"purchase_warehouse_address": "{\"city\":\"广州市\",\"country\":\"中国\",\"detailAddress\":\"落潭镇长腰岭村第三经济合作社长兴工业路3号派亚物流\",\"district\":\"白云区\",\"divisionId\":\"440111108\",\"mobile\":\"18500176747\",\"name\":\"李澳洲\",\"phone\":\"\",\"state\":\"广东省\"}",
"sellerOrderNumber": "-"
}
},
"timestamp": 1647306796,
"site": "taobao_hk"
}
改价注意事项
- 订单改价适用于3.15号以后创建的订单，之前创建过的订单不支持改价，请悉知。
- 当创建完后订单，觉得有可能改价的，联系淘宝卖家进行订单改价，支付后的订单不支持订单改价。
- 有一些商品有业务特定的规则，因此并不是所有的商品都支持改价。
- 有的订单淘宝关单时间很短(如30分钟)，如果超时未支付，此时在下单的时候系统会进行风控拦截(改价后订单已经关闭了，重新生成了一个新的订单)，此时还需要重新联系淘宝卖家对新的订单进行改价。如果在操作过程中有其它任何问题都可以直接咨询相关技术负责人。
8.3.3 售后服务消息
逆向单/留言同步消息
描述: 逆向单状态发生变更时，如卖家同意退款/退货等动作，都会触发消息通知分销商，其次留言有新增(卖家留言)或更新(留言图片覆盖)也会发送留言变更消息给分销商，分销商需要拿到对应消息，做逆向单同步、或留言同步，保持与供销平台数据一致性。
message_type：9
{
"seller_id": "2100000927014",
"message_type": 9,
"data": {
"sellerId": 2100000927014, // 分销商ID
"messageType": 2, // 1 逆向单同步｜2 留言同步
"refundId": 110000312001, // 逆向单ID
"businessTime": 1652266980661, // 消息发送时间戳
"purchaseOrderId": 2608284132117736161 // 采购单ID
},
"timestamp": 1652266980,
"site": "taobao_hk"
}
9 版本升级说明
2022-05-23-撞库
撞库接口（/product/get）升级全量商品
（1）全量商品推广
为了帮助分销商在跨境供货平台上能够找到更多的商品，避免因为商品不在跨境供货平台上导致无法下单，为此供销平台将在2022-05-22号上线“天猫淘宝全量商品”查询，提升商品查询成功率。但是由于天猫淘宝全量商品接入需遵循淘宝合规条例，非跨境供货商品不会提供商品素材信息（图片、描述等）。原签约商品不受此影响。在对接之前，请完整查询该文档，了解接口的更新内容以判断是否需要调整自身系统，避免影响业务。
（1）撞库接口（/product/get）
（2）相似款推荐接口（/product/recommend）
| item_type |
字段描述 |
响应模型 |
| “HAVE_MATERIAL” |
代表这为供销商品，会包含完整商品素材 |
响应数据全部字段正常返回 |
| “WITHOUT_MATERIAL” |
代表这为全量淘宝商品，仅包含部分商品信息（不包含商品图片、描述等） |
全量商品推广，合规：响应数据减少spu部分字段透出，sku保持不变。 少透出的6个spu字段： 1.category_path 类目路径 2.category_id 商品分类id 3.product_unit 商品单位 4.pic_urls 图片 5.begin_amount 起拍价 6.description 详情 |
分销商须知：须按如上规则点进行开发，不然会影响自身系统素材渲染等问题，会出现图片、详情等内容的 缺失，影响用户的体验以及单量。
2022-07-14-订单查询
订单查询（/purchase/orders/query）子单信息中增加物流列表
- 为了兼容国内商家发货的商家，目前手淘在履约上支持商家在子单维度进行拆包发货，即一个子单可以分多个包裹发出，在系统里回填时也可以回填多个单号。
- 但在给分销商透传的时候（不管是页面还是API），都只取了第一个包裹号展示出来，导致多包发货的情况下未展示的包裹被当成了无主件处理，影响了正常履约。
（1）订单查询（/purchase/orders/query）
增加logistic_orders 字段用于返回多物流的列表
开发平台文档中显示的和真实返回类型有出入，真实返回类型为数组如下图:
/purchase/orders/query 中的原物流信息字段logistic_number 、logistic_company_name、rts_time已过时，未来不会进行维护。建议使用logistic_orders字段获取物流信息。
2022-08-04-接口类目信息替换
导购型分销商，由于获取商品素材信息来源接口为（/product/details/query），而该接口目前返回的类目信息均为映射类目（category_id、category_name后续不再维护）。现平台对类目信息进行调整，统一返回淘系类目，以方便分销商根据分类进行区分展示。在此之前，需要找我们业务及运营同学获取一份淘系类目树。
（1）查询导购商品详情接口（/product/details/query）
（2）查询品商关系接口（/product/spus/get）
| 返回新增字段 |
示例值 |
字段描述 |
| tb_category_id |
50000697 |
淘宝商品最小类目 |
| tb_category_path |
女装/女士精品>毛针织衫 |
淘宝商品类目路径 |
例如：
{
"error_msg": "system error",
"code": "0",
"data": {
"goods_info_list": {
"tb_category_id": "50000697",
"tb_category_path": "女装/女士精品>毛针织衫",
"images": "https://img.alicdn.com/bao/uploaded/i4/2206884252030/O1CN01AqHRJ01QrmdqEQID0_!!2206884252030.jpg",
"skus": {
"images": "https://img.alicdn.com/bao/uploaded/i4/2206884252030/O1CN01AqHRJ01QrmdqEQID0_!!2206884252030.jpg",
"price": "1",
"width": "-",
"length": "-",
"weight": "-",
"currency": "CNY",
"sku_id": "4683815098027",
"attributes": "-",
"inventory": "99999",
"height": "45",
"status": "NORMAL"
},
"error_msg": "error msg",
"category_name": "null",
"item_id": "600068435000185100",
"brand_name": "-",
"sourceMarket": "GONGXIAO_OFFLINE",
"title": "Please Do Not Order Weight for Testing",
"inventory": "199998",
"spu_attributes": "--",
"tagList": "[\"2129922\"]",
"short_title": "-",
"supplier_nick": "-",
"category_id": "201242681",
"cn_title": "Chinese title",
"success": "success flag",
"rich_text": "\u003cp\u003etest\u003c/p\u003e",
"price": "1",
"error_code": "error code",
"currency": "USD",
"attributes": "-",
"status": "NORMAL"
}
},
"success": "true",
"error_code": "500",
"request_id": "0ba2887315178178017221014"
}
2022-08-11-品商关系查询
查询品商关系接口（/product/spus/get）兼容多种数据读取方式
- 当前巴拿马分销商选品铺货需要基于品商关系查询接口拉取数据或通过开放平台消息服务订阅“分销商选品”消息去同步铺货数据。
- 由于当前数据存储引擎的限制，分销商选择基于品商关系查询接口拉取数据时，会存在无法突破查询5000条限制的情况。比如xx分销商需要拉取“2022-08-01 00:00:00 - 2022-08-05 00:00:00”期间的铺货数据，该时间段内总计铺货数达到了2w多条，也就是results_total = 2w，但是如果采取普通分页读取的方式，条件不变的情况下，那么最多只能查询5000条数据，无法继续往下查询（除非时间段移动）。该限制平台短期内不会进行处理，但提供了另一种数据读取的方式（scroll读取）以解决当前问题。
| QueryProductSpuList 查询 |
是否支持时间筛选 |
是否支持排序 |
是否支持分页 |
是否支持全量数据 |
| 方案一：普通分页读取 |
支持 |
支持 |
支持 |
不支持 |
| 方案二：scroll方式读取 |
支持 |
不支持 |
不支持 |
支持 |
描述：根据时间片分段读取，尽可能把时间细分为多个时间段。
步骤：
- 请求入参必传start_modified_time ~ end_modified_time + page_size + sort_field（值为“modified”）+ sort_type（值为“ASC”）。
- 假设 page_size = 50, 那么page_no最大为100。当用户想读取101页数据时，超过100需要重置page_no为1，且需要重置“start_modified_time”为上一次100页的最后一条数据作为此次查询的开始时间，其它保持不变即可。
- 判断数据是否读取完毕：当 data 数据为空既查询结束 。
示例：
注意点：
- 如果查询结果results_total > 5000，那么想拉取全部数据，必须根据如上规则查询才能获取全部数据。
描述：基于某一时间段内的快照数据方式读取，通过滚动的方式拉取完所有铺货数据。
步骤：
- 请求入参必传start_modified_time ~ end_modified_time + page_size （只允许首次设置，下一次设置无效，取值范围[1,500]）+ spus_get_type (值为“SCROLL”，否则不生效，默认走普通分页) + scroll_id
- 入参scroll_id首次可为空，下一次查询需以上一次查询返回的scroll_id作为参数值进行查询。
- 判断数据是否读取完毕：当 surplus_total == 0 或 data 为空则结束查询 。
示例：
注意点：
- sort_type、sort_field失效，无法设置排序。
- page_size 只允许首次设置，下一次设置无效，取值范围[1,500]，且设置的页码page_no失效。
- 每次读取的总记录results_total、surplus_total会刷新返回，results_total 首次查询时返回为总记录数，分销商有需要可存储。
- 数据一致性问题：scroll方式读取，某一时间段内的快照数据。如果此时间段有新插入或修改数据，则无法读取到，除非重新获取一次快照数据。那么分销商读取时间区间将不能超过当前时间，否则数据一致性问题。
2023-01-11-订单渲染
入参
| 名称 |
类型 |
是否必须 |
示例值 |
说明 |
| render_item_List |
String |
Y |
[{"itemId":600120680003951077,"quantity":"1","skuId":4951323355633,"chooseSupplychainServices":[{"optionId":1,"serviceCategory":"LOGISTICS"},{"optionId":2,"serviceCategory":"QUALITY_INSPECTION"},{"optionId":3,"serviceCategory":"ADVANCED_QUALITY_INSPECTION"}]}] |
需要渲染的商品信息列表 传入List<ItemInfo>的JSON形式 （见下文 入参对象ItemInfo） |
| need_supplychain_service |
Boolean |
Y |
true |
是否需要供应链服务 |
| warehouse_address |
Address |
N |
{"zip":"11111","country":"中国","address":"测试地址","phone":"","city":"杭州市","mobile_phone":"15068763421","district":"余杭区","name":"a测试aa","cpf":"","state":"浙江省"} |
国内仓地址 不需要供应链服务时必传 （见下文 入参对象Address） |
| receiver_address |
Address |
N |
{"zip":"11111","country":"United States","address":"The State University of New York College at Buffalo","phone":"","city":"Buffalo","mobile_phone":"150","district":"","name":"a测试aa","cpf":"","state":"New York"} |
海外收货地址 需要供应链服务时必传 （见下文 入参对象Address) |
出参
入参对象
Address
| 名称 |
类型 |
是否必须 |
示例值 |
字段说明 |
| name |
String |
N |
desers |
姓名 （下单接口必传） |
| phone |
String |
N |
不传情况填写"" |
电话 |
| mobile_phone |
String |
N |
1231123 |
移动电话（下单接口必传） |
| country |
String |
Y |
US |
国家 |
| state |
String |
N |
Texas |
省份（下单接口必传） |
| city |
String |
N |
Dallas |
城市（下单接口必传） |
| district |
String |
N |
不传情况填写"" |
区 |
| address |
String |
N |
- |
详细地址（下单接口必传） |
| zip |
String |
N |
1111 |
邮政编码（下单接口必传） 美国邮编由5位数字构成 巴西邮编由5位数字+‘-’+3位数字构成 如 12345-678 |
| taxId |
String |
N |
12341 |
税号（下单接口巴西必传） |
ItemInfo
SupplychainService
| 名称 |
类型 |
是否必须 |
示例值 |
字段说明 |
| option_id |
Long |
Y |
1 |
物流方案ID |
| service_category |
String |
Y |
Logistics |
供应商服务的类目 目前需要传入三种服务 分别是 LOGISTICS（基础物流服务） QUALITY_INSPECTION（质检服务） ADVANCED_QUALITY_INSPECTION（高级质检） |
出参对象
RenderOrderInfo
ItemPriceInfo
DeliveryOption
| 名称 |
类型 |
是否必须 |
示例值 |
字段说明 |
| option_id |
Long |
Y |
1 |
服务方案id |
| name |
String |
Y |
巴西空运 |
方案名称 |
| service_category |
String |
Y |
LOGISTICS |
服务类目 |
| is_must_select |
Boolean |
Y |
true |
是否必选 |
| description |
String |
Y |
- |
描述 |
| shipping_fee |
Money |
Y |
123 |
运费/服务费 （见下文 出参对象Money） |
| shipping_time |
ExpectDay |
Y |
- |
物流方案时间 （见下文 出参对象ExpectDay ） |
UnavailableSku
| 名称 |
类型 |
是否必须 |
示例值 |
说明 |
| item_id |
Long |
Y |
600120680003951077 |
不可用商品Id |
| sku_id |
Long |
Y |
4951323355634 |
不可用商品skuId |
| reason |
String |
Y |
查询到商品为空，商品不可用 |
失败原因 |
| error_code |
String |
Y |
F-10001-01-16-001 |
失败code |
| error_msg |
String |
Y |
ITEM_CANNOT_BUY |
失败说明 |
Money
| 名称 |
类型 |
是否必须 |
示例值 |
说明 |
| amount |
Long |
Y |
123 |
金额（单位：分） |
| currency |
String |
Y |
- |
币种 |
2023-01-11-订单常见错误码（正在更新中）
|
CODE
|
可读错误码
|
错误描述_EN
|
错误描述_CN
|
|
B-00903-10-15-010
|
无
|
bus ticket price is invalid
|
系统繁忙，请稍后再试
|
|
F-10006-03-16-004
|
BUY_QUANTITY_NOT_MATCH_MIN_LIMIT
|
The buy quantity not match the min limit: {0}
|
未达到最小可购买数量：{0}
|
|
B-00118-00-15-001
|
ILLEGAL_TRANSPORTATION_METHOD
|
illegal transportation method
|
不合法的运送方式。比如买家付邮费时却没传运送方式
|
|
P-02306-11-16-011
|
HOT_ITEM_BLOCK
|
hot item block
|
亲，系统繁忙，请稍后再试
|
|
P-02306-11-16-001
|
CAN_NOT_BUY_FROM_PC
|
can not buy from pc
|
不支持PC购买
|
|
F-10000-00-16-099
|
UNKOWN_SYSTEM_ERROR
|
Unkonwn system error.
|
啊哦，系统太忙了，等会再来试试吧！
|
|
F-00103-00-16-113
|
REDUCE_INVENTORY_FAIL
|
reduce inventory error.
|
库存不足
|
|
F-10012-01-16-016
|
SUCCESS_RATE_OPTIMIZE_DOUBLE11
|
SUCCESS_RATE_OPTIMIZE_DOUBLE11
|
亲，该商品目前无法购买，建议您稍后再试
|
|
F-10012-01-16-001
|
BLOCK_BY_MTEE
|
blocked by mtee, error message:{0}
|
亲，同一时间下单人数过多，建议您稍后再试
|
|
F-10001-01-16-001
|
ITEM_CANNOT_BUY
|
Item cannot buy2, item id: {0}, sku id: {1}
|
商品不能购买
|
|
F-10001-01-16-011
|
AUCTION_ITEM_CANNOT_BUY
|
Auction item cannot buy, item id: {0}, sku id: {1}
|
商品不能购买
|
|
B-00504-01-16-001
|
无
|
无
|
系统繁忙，请稍后再试
|
|
B-50018-00-01-001
|
无
|
The QrCode's mobile is not right. mobileNo: {0}
|
请填写正确的手机号码！
|
|
F-10003-11-16-001
|
MAX_BUY_QUANTITY_EXCEEDED
|
inventory not enough
|
购买数量超过了限购数。可能是库存不足，也可能是人为限制。
|
|
F-10003-11-16-006
|
SIC_RESULT_FAIL
|
queryItemRegionalExt result is false . itemId
|
该商品不可售
|
|
F-10003-11-16-007
|
REDUCE_INVENTORY_FAIL
|
reduce inventory fail
|
库存扣减失败
|
|
F-10003-11-16-002
|
INVENTORY_AREA_LIMIT_ERROR
|
area inventory not enough
|
抱歉，该商品在收货地址内不可售，请重选收货地址！
|
|
F-10003-11-16-003
|
ITEM_OVER_SOLD
|
item or sku is oversold
|
购买数量超过了限购数。可能是库存不足，也可能是人为限制。
|
|
P-01415-10-16-042
|
STORE_QUERY_HAS_EXCEPTION
|
STORE_QUERY_HAS_EXCEPTION
|
亲，系统繁忙，请稍后重试！
|
|
F-10000-01-16-000
|
SYSTEM_ERROR
|
System error.
|
系统繁忙，请稍后重试！
|
|
P-10000-11-16-014
|
HOT_ITEM_CAN_NOT_BUY
|
hot item can't buy
|
抱歉，该商品当前时间不能购买，请在活动开始后重试，谢谢!
|
|
P-02309-11-10-002
|
UNKNOWN_ERROR
|
Unknown system: {0}, {0}
|
啊哦，系统太忙了，等会再来试试吧！
|
|
F-10000-00-16-100
|
RESTART_RENDER_PROCESS
|
Restart the Render process..
|
因为产生了新的不确定订单，重新走渲染流程
|
|
P-01415-00-16-102
|
TOO_MANY_TIMES_TRY_RE_RENDER
|
Have re-render order more than 10 times, aborted.
|
对不起，系统繁忙，请稍候再试
|
|
F-10000-00-16-101
|
FAIL_RESTART_RENDER_PROCESS
|
Failed to re-start the render process, due to the temp OrderLine list is null or error code is not right. Temp OrderLine List size: {0}, errorCode: {1}
|
不能重新走渲染流程，可能原因，不确定OrderLine列表为空，或者ErrorCode不正确.
|
|
P-10000-11-17-019
|
CREATE_ORDER_FLOW_CONTROL_HOT_ITEM
|
hot item flow control for create order
|
热卖商品创单限制
|
|
P-10000-11-17-018
|
CONFIRM_SINGLE_ITEM_FLOW_CONTROL
|
single item flow control for confirm
|
商品创单限制
|
|
F-10004-03-16-004
|
MISSING_ITEM_PRICE
|
missing item price
|
商品价格获取失败
|
|
F-10001-01-16-023
|
SKU_IS_MISSING
|
Sku is missing from IC, itemId: {0}, skuId: {1}
|
找不到商品
|
|
F-10005-11-10-005
|
QUERY_PROMOTION_FAIL
|
query promotion ex interrupt error
|
优惠查询失败
|
|
F-10005-11-10-003
|
USING_PROMOTION_FAIL
|
call UsingPromotion error. code:{0}
|
优惠失效，请刷新页面选择其他优惠
|
|
F-10005-11-10-004
|
REDUCE_PROMOTION_INVETORY_FAIL
|
call dealAfterPromotion error. code:{0}
|
优惠失效，请刷新页面选择其他优惠
|
|
F-10005-11-10-002
|
USING_PROMOTION_FAIL
|
call UsingPromotion exception error.
|
优惠失效，请刷新页面选择其他优惠
|
|
P-02114-10-16-002
|
ITEM_WITH_AREAS_LIMITED
|
ITEM_WITH_AREAS_LIMITED
|
您所购买的商品不在限购支持的区域内，暂不能购买。
|
|
F-10002-11-10-001
|
CALL_DELIVERY_QUERY_ABILITY_SERVICE_ERROR
|
call delivery queryAbility service error
|
无可用运输方式
|
|
F-10002-11-10-002
|
CALL_DELIVERY_CONFIRM_ABILITY_SERVICE_ERROR
|
call delivery confirmAbility service error
|
无可用运输方式
|
|
F-10002-11-10-039
|
CONFIRM_ABILITY_RESULT_FALSE
|
the confirm result is false after call confirm ability
|
无可用运输方式
|
|
F-10002-01-16-019
|
SPLIT_SERVICE_ERROR
|
split error!
|
系统异常
|
|
F-10002-03-16-013
|
无
|
item can't buy
|
您所购买的商品不在限购支持的区域内，暂不能购买。
|
|
F-10002-11-10-022
|
QUERY_ABILITY_RESULT_NULL
|
delivery ability result is null
|
无可用运输方式
|
|
F-10002-01-99-008
|
无
|
system error!
|
系统异常
|
|
B-PNM-001
|
INVALID_PARAMETERS
|
INVALID_PARAMETERS
|
传入参数非法
|
