Amazon Selling Partner API - spapi.vip

报表API v2021-06-30用例指南

亚马逊SPAPI

# 什么是报告API？

使用报告的销售伙伴API(报告API)，建立从亚马逊获得报告的应用程序，以帮助销售伙伴管理他们的业务.该API为各种用例提供报告，包括：监控库存、跟踪履行的订单、获得税务信息、跟踪退货和卖家业绩、用亚马逊的Fulfillment管理销售业务等等.请参考[报告API参考](https: //spapi.vip/zh/references/reports-api-v2021-06-30-reference.html)以了解关于Reports API操作以及相关数据类型和模式的详细信息. 参考reportType values (opens new window)以了解可用的报表类型.

生成报告的三个主要工作流程是请求报告、安排报告和检索自动生成的报告.

请求报告

你可以通过使用createReport操作按需请求任何可用的报告类型.参考Tutorial请求和检索一个报告的说明.

安排一个报告

您可以使用createReportSchedule操作让亚马逊按时间表自动提交报告请求.参考Tutorial安排和检索报告的说明.

检索自动生成的报告

亚马逊会自动生成一些报告.请参考教程检索自动生成的报告以获得检索那些自动生成的报告的说明.

# Terminology

  • S3 pre-signed URL. 亚马逊S3桶的一个URL，你可以从该桶中下载一个对象，而无需AWS安全凭证或权限.

# Tutorial: 请求和检索一个报告

使用下面的过程来请求一个报告

1.调用createReport (opens new window)操作，指定你所请求的报告类型和市场，以及任何可选参数.

亚马逊接收报告请求.如果操作成功，响应中包括一个reportId值.

2.定期轮询亚马逊SQS队列的REPORT_PROCESSING_FINISHED通知事件，当报告处理为CANCELLED、DONE或FATAL时，该通知事件包括一个reportDocumentId值，如果有报告数据可用.

3.调用getReportDocument (opens new window)操作，传递上一步的reportDocumentId值.

亚马逊返回一个预先签名的报告文档的位置的URL，如果报告文档的内容被压缩，则返回使用的压缩算法.

4.下载报告.

# Prerequisites

要成功完成本教程，需要以下项目

步骤

步骤1.请求一份报告

第2步.确认报告处理完毕

第3步.检索报告

# 步骤1.请求一份报告

通过指定你所要求的报告类型和市场，以及任何可选的参数来要求一份报告.

-调用createReport (opens new window)操作，传递以下参数

请求主体

名称描述要求
reportOptions 传递给报告的附加信息.这因报告类型而异.

类型ReportOptions

 没有
reportType 报告类型.更多信息，见报告类型值.

类型：字符串

 是的
dataStartTime 日期和时间范围的开始，采用ISO 8601日期时间格式，用于选择要报告的数据.默认为现在.该值必须早于或等于当前日期和时间.不是所有的报告类型都使用这个.

类型：字符串(日期-时间)

 没有
dataEndTime 日期和时间范围的终点，采用ISO 8601日期时间格式，用于选择要报告的数据.默认为现在.该值必须在当前日期和时间之前或等于当前日期和时间.不是所有的报告类型都使用这个.

类型：字符串(日期-时间)

 没有
marketplaceIds A list of marketplace identifiers.报告文件的内容将包含所有指定市场的数据，除非报告类型另有说明.

Type: < string > array

 是的

# Request example:

POST https://sellingpartnerapi-na.amazon.com/reports/2021-06-30/reports
{
  "报告类型": "get_merchant_listings_all_data",
  "dataStartTime": "2019-12-10T20:11:24.000Z",
  "marketplaceIds": [
    "a1pa6795ukmfr9",
    "atvpdkikx0der"
  ]
}
1
2
3
4
5
6
7
8
9

响应

一个成功的响应包括以下属性

名称描述
报告编号报告的标识符.该标识符只有在与卖方ID结合时才是唯一的.

类型：字符串

# Response example:

{
  "reportId": "ID323"
}
1
2
3

# 第2步.确认报告处理已经完成

要确认报告处理是否完成，请参阅如何验证报告处理是否完成.

# 步骤3.检索报告

要检索报告，请参阅如何检索报告.

# Tutorial: 安排和检索报告

你可以使用createReportSchedule操作来安排对报告的请求，以便定期提交.使用周期枚举来指定时间段.要确定哪些报告可以被安排，请查看Selling Partner API文档中的报告类型值 (opens new window).

使用下面的程序来请求一份报告

1.调用createReportSchedule (opens new window)操作来创建一个定期提交报告请求的时间表.指定报告类型、marketplaceIds和period值以及任何可选的参数.对于报告类型值，请参考报告类型值 (opens new window).对于period值，请参考period枚举 (opens new window).

注意如果一个具有相同报告类型和市场ID的报告计划表已经存在，它将被取消并被这个计划表取代.否则，将创建一个新的报告计划表.

2.定期轮询Amazon SQS队列中的REPORT_PROCESSING_FINISHED通知事件，使用的时间间隔与你在第一步配置的时间表相似.

如果你收到预定报告的通知，通知事件包含报告信息，包括reportDocumentId值，如果报告数据可用的话.

3.对于每一个reportDocumentId

  1. Call the getReportDocument (opens new window) operation, passing the reportDocumentId value.

    亚马逊会返回一个预-签名的报告文档的位置的URL，如果报告文档的内容被压缩，则返回所使用的压缩算法.

2.下载报告.

# Prerequisites

要成功完成本教程，需要以下项目

步骤

Step 1.为报告请求创建一个时间表

步骤2.定期检索有关预定报告的信息的信息

第3步.检索报告

# 步骤1.为报告请求创建一个时间表

调用createReportSchedule操作来创建一个提交报告请求的时间表，指定reportType、markeplaceIds和period值以及任何可选的参数.参考reportType值 (opens new window)，了解可用报告类型的列表.

主体参数

帐户中的资金将被冻结
名称描述要求
reportType 报告类型.

类型：字符串

 是的
marketplaceIds 报告时间表的市场标识符的列表.

类型: < string > array

 是的
reportOptions 传递给报告的额外信息.这因报告类型而异.

类型ReportOptions

 没有
期间 一组预定义的ISO 8601周期之一，指定报告的创建频率.

Type: enum (Period)

 是的
nextReportCreationTime 日程表将创建下一份报告的日期和时间，ISO 8601日期时间格式.

类型: string (date-time)

# Request example:

POST https://sellingpartnerapi-na.amazon.com/reports/2021-06-30/schedules
{
  "报告类型": "get_xml_browse_tree_data",
  "周期": "P2D",
  "marketplaceIds":["ATVPDKIKX0DER"]
}
1
2
3
4
5
6

响应

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

名称 描述
CreateReportScheduleResponse createReportSchedule操作的有效载荷. CreateReportScheduleResponse

# Response example:

{
  "reportScheduleId": "ID323"
}
1
2
3

# Step 2.定期检索计划报告的信息

定期轮询Amazon SQS队列中的REPORT_PROCESSING_FINISHED通知事件，使用的时间间隔与你在步骤1中配置的时间表相似.以确认报告处理已经完成参考如何验证报告处理是否完成.

# 步骤3.检索报告

要检索报告，请参考如何检索报告.

# Tutorial: 检索自动生成的报告

使用下面的过程来请求自动生成的报告

1.定期轮询亚马逊SQS队列的REPORT_PROCESSING_FINISHED通知事件，该事件在报告处理为CANCELLED、DONE或FATAL时提供信息.通知事件包括一个reportDocumentId值，如果有报告数据可用.

  1. 对于每一个代表你想检索的报告的reportDocumentId

    1. Call the getReportDocument (opens new window) operation, passing the reportDocumentId value.

      亚马逊会返回一个预先签名的URL，表示报告文档的位置，如果报告文档的内容被压缩，则会返回使用的压缩算法.

    2.下载报告.

# Prerequisites

要成功完成本教程，需要以下项目

步骤

步骤1.检索可以下载的报告的信息的信息

第2步.检索报告

# 步骤1.检索可以下载的报告的信息

1.你可以定期轮询Amazon SQS队列，检查是否收到关于Amazon生成的报告的通知.要确认报告处理完成，请参考如何验证报告处理完成.

REPORT_PROCESSING_FINISHED通知事件包含reportDocumentId，可用于下载报告.

2.对于每一个代表你想检索的报告的reportDocumentId，保存reportDocumentId，然后转到步骤2来检索报告.

# Response example:

{
  "报告": [
    {
      "报告类型": "get_v2_settlement_report_data_flat_file",
      "processingEndTime": "2021-08-03T01:02:25+00:00",
      "processingStatus": "DONE",
      "marketplaceIds": [
        "atvpdkikx0der"
      ],
      "reportDocumentId": "DOC-b8b0-4226-b4b9-0ee058ea5760",
      "reportId": "ID222",
      "dataEndTime": "2021-08-03T01:02:25+00:00",
      "createdTime": "2021-08-03T01:02:25+00:00",
      "processingStartTime": "2021-08-03T01:02:25+00:00",
      "dataStartTime": "2021-08-03T01:02:25+00:00"
    }
  ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

# 第2步.检索报告

要检索报告，请参考如何检索报告.

# 如何验证报告的处理已经完成

我们建议你使用Notifications API (opens new window)来订阅REPORT_PROCESSING_FINISHED事件，以便在报告处理状态改变时得到通知.这可以减少你调用getReport (opens new window)或getReports (opens new window)来检查处理状态的次数.

当任何报告的处理状态为DONE、CANCELLED或FATAL时，将发送REPORT_PROCESSING_FINISHED通知事件.

要订阅REPORT_PROCESSING_FINISHED通知类型，请参考Notifications API Use Case Guide (opens new window). 更多信息请参考REPORT_PROCESSING_FINISHED通知事件 (opens new window).

以下处理状态值确认处理已经结束

  • CANCELLED - 报告被取消. 有两种方式可以取消报告1)在报告开始处理前提出取消请求，或者2)在没有数据返回时自动取消.

  • DONE - 报告已经完成处理，并且有一个报告文档的ID.

  • FATAL - 报告由于致命的错误而被放弃，并且可能存在一个reportDocumentId. 如果存在，reportDocumentId所代表的报告可以解释为什么报告处理结束.

# 如何检索一个报告

获取检索报告文件所需的信息，然后下载报告.

步骤

步骤1.获取检索报告所需的信息

第2步.下载报告

# 步骤1.获取检索报告所需的信息

调用getReportDocument操作来获取检索报告文件内容所需的信息.这包括报告文件的预-签名的URL，如果报告文件内容被压缩，还可以选择使用压缩算法.

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

路径参数

名称描述要求
reportDocumentId 报告文档的标识符.

类型：字符串

 是的

# Request example:

GET https://sellingpartnerapi-na.amazon.com/reports/2021-06-30/documents/DOC-b8b0-4226-b4b9-0ee058ea5760
1

响应

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

名称描述
reportDocumentId 报告文件的标识符.该标识符只有在与卖方ID结合时才是唯一的.
url 报告文件的一个预先-签名的URL.这个URL在5分钟后过期.

类型: string

compressionAlgorithm 如果存在，报告文件内容已经用所提供的算法进行了压缩.

类型: 枚举(CompressionAlgorithm)

# Response example:

{
  "reportDocumentId": "DOC-b8b0-4226-b4b9-0ee058ea5760",
  "url": "https://d34o8swod1owfl.cloudfront.net/SampleResult%2BKey%3DSample%2BINITVEC%3D58+fa+bf+a7+08+11+95+0f+c1+a8+c6+e0+d5+6f+ae+c8"
}
1
2
3
4
  1. 保存url和compressionAlgorithm (optional property)以便在步骤2中使用

# 步骤2.下载报告

你必须使用步骤1中返回的信息下载报告.下面的示例代码演示了如何下载一个纯文本的报告文档.你也可以使用示例代码中演示的原则来指导你用其他编程语言构建应用程序，或者用于其他类型的文档(XML,CSV,TSV等.).

1.使用以下内容作为样本代码的输入

  • 上一步的url和可选的compressionAlgorithm值是DownloadExample'类的url'和`compressionAlgorithm'方法的参数.

注意你必须始终保持静态加密.未加密的报告内容决不能存储在磁盘上，即使是暂时的，因为报告可能包含敏感信息.我们提供的示例代码演示了这个原则.

# 示例代码(Java)

// DownloadExample.java
// 本示例适用于报告的销售伙伴API，版本：2021-06-30
// 和销售伙伴 API for Feeds, 版本: 2021-06-30
import java.io.BufferedReader;
import java.io.Closeable;
import java.io.IOException;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.nio.charset.Charset;
import java.util.zip.GZIPInputStream;

import com.squareup.okhttp.MediaType;
import com.squareup.okhttp.OkHttpClient;
import com.squareup.okhttp.Request;
import com.squareup.okhttp.Response;
import com.squareup.okhttp.ResponseBody;

/**
 *下载一个文档的例子.
 */
public class DownloadExample {

  public static void main(String args[]) {
    String url = "<来自getFeedDocument/getReportDocument响应的URL>"
    String compressionAlgorithm = "<来自getFeedDocument/getReportDocument响应的压缩算法>"

    DownloadExample obj = new DownloadExample();
    尝试 {
      obj.download(url, compressionAlgorithm);
    } catch (IOException e) {
      //在这里处理异常.
    } catch (IllegalArgumentException e) { //处理这里的异常.
      //处理这里的异常.
    }
  }

  /**
   *下载并可选择解压从给定的url.中获取的文件
   *
   * @param url 指向文档的url
   * @param compressionAlgorithm 指用于文档的压缩算法
   * @抛出IOException，当有一个错误读取响应时
   * @当字符集丢失时，抛出IllegalArgumentException
      */

    public void download(String url, String compressionAlgorithm) throws IOException, IllegalArgumentException {
    
    OkHttpClient httpclient = new OkHttpClient();
    请求 request = 新的 Request.Builder()
      .url(url)
      .get()
      .build();
    
    响应 = httpclient.newCall(request).execute()
    如果(!Response.isSuccessful()) {
      System.out.println(
        String.format("Call to download content was unsuccessful with response code: %d and message: %s",
          response.code(), response.message()));
      返回
    }
    
    try (ResponseBody responseBody = response.body()) {
      MediaType mediaType = MediaType.parse(response.header("Content-Type"));
      Charset charset = MediaType.charset()
      如果(charset == null) {
        抛出新的IllegalArgumentException(String.format(
          "无法解析来自'%s'的字符集", mediaType.toString())
      }
    
      Closeable closeThis = null;
      试试 {
        InputStream inputStream = responseBody.byteStream();
        closeThis = inputStream;
    
        if ("GZIP".equals(compressionAlgorithm)) {
          inputStream = new GZIPInputStream(inputStream);
          closeThis = inputStream;
        }
    
        // 这个例子假设下载内容在content-type头中有一个charset，e.g.
        // text/plain; charset=UTF-8
        if ("text".equals(mediaType.type()) &amp;&amp; "plain".equals(mediaType.subtype())) {
          InputStreamReader inputStreamReader = new InputStreamReader(inputStream, charset);
          closeThis = inputStreamReader;
    
          BufferedReader reader = new BufferedReader(inputStreamReader);
          closeThis = reader;
    
          字符串行
          do {
            line = reader.readLine();
            //逐行处理.
          } while (line != null);
        } else {
          //在此处理带有二进制数据/其他媒体类型的内容.
        }
      } finally {
        if (closeThis != null) {
          closeThis.close();
        }
      }
    }
  }
}
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
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104

# 最佳实践

# 期待报告的变化

亚马逊会定期向报告添加新的字段和字段值.确保您在应用程序中构建的任何报告解析器能够优雅地处理这些类型的报告更新.

# 不要依赖文档ID结构

不要依赖文档标识符的格式和结构.格式和结构是可以改变的.

Solicitations API v1