Tokens API使用案例指南

亚马逊SPAPI

# 什么是代币API?

Selling Partner API for Tokens (Tokens API)提供了一种安全的方式来访问客户的个人身份信息(PII).你可以调用[createRestrictedDataToken](https: //spapi.cyou/zh/references/tokens-api-v2021-03-01-reference.html#post-tokens2021-03-01restricteddatatoken)操作,为你指定的一个或多个受限资源获取受限数据令牌(RDT)或者如果你有一个 "委托人应用程序 "你可以从一个与你密切合作的开发者所拥有的 "委托人应用程序 "中获得RDT(参见委托授权.在这两种情况下,RDT授权你对返回受限数据的操作进行调用.关于定义,参见术语.

当你调用限制性操作时,你在x-amz-access-token头中包含一个RDT.这与其他Selling Partner API操作不同,你在x-amz-access-token头中包含一个LWA访问令牌.更多信息,见Step 3.Add headers to the URI (opens new window) in the Selling Partner API Developer Guide._

# Delegating authorization

通过Token API,委托人应用程序可以获得一个RDT,该RDT将访问PII的授权委托给受委托人应用程序.受委托人应用程序由销售伙伴授权,是销售伙伴与之互动的应用程序.受委托人应用程序执行一个需要PII的专门功能这两个应用程序由不同的开发者拥有,并且是紧密结合的,因此委托者应用程序可以安全地将RDT传输给被委托者应用程序.关于使用RDT进行授权的更多信息,请参见TutorialDelegate authorization to access PII.

# Terminology

  • 限制性数据令牌(RDT).一种短期-访问令牌,授权调用限制性操作.一个RDT的有效期为一个小时.

  • 限制性操作. 一个返回限制性数据的操作,例如PII. 你需要一个RDT来调用限制性操作.

  • 限制性资源. 一个代表限制性操作的HTTP方法和路径.

  • 受限制的报告类型. 一个包含PII的报告类型.见受限制的报告类型.

  • 委托人应用程序.一个获得RDT并将其传递给受委托人应用程序的应用程序.销售伙伴授权并与委托人应用程序进行互动.

  • 被委托人应用程序. 一个获得授权的应用程序,从被委托人应用程序传递给它的RDT中调用受限制的操作. 被委托人应用程序执行需要PII的专门功能,如运输、税收发票或税收汇款服务,并且没有被销售伙伴直接授权.

  • 特定路径. 限制资源中包含特定订单或货物标识符的路径. 例如,orders/v0/orders/902-3159896-1390916/address

  • 通用路径. 在一个受限资源中的路径,包含一个通用的标识符,如{订单ID}{货物ID}. 例如,orders/v0/orders/{订单ID}/address

# Restricted operations

限制性操作返回客户的个人身份信息(PII).你需要一个RDT来调用限制性操作.

以下是受限操作的列表,按API分组

Direct Fulfillment Orders API:

  • `getOrders'.
  • `获取订单'

直接履行发货API

  • getShippingLabels: - getPackage.
  • `getPackingSlips'(包装单)
  • 获取客户发票

商户履行API

  • getShipment(获取货物)
  • "取消货物": - "取消货物"?
  • 撤销货件的旧版本
  • `创建货件'.

订单API:

  • `getOrders'(获取订单)
  • "获取订单"(getOrder)
  • "获取订单项目"(getOrderItems)
  • `getOrderRegulatedInfo'(获取订单信息)

报告API

  • `getReportDocument'.

    注释.

    • getReportDocument操作只有在指定了限制性报告类型时才被认为是限制性操作.请看限制性报告类型列表.
    • 当调用 "createRestrictedDataToken "操作为 "getReportDocument "操作获取RDT时,指定的受限资源只能包含一个特定的路径,而不是一个通用的路径. 关于定义,请参见术语.

货运发票

  • `getShipmentDetails'.

运送API

  • `getShipment'(获取货物)

# 受限制的报告类型

受限制的报告类型包含PII.当在调用getReportDocument操作中指定一个受限制的报告类型时,你必须在调用中传递一个RDT.

下面是一个受限制的报告类型的列表

  • get_amazon_fulfilled_shipments_data_invoicing(获取AMAZON_fulfilled_shipments_data的发票)
  • get_amazon_fulfilled_shipments_data_tax(获取AMAZON_fulfilled_shipments_data_tax)
  • get_flat_file_actionable_order_data_shipping(获取可操作订单数据)
  • get_flat_file_order_report_data_shipping(获取扁平文件的订单数据)
  • "获取扁平化的订单报告_发票数据"
  • 扁平文件订单报告中的税收数据
  • Get_flat_file_orders_reconciliation_data_tax(平坦文件)
  • Get_flat_file_orders_reconciliation_data_invoicing(平坦文件)
  • "获取平坦的文件_订单_调节数据_运输"
  • "获取开票数据的订单报告"
  • "获取订单报告中的税收数据"
  • "获取订单报告数据 "的发货信息
  • "获取易货贸易文件"
  • Get_gst_mtr_b2b_custom(定制)
  • "获取增值税交易数据" -`sc_vat_tax_report'(增值税报告)

# Tutorial: 获得授权以访问大宗订单的PII

你可以得到一个RDT,它提供访问个人身份信息的授权(PII),用于批量订单. 你指定的dataElements值(使用[restrictedResources](https //spapi.cyou/zh/references/tokens-api-v2021-03-01-reference.html#restrictedresource)参数的createRestrictedDataToken操作)决定RDT授权你的应用程序访问的限制数据的类型.在这个教程中我们请求一个RDT,授权访问买方信息和运输地址信息.

先决条件

要完成本教程,你将需要

-来自你为之调用的销售伙伴的授权.更多信息请参见销售伙伴API开发者指南 (opens new window).

  • 对访问买方信息和/或送货地址信息所需的角色的批准.这些角色是:

    • **直接-到-消费者运输.**需要访问运输地址信息.
    • 税款汇出. 需要访问买方信息.
    • 税收发票. 需要访问买方信息.

    要申请访问这些角色,请参阅《销售伙伴API开发者指南》中的注册为开发者 (opens new window),并更新你的开发者资料.

# 步骤1.获得一个RDT

调用createRestrictedDataToken操作来获得一个RDT.

  1. Call the createRestrictedDataToken (opens new window) operation, passing the following parameters:

主体参数

属于 "是"
参数 描述需要
restrictedResources

限制性资源的模型.最大50

类型RestrictedResource

请求示例:

POST https://sellingpartnerapi-na.amazon.com/tokens/2021-03-01/restrictedDataToken
{
  "restrictedResources": [
    {
      "方法": "GET",
      "path": "/orders/v0/orders",
      "dataElements": ["buyerInfo", "shippingAddress"]
    }
  ]
}
1
2
3
4
5
6
7
8
9
10

# Response

一个成功的响应包括以下内容

名称描述
restrictedDataToken

A 限制性数据令牌(RDT).这是一个短的-寿命的访问令牌,授权调用您指定的限制性资源所代表的限制性操作.在随后调用限制性操作时,在x-amz-access-token头中传递这个值.

类型: string

expiresIn

RDT的寿命,以秒为单位.

类型: 整数

响应的例子:

{
  "restrictedDataToken": "Atz.sprdt|IQEBLjAsAhRmHjNgHpi0U-Dme37rR6CuUpSR",
  "expiresIn": 3600
}
1
2
3
4

2.保存restrictedDataToken值(RDT)在Step 2.包括RDT与对getOrders的调用 operation

# 步骤2.包括RDT与对getOrders操作的调用

调用[getOrders](https //spapi.cyou/zh/references/orders-api-v0-reference.html#get-ordersv0orders)操作的订单API指定适当的参数来过滤你想要的订单.确保包括来自步骤1.获取RDT中的RDTx-amz-access-token是你调用getOrders.的头,因为你在Step 1.获取RDT中同时指定了buyerInfoshippingAddress你对getOrders的调用被授权为每个订单返回买方信息和运输地址信息.如果你在步骤1中只指定了buyerInfo,getOrders将被授权为每个订单只返回买方信息.如果你在步骤1中只指定shippingAddress,getOrders将被授权为每个订单只返回运输地址信息.

# Tutorial: 获取授权以访问订单中的PII项目

你可以得到一个RDT,它提供了访问指定订单中的订单项目的个人身份信息(PII)的授权.在这个工作流程中,你指定dataElements=buyerInfo,表示RDT将授权你的应用程序访问订单项目的买家信息.

先决条件

要完成本教程,你将需要

-来自你为之调用的销售伙伴的授权.更多信息请参见销售伙伴API开发者指南 (opens new window).

  • 对访问买方信息所需的角色的批准.这些角色是

    • 税款汇出
    • 开具税务发票

    你可能只需要批准其中一个角色,这取决于你的使用情况. 要申请访问这些角色,请参阅《销售伙伴API开发者指南》中的注册为开发者 (opens new window),并更新你的开发者资料.

# 步骤1.获得一个订单ID

您需要一个订单ID来识别您想要的订单项目信息.您也需要一个订单ID来获得一个RDT,授权您的应用程序访问订单项目的买方信息.您可以使用Orders API的getOrders操作来获得一个订单列表,您可以从中获得您感兴趣的订单的订单ID.

1.调用Orders API的getOrders (opens new window)操作,指定适当的参数来过滤您想要的订单.

该操作会返回符合您要求的订单.每个订单包括一个订单ID.

2.从返回的订单中,确定您想要的订单项目信息.

3.保存您想要的订单ID在步骤2.获得一个RDT步骤3.包括RDT与调用 getOrderItems operation.

# 步骤2.获得一个RDT

调用createRestrictedDataToken操作来获得一个RDT. 在restrictedResources参数的path属性中包括来自步骤1的订单ID.获得一个订单ID.在这个工作流程中,我们将指定dataElements参数的buyerInfo值.这表明RDT应该提供访问PII的授权,用于税收和礼品包装等用例.

调用createRestrictedDataToken操作来获得一个RDT.

  1. Call the createRestrictedDataToken (opens new window) operation, passing the following parameter:

主体参数:

属于 "是"
参数 描述需要
restrictedResources

限制性资源的模型.最大50

类型RestrictedResource

请求示例:

POST https://sellingpartnerapi-na.amazon.com/tokens/2021-03-01/restrictedDataToken
{
  "restrictedResources": [
    {
      "方法": "GET",
      "path": "/orders/v0/orders/123-1234567-1234567/orderItems",
      "dataElements": ["buyerInfo"]
    }
  ]
}
1
2
3
4
5
6
7
8
9
10

# Response

一个成功的响应包括以下内容

名称描述
restrictedDataToken

A 限制性数据令牌(RDT).这是一个短的-寿命的访问令牌,授权调用您指定的限制性资源所代表的限制性操作.在随后调用限制性操作时,在x-amz-access-token头中传递这个值.

类型: string

expiresIn

RDT的寿命,以秒为单位.

类型: 整数

响应的例子:

{
  "restrictedDataToken": "Atz.sprdt|IQEBLjAsAhRmHjNgHpi0U-Dme37rR6CuUpSR",
  "expiresIn": 3600
}
1
2
3
4

2.保存restrictedDataToken值(RDT)在步骤中使用 3.在调用getOrder操作时包括RDT.

# 步骤3.包括RDT与对getOrderItems操作的调用

调用[getOrderItems](https //spapi.cyou/zh/references/orders-api-v0-reference.html#get-ordersv0ordersorderidorderitems) operation of the Orders API, 指定你在步骤1.获取订单ID.中确定的订单ID,确保在调用getOrderItems.的x-amz-access-token头中包含步骤1的RDT

# Tutorial: 委托授权来访问PII

你可以将调用限制性操作的授权委托给 "受委托的应用程序",这是一个为销售伙伴执行专门功能的应用程序(,如运输、税收发票或税收汇款服务),但不直接由销售伙伴授权. 你通过这种方式委托授权

1.调用Token API的createRestrictedDataToken (opens new window)操作(指定受委托应用的应用ID) 2.从 "createRestrictedDataToken "响应中获得一个RDT,并且 3.将RDT传递给被委托人的应用程序.

RDT授权被委托人应用程序调用限制性操作,返回代表销售伙伴执行功能所需的PII.定义见术语.

先决条件

要完成本教程,你需要

此外,在步骤3.被委托人应用程序的开发人员调用getOrder操作将需要

# 步骤1.获得一个RDT

调用createRestrictedDataToken操作来获得一个RDT.在restrictedResources参数的path属性中包括需要PII的订单ID. 在这个工作流程中,我们将同时指定dataElements'参数的buyerInfo'和`shippingAddress'值. 这表明RDT应该包括访问PII的授权,如税收和运输. 在你自己的工作流程中,你可能只指定一个值,这取决于你的用例所需的PII.

  1. Call the createRestrictedDataToken (opens new window) operation, passing the following parameters:

主体参数:

属于 "是"
参数 描述需要
restrictedResources

限制性资源的模型.最大50

类型RestrictedResource

targetApplication

被委托访问的目标应用程序的应用程序ID.

类型: string

没有

请求示例:

POST https://sellingpartnerapi-na.amazon.com/tokens/2021-03-01/restrictedDataToken
{
  "restrictedResources": [
    {
      "方法": "GET",
      "path": "/orders/v0/orders/123-1234567-1234567",
      "dataElements": ["buyerInfo", "shippingAddress"]
    }
  ],
  "targetApplication": "amzn1.sellerapps.app.target-application"
}
1
2
3
4
5
6
7
8
9
10
11

# Response

一个成功的响应包括以下内容

名称描述
restrictedDataToken

A 限制性数据令牌(RDT).这是一个短的-寿命的访问令牌,授权调用您指定的限制性资源所代表的限制性操作.在随后调用限制性操作时,在x-amz-access-token头中传递这个值.

类型: string

expiresIn

RDT的寿命,以秒为单位.

类型: 整数

响应的例子:

{
  "restrictedDataToken": "Atz.sprdt|IQEBLjAsAhRmHjNgHpi0U-Dme37rR6CuUpSR",
  "expiresIn": 3600
}
1
2
3
4

2.保存restrictedDataToken值(RDT),以便在下面的步骤中提供给受权人应用程序.

# 步骤2.将RDT和订单ID传递给受托人应用程序

安全地传输RDT和订单ID给受委托的应用程序.该应用程序将在以下步骤中调用getOrder操作时使用这些数据.

# 步骤3.被委托人应用程序调用getOrder操作

被委托人应用程序调用[getOrder](https: //spapi.cyou/zh/references/orders-api-v0-reference.html#get-ordersv0ordersorderid)操作的订单API在路径中指定来自步骤2的订单ID.将RDT和订单ID传递给被委托人的应用程序.该调用必须 在调用的 "x-amz-access-token "头中包括RDT(也是来自步骤2)对getOrder的调用会返回订单的买方信息和送货地址信息.

1.受委托的应用程序调用getOrder (opens new window)操作,传递以下参数

主体参数

参数 描述需要
orderId

一个亚马逊-定义的订单标识符,以3-7-7的格式.

类型: string

是的

请求示例:

GET https://sellingpartnerapi-na.amazon.com/orders/v0/orders/123-1234567-1234567
1

# Response

一个成功的响应包括以下内容

名称描述
payload

getOrder操作的有效载荷.

类型Order

响应的例子:

{
  "payload": {
    "AmazonOrderId": "902-3159896-1390916",
    "PurchaseDate": "2017-01-20T19:49:35Z",
    "LastUpdateDate": "2017-01-20T19:49:35Z",
    "OrderStatus": "Pending",
    "FulfillmentChannel": "SellerFulfilled",
    "NumberOfItemsShipped": 0,
    "NumberOfItemsUnshipped": 0,
    "PaymentMethod": "其他",
    "PaymentMethodDetails": [
      "CreditCard",
      "GiftCerificate"
    ],
    "MarketplaceId": "atvpdkikx0der",
    "ShipmentServiceLevelCategory": "标准"
    "OrderType": "StandardOrder",
    "EarliestShipDate": "2017-01-20T19:51:16Z",
    "LatestShipDate": "2017-01-25T19:49:35Z",
    "IsBusinessOrder": false,
    "IsPrime": false,
    "IsGlobalExpressEnabled": false,
    "IsPremiumOrder": false,
    "IsSoldByAB": false,
    "DefaultShipFromLocationAddress": {
      "名称": "MFNIntegrationTestMerchant",
      "AddressLine1": "2201 Westlake Ave",
      "城市": "SEATTLE",
      "StateOrRegion": "WA",
      "PostalCode": "98121-2778",
      "CountryCode": "US",
      "电话": "+1 480-386-0930 ext.73824",
      "地址类型": "商业"
    },
    "FulfillmentInstruction": {
      "FulfillmentSupplySourceId": "sampleSupplySourceId"
    },
    "IsISPU": false,
    "ShippingAddress": {
      "名称": "密歇根地址",
      "AddressLine1": "1 Cross St.",
      "城市": "Canton",
      "StateOrRegion": "MI",
      "PostalCode": "48817",
      "CountryCode": "美国"
    },
    "BuyerInfo": {
      "BuyerEmail": "[email protected]",
      "BuyerName": "John Doe",
      "BuyerTaxInfo": {
        "CompanyLegalName": "一个公司名称"
      },
      "PurchaseOrderNumber": "1234567890123"
    }
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56

2.被委托人应用程序使用响应中的数据来执行其运输和税收功能.

# Tutorial: 获取授权以访问多个货件的货件信息

你可以获得一个RDT,该RDT提供授权以获取销售伙伴的任何货件的货件信息.

先决条件

要完成本教程,您需要

-您想获得的货件信息的货件ID.

# 步骤1.获得一个RDT

调用createRestrictedDataToken操作来获得一个RDT.在你指定的restrictedResources参数的path属性中,使用一个包括以下文字的通用路径{shipmentId}. 定义见Terminology.

  1. Call the createRestrictedDataToken (opens new window) operation, passing the following parameter:

主体参数:

属于 "是"
参数 描述需要
restrictedResources

限制性资源的模型.最大50

类型RestrictedResource

请求示例:

POST https://sellingpartnerapi-na.amazon.com/tokens/2021-03-01/restrictedDataToken
{
  "restrictedResources": [
    {
      "方法": "GET",
      "path": "/mfn/v0/shipments/{shipmentId}"
    }
  ]
}
1
2
3
4
5
6
7
8
9

# Response

一个成功的响应包括以下内容

名称描述
restrictedDataToken

A 限制性数据令牌(RDT). 这是一个短暂的-访问令牌,授权你调用你指定的限制性资源所代表的限制性操作.在后续调用限制性操作时,在x-amz-access-token头里传递RDT值.

类型: string

expiresIn

RDT的寿命,以秒为单位.

类型: 整数

响应的例子:

{
  "restrictedDataToken": "Atz.sprdt|IQEBLjAsAhRmHjNgHpi0U-Dme37rR6CuUpSR",
  "expiresIn": 3600
}
1
2
3
4

2.保存restrictedDataToken值(RDT)在Step 2.在调用getShipment操作时包含RDT.

定义见术语.

# 步骤2.在调用getShipment操作时包含RDT

调用[getShipment](https: //spapi.cyou/zh/references/merchant-fulfillment-api-v0-reference.html#get-mfnv0shipmentsshipmentid)操作的 Merchant Fulfillment API使用您在Step 1. Get an RDT中指定的通用路径,并将{shipmentId}替换为销售伙伴的真实货件ID.GET /mfn/v0/shipments/FBA1234ABC5D. 对所有您想要的货件信息进行重复每次调用时指定适当的货件ID.每次调用必须包括来自步骤1的RDT.获取RDTx-amz-access-token标题下.

**注意.**一个RDT的有效期为一个小时.

# 教程为令牌API生成一个Java SDK

有了这个SDK,你就可以通过已经为你设置好的以下代码来调用Tokens API用亚马逊令牌交换登录(用刷新令牌交换访问令牌)和认证.

要生成一个带有LWA令牌交换和认证的Java SDK

1.安装Java 8或更新版本 (opens new window)Apache Maven 3.6.或更高 (opens new window),以及GNU Wget (opens new window),并使它们在你的$PATH.中可用

  1. 转到https://github.com/amzn/selling-partner-api-models (opens new window).

  2. 克隆版本库,在你的电脑上制作一个本地拷贝,如果你还没有这样做的话.

  3. 打开一个命令提示符窗口,进入一个你想下载Swagger代码生成器的目录.

5.下载最新版本的Swagger代码生成器.

比如说
```
wget https://repo1.maven.org/maven2/io/swagger/swagger-codegen-cli/2.4.13/swagger-codegen-cli-2.4.13.jar -O swagger-codegen-cli.jar
```
**swagger-codegen-cli.jar**下载到当前目录.

**注意:**您也可以通过将浏览器指向这里从maven.org下载<https://repo1.maven.org/maven2/io/swagger/swagger-codegen-cli/2.4.13/swagger-codegen-cli-2.4.13.jar>
  1. swagger-codegen-cli.jar复制到对你有意义的目录结构中. 本例中,我们将其复制到C:\SwaggerToCL.

  2. 导航到你本地版本的selling-partner-api-models\models\tokens-api-model文件夹下的tokens_2021-03-01_json

  3. tokens_2021-03-01.json复制到C:\SwaggerToCL.中

  4. 根据你本地版本的**selling-partner-api-models\clients\sellingpartner-api-aa-java文件夹中的模板生成SDK. 该文件夹包含一个授权和认证库,以及为Swagger代码生成器定制的模板.

    比如说

    java -jar C:\SwaggerToCL\swagger-codegen.jar generate -i C \SwaggerToCL\tokens_2021-03-01.json -l java -t [path to selling-partner-api-models\clients\sellingpartner-api-aa-java folder]resources\swagger-codegen\templates -o C: \SwaggerToCL\Tokens_JavaCL
    
    1

    SDK被复制到C:\SwaggerToCL\Tokens_JavaCL中

10.建立AA库,并将其作为SDK的一个依赖项

1. 导航到你的本地版本的**selling-partner-api-models\clients\sellingpartner-api-aa-java**文件夹并运行mvn package. 这将生成一个名为 "target". 在这个文件夹中,有一个名为**sellingpartnerapi-aa-java-1.0-jar-with-dependencies.jar**的JAR文件(或类似的东西)以及所有需要的依赖项.

2.将JAR文件安装到你的本地Maven仓库中.

    比如说
    ```
    mvn install:install-file -Dfile=[path to JAR file in "target" folder] -DgroupId=com.amazon.sellingpartnerapi -DartifactId=sellingpartnerapi-aa-java -Dversion=1.0 -Dpackaging=jar
    ```
    你可以在**selling-partner-api-models/clients/sellingpartner-api-aa-java**文件夹中的**pom.xml**文件的顶部附近找到实际的groupId、artifactId和版本值.
  1. 在客户端库的pom.xml中添加对AA库的依赖

    比如说

    <依赖关系
    <groupId>com.amazon.sellingpartnerapi</groupId>
    <artifactId>sellingpartnerapi-aa-java</artifactId>
    <版本>1.0</版本>
    </dependency></dependency>
    
    1
    2
    3
    4
    5

12.在生成的SDK文件夹内运行**mvn软件包.

13.下载以下任何文件并使用它们在生成的客户端库的**main/java/sampleCode/**文件夹内构建类.定义见Terminology.

- [RestrictedDataTokenWorkflow.java](https://github.com/amzn/selling-partner-api-models/blob/main/clients/sample-code/RestrictedDataTokenWorkflow.java). 用于获取RDT并使用它来授权自己的应用程序调用一个或多个受限操作.

- [DelegatedRestrictedDataTokenWorkflowForDelegator.java](https://github.com/amzn/selling-partner-api-models/blob/main/clients/sample-code/DelegatedRestrictedDataTokenWorkflowForDelegator.java). 用于获得一个RDT,将调用受限操作的授权委托给一个被委托的应用程序.

- [DelegatedRestrictedDataTokenWorkflowForDelegatee.java](https://github.com/amzn/selling-partner-api-models/blob/main/clients/sample-code/DelegatedRestrictedDataTokenWorkflowForDelegatee.java). 适用于从委托者应用程序接收RDT并使用它来授权调用受限操作的受委托者应用程序.

**注意.**在生成SDK时使用最新版本的**tokens_2021-03-01.json**,以确保你获得最新的功能.

你现在可以开始测试获取RDT和调用限制性操作的工作流程了.用这段代码来指导你构建自己的应用程序.

Last Updated: 2022/10/20 下午11:58:42