Guia de caso de uso da API de relatórios

Como obter relatórios da Amazon para ajudar os parceiros de vendas a gerenciar seus negócios.

Versão da API: 30-06-2021

O que é a API de relatórios?

Use a Selling Partner API for Reports (API de relatórios) para criar aplicativos que obtêm relatórios da Amazon para ajudar os parceiros de vendas a gerenciar seus negócios. A API fornece relatórios para uma variedade de casos de uso, incluindo: monitoramento de estoque, rastreamento de pedidos para atendimento, obtenção de informações fiscais, rastreamento de devoluções e desempenho do vendedor, gerenciamento de um negócio de vendas com o atendimento da Amazon e muito mais. Consulte a Referência da API de relatórios para obter detalhes sobre as operações da API de relatórios e os tipos de dados e esquemas associados. Consulte os valores de reportType para os tipos de relatório disponíveis.

Os três principais fluxos de trabalho para gerar relatórios são solicitar um relatório, agendar um relatório e recuperar relatórios gerados automaticamente.

Solicitando um relatório

Você pode solicitar qualquer tipo de relatório disponível sob demanda usando a operação createReport. Consulte Tutorial: Solicitar e recuperar um relatório para obter instruções.

Agendando um relatório

Você pode fazer com que a Amazon envie solicitações de relatório automaticamente em uma programação usando a operação createReportSchedule. Consulte Tutorial: Agendar e recuperar relatórios para obter instruções.

Recuperando relatórios gerados automaticamente

A Amazon gera alguns relatórios automaticamente. Consulte Tutorial: Recuperar relatórios gerados automaticamente para obter instruções sobre como recuperar esses relatórios gerados automaticamente.

Terminologia

• URL pré-assinado do S3. Um URL para um bucket do Amazon S3 do qual você pode fazer download de um objeto sem credenciais ou permissões de segurança da AWS.

Tutorial: Solicitar e recuperar um relatório

Use o seguinte processo para solicitar um relatório:

1. Chame a operação createReport, especificando o tipo de relatório e os mercados que você está solicitando e quaisquer parâmetros opcionais.
   A Amazon recebe a solicitação de relatório. Se a operação for bem-sucedida, a resposta incluirá um valor reportId.

2. Pesquise periodicamente a fila do Amazon SQS para o evento de notificação REPORT_PROCESSING_FINISHED, que fornece informações quando o processamento do relatório é CANCELLED, DONE ou FATAL. O evento de notificação inclui um valor reportDocumentId se houver dados de relatório disponíveis.

3. Chame a operação getReportDocument, passando o valor reportDocumentId da etapa anterior.
   A Amazon retorna um URL pré-assinado para o local do documento de relatório e o algoritmo de compactação usado se o conteúdo do documento de relatório tiver sido compactado.

• Baixe o relatório.

Pré-requisitos

Os seguintes itens são necessários para concluir com êxito este tutorial:

• O tipo de relatório que você solicitará. Consulte os valores de reportType para obter uma lista dos tipos de relatório disponíveis.

• Autorização do parceiro de vendas para quem você está fazendo chamadas. Consulte o Guia do desenvolvedor da API do parceiro de vendas para obter mais informações.

• Uma instalação funcional do Java Development Kit (JDK) para executar o código de amostra.

Passos

• Solicite um relatório
• Confirme se o processamento do relatório foi concluído
• Recuperar o relatório

Etapa 1. Solicite um relatório

Solicite um relatório especificando o tipo de relatório e os mercados que você está solicitando e quaisquer parâmetros opcionais.

• Chame a operação createReport, passando os seguintes parâmetros:

Request body:

Nome	Descrição	Schema
reportOptions	Informações adicionais passadas aos relatórios. Isso varia de acordo com o tipo de relatório.	string
reportType Obrigatório	O tipo de relatório. Para obter mais informações, consulte valores reportType.	string
dataStartTime	O início de um intervalo de data e hora, no formato de data e hora ISO 8601, usado para selecionar os dados a serem relatados. O padrão é agora. O valor deve ser anterior ou igual à data e hora atuais. Nem todos os tipos de relatório fazem uso disso.	string (date-time)
dataEndTime	O fim de um intervalo de data e hora, no formato de data e hora ISO 8601, usado para selecionar os dados a serem relatados. O padrão é agora. O valor deve ser anterior ou igual à data e hora atuais. Nem todos os tipos de relatório fazem uso disso.	string (date-time)
marketplaceIds Obrigatório	Uma lista de identificadores de mercado. O conteúdo do documento de relatório conterá dados para todos os mercados especificados, a menos que o tipo de relatório indique o contrário.	< string > array

Exemplo de solicitação:

POST

POST https://sellingpartnerapi-na.amazon.com/reports/2021-06-30/reports
{
  "reportType": "GET_MERCHANT_LISTINGS_ALL_DATA",
  "dataStartTime": "2019-12-10T20:11:24.000Z",
  "marketplaceIds": [
    "A1PA6795UKMFR9",
    "ATVPDKIKX0DER"
  ]
}

Resposta

Uma resposta bem-sucedida inclui a seguinte propriedade:

Nome	Descrição	Schema
reportId	O identificador do relatório. Esse identificador é exclusivo apenas em combinação com um ID de vendedor.	string

Exemplo de resposta:

JSON

{
  "reportId": "ID323"
}

Etapa 2. Confirme se o processamento do relatório foi concluído

Para confirmar se o processamento do relatório foi concluído, consulte Como verificar se o processamento do relatório foi concluído.

Etapa 3. Recupere o relatório

Para recuperar o relatório, consulte Como recuperar um relatório.

Tutorial: Agendar e recuperar relatórios

Você pode agendar solicitações de relatórios para que sejam enviadas periodicamente, usando a operação createReportSchedule. Use a enumeração de período para especificar o período de tempo. Para identificar quais relatórios podem ser programados, revise os valores de tipo de relatório na documentação da API do parceiro de vendas.

Use o seguinte processo para solicitar um relatório:

1. Chame a operação createReportSchedule para criar um agendamento para enviar periodicamente solicitações de relatório. Especifique reportType, marketplaceIds e period valores de período e quaisquer parâmetros opcionais. Para valores reportType, consulte valores reportType. Para valores de período, consulte a enumeração de período.
   Observação: se já existir uma programação de relatório com o mesmo tipo de relatório e IDs de mercado, ela será cancelada e substituída por essa programação. Caso contrário, uma nova programação de relatório é criada.

2. Pesquise periodicamente a fila do Amazon SQS para o evento de notificação REPORT_PROCESSING_FINISHED, que fornece informações quando o processamento do relatório é CANCELLED, DONE ou FATAL. O evento de notificação inclui um valor reportDocumentId se houver dados de relatório disponíveis.

3. Para cada reportDocumentId:

• Chame a operação getReportDocument, passando o valor reportDocumentId.
  A Amazon retorna um URL pré-assinado para o local do documento de relatório e o algoritmo de compactação usado se o conteúdo do documento de relatório tiver sido compactado.

• Baixe o relatório.

Pré-requisitos

Os seguintes itens são necessários para concluir com êxito este tutorial:

• Um tipo de relatório para agendar. Consulte os valores de reportType para obter uma lista dos tipos de relatório disponíveis.

• Autorização do parceiro de vendas para quem você está fazendo chamadas. Consulte o Guia do desenvolvedor da API do parceiro de vendas para obter mais informações.

• Uma instalação funcional do Java Development Kit (JDK) para executar o código de amostra.

Passos

• Criar uma programação para solicitações de relatórios
• Recupere periodicamente informações sobre os relatórios programados
• Recuperar o relatório

Etapa 1. Criar uma programação para solicitações de relatórios

Chame a operação createReportSchedule para criar um agendamento para enviar solicitações de relatório, especificando os valores reportType, markeplaceIds e period período e quaisquer parâmetros opcionais. Consulte os valores de reportType para obter uma lista dos tipos de relatório disponíveis.

• Chame a operação createReportSchedule e passe os seguintes parâmetros:

Body parameter:

Nome	Descrição	Schema
reportType	O tipo de relatório.	string
marketplaceIds	Uma lista de identificadores de mercado para a programação de relatórios.	< string > array
reportOptions	Informações adicionais passadas aos relatórios. Isso varia de acordo com o tipo de relatório.	ReportOptions
period	Um de um conjunto de períodos ISO 8601 predefinidos que especifica com que frequência um relatório deve ser criado.	enum (Period)
nextReportCreationTime	A data e hora em que o agendamento criará seu próximo relatório, no formato de data e hora ISO 8601.	string (date-time)

Exemplo de solicitação:

POST

POST https://sellingpartnerapi-na.amazon.com/reports/2021-06-30/schedules
{
  "reportType": "GET_XML_BROWSE_TREE_DATA",
  "period": "P2D",
  "marketplaceIds":["ATVPDKIKX0DER"]
}

Resposta

Uma resposta bem-sucedida inclui o seguinte:

Nome	Descrição	Schema
CreateReportScheduleResponse	A carga útil para a operação createReportSchedule.	CreateReportScheduleResponse

Exemplo de resposta:

JSON

{
  "reportScheduleId": "ID323"
}

Etapa 2. Recupere periodicamente informações sobre os relatórios programados

Pesquise periodicamente a fila do Amazon SQS para o evento de notificação REPORT_PROCESSING_FINISHED usando um intervalo semelhante ao agendamento que você configurou na etapa 1. Para confirmar se o processamento do relatório foi concluído, consulte Como verificar se o processamento do relatório foi concluído.

Etapa 3. Recupere o relatório

Para recuperar um relatório, consulte Como recuperar um relatório.

Tutorial: Recuperar relatórios gerados automaticamente

Use o seguinte processo para solicitar um relatório gerado automaticamente:

1. Pesquise periodicamente a fila do Amazon SQS para o evento de notificação REPORT_PROCESSING_FINISHED que fornece informações quando o processamento do relatório é CANCELLED, DONE ou FATAL. O evento de notificação inclui um valor reportDocumentId se houver dados de relatório disponíveis.

2. Para cada reportDocumentId que representa um relatório que você deseja recuperar:

• Chame a operação getReportDocument, passando o valor reportDocumentId.
  A Amazon retorna um URL pré-assinado para o local do documento de relatório e o algoritmo de compactação usado se o conteúdo do documento de relatório tiver sido compactado.

• Baixe o relatório.

Pré-requisitos

Os itens a seguir são necessários para concluir com êxito este tutorial:

• Um ou mais tipos de relatório para download depois que os dados do relatório estiverem disponíveis. Consulte os valores de reportType para obter uma lista de tipos de relatório.

• Autorização do parceiro de vendas para quem você está fazendo chamadas. Consulte o Guia do desenvolvedor da API do parceiro de vendas para obter mais informações.

• Uma instalação funcional do Java Development Kit (JDK) para executar o código de amostra.

Passos

• Recuperar informações sobre relatórios que podem ser baixados
• Recuperar o relatório

Etapa 1. Recuperar informações sobre relatórios que podem ser baixados

1. Você pode pesquisar periodicamente a fila do Amazon SQS para verificar se recebeu uma notificação sobre os relatórios gerados pela Amazon. Para confirmar que o processamento do relatório foi concluído, consulte Como verificar se o processamento do relatório foi concluído.

O evento de notificação REPORT_PROCESSING_FINISHED contém o reportDocumentId, que pode ser usado para baixar o relatório.

2. Para cada reportDocumentId que representa um relatório que você deseja recuperar, salve o reportDocumentId e vá para a Etapa 2 para recuperar o relatório.

Exemplo de resposta:

JSON

{
  "reports": [
    {
      "reportType": "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"
    }
  ]
}

Etapa 2. Recupere o relatório

Para recuperar um relatório, consulte Como recuperar um relatório.

Como verificar se o processamento do relatório foi concluído

Depois de chamar a operação createReport, a Amazon recebe a solicitação e começa a processar o relatório. Você deve então confirmar que o processamento foi concluído antes de continuar.

Chame periodicamente a operação getReport, passando o valor reportId da etapa anterior, até que o valor processingStatus na resposta indique que o processamento foi finalizado. O processamento será encerrado quando o processingStatus for igual a CANCELLED, DONE ou FATAL. Neste ponto, a resposta inclui um valor reportDocumentId se houver dados de relatório disponíveis.

Aqui estão os valores de processingStatus que confirmam que o processamento terminou:

• CANCELADO - O relatório foi cancelado. Há duas maneiras de cancelar um relatório: uma solicitação de cancelamento explícita antes do início do processamento do relatório ou um cancelamento automático se não houver dados a serem retornados.

• CONCLUÍDO - O relatório concluiu o processamento e um reportDocumentId está disponível.

• FATAL - O relatório foi interrompido devido a um erro fatal e um reportDocumentId pode estar presente. Se presente, o relatório representado pelo reportDocumentId pode explicar por que o processamento do relatório foi encerrado.

Os seguintes valores de processingStatus indicam que o processamento não foi finalizado e você deve continuar a chamar a operação getReport até que a operação retorne um processingStatus de CANCELLED, DONE ou FATAL.

• IN_PROGRESS - O relatório está sendo processado.

• IN_QUEUE - O relatório ainda não iniciou o processamento. Ele pode estar aguardando outro relatório IN_PROGRESS.

Observação: a operação getReport fornece informações apenas para solicitações de relatório sob demanda ou agendadas que foram criadas nos últimos 90 dias.

Path parameter:

Nome	Descrição	Schema
reportId Obrigatório	O identificador do relatório. Esse identificador é exclusivo apenas em combinação com um ID de vendedor.	string

Exemplo de solicitação:

GET

GET https://sellingpartnerapi-na.amazon.com/reports/2021-06-30/reports/ID323

Resposta

Uma resposta bem-sucedida inclui o seguinte:

Nome	Descrição	Schema
payload	A carga útil para a operação getReport.	report

Exemplo de resposta

JSON

{
  "payload": {
    "reportId": "ID323",
    "reportType": "GET_MERCHANT_LISTINGS_ALL_DATA",
    "dataStartTime": "2019-12-11T13:47:20.677Z",
    "dataEndTime": "2019-12-12T13:47:20.677Z",
    "createdTime": "2019-12-10T13:47:20.677Z",
    "processingStatus": "DONE",
    "processingStartTime": "2019-12-10T13:47:20.677Z",
    "processingEndTime": "2019-12-12T13:47:20.677Z",
    "reportDocumentId": "DOC-b8b0-4226-b4b9-0ee058ea5760"
  }
}

Como recuperar um relatório

Obtenha as informações necessárias para recuperar um documento de relatório e faça o download do relatório.

Passos

1. Obtenha as informações necessárias para recuperar o relatório

2. Baixe o relatório

Etapa 1. Obtenha as informações necessárias para recuperar o relatório

Chame a operação getReportDocument para obter as informações necessárias para recuperar o conteúdo de um documento de relatório. Isso inclui um URL pré-assinado para o documento de relatório e, opcionalmente, o algoritmo de compactação usado se o conteúdo do documento de relatório tiver sido compactado.

1. Chame a operação getReportDocument, passando o seguinte parâmetro:

Path parameter:

Nome	Descrição	Schema
reportDocumentId	O identificador do documento de relatório.	string

Exemplo de solicitação:

GET

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

Resposta

Uma resposta bem-sucedida inclui o seguinte:

Nome	Descrição	Schema
reportDocumentId	O identificador do documento de relatório. Esse identificador é exclusivo apenas em combinação com um ID de vendedor.	string
url	Um URL pré-assinado para o documento de relatório. Este URL expira após 5 minutos.	string
compressionAlgorithm	Se presente, o conteúdo do documento de relatório foi compactado com o algoritmo fornecido.	enum (CompressionAlgorithm)

Exemplo de resposta

JSON

{
  "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"
}

2. Salve o url e o compressionAlgorithm (propriedade opcional) para uso na Etapa 2.

Etapa 2. Baixe o relatório

Você deve baixar o relatório usando as informações retornadas na Etapa 1. O código de exemplo a seguir demonstra como baixar um documento de relatório de texto simples. Você também pode usar os princípios demonstrados no código de exemplo para orientá-lo na criação de aplicativos em outras linguagens de programação ou para outros tipos de documentos (XML, CSV, TSV etc.).

1. Use o seguinte como entradas para o código de amostra:

• Os valores url e opcional compressionAlgorithm da etapa anterior são argumentos para os parâmetros url e compressionAlgorithm do método de download da classe DownloadExample.

Observação: você deve sempre manter a criptografia em repouso. O conteúdo de relatório não criptografado nunca deve ser armazenado em disco, mesmo que temporariamente, porque os relatórios podem conter informações confidenciais. O código de exemplo que fornecemos demonstra esse princípio.

Código de exemplo (Java)

Java

// DownloadExample.java
// This example is for use with the Selling Partner API for Reports, Version: 2021-06-30
// and the Selling Partner API for Feeds, Version: 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;

/**
 * Example that downloads a document.
 */
public class DownloadExample {

  public static void main(String args[]) {
    String url = "<URL from the getFeedDocument/getReportDocument response>";
    String compressionAlgorithm = "<compressionAlgorithm from the getFeedDocument/getReportDocument response>";

    DownloadExample obj = new DownloadExample();
    try {
      obj.download(url, compressionAlgorithm);
    } catch (IOException e) {
      //Handle exception here.
    } catch (IllegalArgumentException e) {
      //Handle exception here.
    }
  }

  /**
   * Download and optionally decompress the document retrieved from the given url.
   *
   * @param url                  the url pointing to a document
   * @param compressionAlgorithm the compressionAlgorithm used for the document
   * @throws IOException              when there is an error reading the response
   * @throws IllegalArgumentException when the charset is missing
   */
  public void download(String url, String compressionAlgorithm) throws IOException, IllegalArgumentException {
    OkHttpClient httpclient = new OkHttpClient();
    Request request = new Request.Builder()
      .url(url)
      .get()
      .build();

    Response response = httpclient.newCall(request).execute();
    if (!response.isSuccessful()) {
      System.out.println(
        String.format("Call to download content was unsuccessful with response code: %d and message: %s",
          response.code(), response.message()));
      return;
    }

    try (ResponseBody responseBody = response.body()) {
      MediaType mediaType = MediaType.parse(response.header("Content-Type"));
      Charset charset = mediaType.charset();
      if (charset == null) {
        throw new IllegalArgumentException(String.format(
          "Could not parse character set from '%s'", mediaType.toString()));
      }

      Closeable closeThis = null;
      try {
        InputStream inputStream = responseBody.byteStream();
        closeThis = inputStream;

        if ("GZIP".equals(compressionAlgorithm)) {
          inputStream = new GZIPInputStream(inputStream);
          closeThis = inputStream;
        }

        // This example assumes that the download content has a charset in the content-type header, e.g.
        // text/plain; charset=UTF-8
        if ("text".equals(mediaType.type()) && "plain".equals(mediaType.subtype())) {
          InputStreamReader inputStreamReader = new InputStreamReader(inputStream, charset);
          closeThis = inputStreamReader;

          BufferedReader reader = new BufferedReader(inputStreamReader);
          closeThis = reader;

          String line;
          do {
            line = reader.readLine();
            // Process line by line.
          } while (line != null);
        } else {
          //Handle content with binary data/other media types here.
        }
      } finally {
        if (closeThis != null) {
          closeThis.close();
        }
      }
    }
  }
}

Melhores Práticas

Espere mudanças nos relatórios

A Amazon adiciona periodicamente novos campos e valores de campo aos relatórios. Certifique-se de que todos os analisadores de relatório que você criar em seus aplicativos possam lidar normalmente com esses tipos de atualizações de relatório.

Não confie na estrutura de ID do documento

Não confie no formato e na estrutura dos identificadores de documentos. O formato e a estrutura estão sujeitos a alterações.