Versión API: 2020-09-04

¿Qué es la API de reporte?

A partir del 27 de junio de 2023 , la Selling Partner API para Reports v2020-09-04 ya no estará disponible y todas las llamadas fallarán. Las integraciones que dependen de la API de Reports deben migrar a Reports v2021-06-30 para evitar la interrupción del servicio.

Terminología

• Cipher block chaining . El Cipher block chaining es un algoritmo que utiliza un cifrado de bloques para proporcionar seguridad de la información, como confidencialidad o autenticidad. Este algoritmo utiliza un vector de inicialización y una clave para cifrar los datos.
• URL prefirmada de Amazon S3 . Una URL para un bucket de S3 desde el que puede descargar un objeto sin permisos ni credenciales de seguridad de AWS. En algunos casos, el objeto puede comprimirse, en cuyo caso compressionAlgorithm se devuelve además de la URL. La URL caduca después de 5 minutos.

Tutorial: Solicitar y recuperar un reporte

Estos son los pasos de alto nivel para solicitar un reporte:

1. Llama a operación createReport, especificando el reporte type y los marketplaces que está solicitando, y cualquier parámetro opcional que desee.

   Amazon recibe la solicitud de reporte. Si la operación tiene éxito, la respuesta incluye un reportId.

2. Llame periódicamente la operación getReport, pasando el valor reportId del paso anterior, hasta el valor processingStatus El valor en la respuesta indica que el procesamiento ha terminado. El procesamiento habrá terminado cuando el valor processingStatus es igual CANCELLED, DONE o FATAL. En este punto, la respuesta incluye un reportDocumentId si hay datos de reporte disponibles.

3. Llame a la operación getReportDocument, pasando el valor reportDocumentId del paso anterior.

   Amazon devuelve una URL preestablecida para la ubicación del documento del reporte junto con los detalles de cifrado. En algunos casos, el objeto puede comprimirse, en cuyo caso compressionAlgorithm se devuelve además de la URL. La URL caduca después de 5 minutos.

4. Descargar y descifrar el reporte.

requisitos previos

Para completar este tutorial, necesitará:

• Un reporte type para solicitar. Consulte los valores de reportType para obtener una lista de los reporte types disponibles.
• Autorización del seller para el que está llamando. Consulte la Guía para desarollador de la Selling Partner API para obtener más información.
• Una comprensión del cifrado del lado del cliente mediante el Cipher block chaining (CBC). Para definiciones, consulte Terminología .
• Para usar el código de ejemplo en esta guía, una instalación funcional de Java Development Kit (JDK), incluida la biblioteca javax.crypto.

Pasos

1. Solicitar un reporte
2. Confirme que el procesamiento del reporte se ha completado
3. Recuperar el reporte

Paso 1. Solicitar un reporte

Solicite un reporte especificando el reporte type y los marketplaces que está solicitando, y cualquier parámetro opcional.

• Llama la operación createReport, pasando los siguientes parámetros:

Cuerpo de la solicitud:

Ejemplo de solicitud:

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

Respuesta

Una respuesta exitosa incluye la siguiente propiedad:

Ejemplo de respuesta:

{
  "payload":
  {
    "reportId": "ID323"
  }
}

Paso 2. Confirme que el procesamiento del reporte se ha completado

Después de llamar al createReport Amazon recibe la solicitud y comienza a procesar el reporte. A continuación, debe confirmar que el procesamiento se ha completado antes de continuar.

Llame periódicamente al getReport, pasando el valor reportId del paso anterior, hasta el valor processingStatus El valor en la respuesta indica que el procesamiento ha terminado. El procesamiento habrá terminado cuando el valor processingStatus es igual CANCELLED, DONE o FATAL. En este punto, la respuesta incluye un reportDocumentId si hay datos de reporte disponibles.

Aquí están los valores processingStatus que confirman que el procesamiento ha terminado:

• CANCELLED - El reporte fue cancelado. Hay dos formas de cancelar un reporte: una solicitud de cancelación explícita antes de que el reporte comience a procesarse o una cancelación automática si no hay datos para devolver.
• DONE - El reporte ha completado el procesamiento y un reportDocumentId está disponible.
• FATAL - El reporte se detuvo debido a un error fatal y un reportDocumentId puede estar presente. Si está presente, el reporte representado por el valor reportDocumentId puede explicar por qué finalizó el procesamiento del reporte.

La siguiente processingStatus Los valores indican que el procesamiento no ha finalizado y debe continuar llamando a la operación getReport hasta que la operación devuelva un processingStatus de CANCELLED, DONE o FATAL.

• IN_PROGRESS - El reporte se está procesando.
• IN_QUEUE - El reporte aún no ha comenzado a procesarse. Puede estar esperando otro IN_PROGRESS reporte.

Nota : la operación getReport solo sirve información para solicitudes de reportes programados o bajo demanda que se crearon en los últimos 90 días.

Parámetro de ruta:

Ejemplo de solicitud:

GET https://sellingpartnerapi-na.amazon.com/reports/2020-09-04/reports/ID323

Respuesta

Una respuesta exitosa incluye lo siguiente:

Ejemplo de respuesta

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

Paso 3. Recuperar el reporte

Para recuperar el reporte, consulte Cómo recuperar un reporte .

Tutorial: programar y recuperar reporte

Puede programar solicitudes de reporte para que se envíen periódicamente, utilizando el valor createReportSchedule operación. Utilice la enumeración de período para especificar el período de tiempo. Para identificar qué reporte se pueden programar, revise los valores de reporte type en la documentación de la Selling Partner API.

Estos son los pasos de alto nivel para programar y recuperar reporte:

1. Llama la operación createReportSchedule para crear un cronograma para enviar periódicamente solicitudes de reporte. Especificar reportType, marketplaceIds y valores period y cualquier parámetro opcional. Para valores de reportType, consulte valores de reporte type. Para valores period, véase enumeración de períodos .

   Nota : si ya existe un cronograma de reporte con el mismo reporte type e ID de marketplace, se cancelará y se reemplazará con este. De lo contrario, se creará un nuevo calendario de reporte.

2. Llame periódicamente algetReports operación usando un intervalo que es similar al programa que configuró en el paso anterior.

   Si una llamada a la operación getReports tiene éxito, la respuesta contiene una array de información del reporte, que incluye reportDocumentId valores si los datos del reporte están disponibles.

   Nota : la operación getReports solo sirve información para solicitudes de reportes programados o bajo demanda que se crearon en los últimos 90 días.

3. Para cada reportDocumentId:

   1. Llama la operación getReportDocument, pasando el valor reportDocumentId.

      Amazon devuelve una URL preestablecida para la ubicación del documento del reporte junto con los detalles de cifrado. En algunos casos, el objeto puede comprimirse, en cuyo caso compressionAlgorithm se devuelve además de la URL. La URL caduca después de 5 minutos.

   2. Descargar y descifrar el reporte.

requisitos previos

Para completar este tutorial, necesitará:

• Un reporte type para programar. Consulte los valores de reportType para obtener una lista de los reporte types disponibles.
• Autorización del seller para el que está llamando. Consulte la Guía para desarolladores de la Selling Partner API para obtener más información.
• Una comprensión del cifrado del lado del cliente mediante el Cipher block chaining (CBC). Para definiciones, consulte Terminología .
• Para usar el código de ejemplo en esta guía, una instalación funcional de Java Development Kit (JDK), incluida la biblioteca javax.crypto.

Pasos

1. Crear un cronograma para las solicitudes de reporte
2. Recuperar periódicamente información sobre los reportes programados
3. Recuperar los reporte

Paso 1: Cree un cronograma para las solicitudes de reporte

Llama la operación createReportSchedule para crear un cronograma para enviar solicitudes de reporte, especificando el valor reportType, markeplaceIds, y period valores y cualquier parámetro opcional. Consulte los valores de reportType para obtener una lista de los reporte types disponibles.

• Llama la operación createReportSchedule y pasar los siguientes parámetros:

Parámetro del Body:

Ejemplo de solicitud:

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

Respuesta

Una respuesta exitosa incluye lo siguiente:

Ejemplo de respuesta:

{
  "payload":
  {
    "reportScheduleId": "ID323"
  }
}

Paso 2: recuperar periódicamente información sobre los reportes programados

Llame periódicamente la operación getReports usando un intervalo que es similar al horario que configuró. Querrá intentar programar estas llamadas para que ocurran después de que los reportes programados probablemente se hayan completado.

1. Llama la operación getReports periódicamente para recuperar información sobre los reportes programados, pasando los siguientes parámetros:

Parámetros de query:

Ejemplo de solicitud:

GET https://sellingpartnerapi-na.amazon.com/reports/2020-09-04/reports?reportTypes=GET_XML_BROWSE_TREE_DATA

Respuesta

Una respuesta exitosa incluye lo siguiente:

La array de payload en la respuesta contiene uno objeto Report consulte Reportpara cada reporte procesado y cada objeto de reporte contiene el archivo reportDocumentId.

Nota : se devuelve información sobre los reportes programados y a pedido. Para identificar los reportes programados, busque la presencia de un reportScheduleId en el valor Report objeto en la respuesta. El reportScheduleId indica qué horario envió esta solicitud de reporte.

1. Para cada reportDocumentId, salva el valor reportDocumentId y vaya al paso 3 para recuperar el reporte.

Ejemplo de respuesta:

{
  "nextToken": "VGhpcyB0b2tlbiBpcyBvcGFxdWUgYW5kIGludGVudGlvbmFsbHkgb2JmdXNjYXRlZA==",
  "payload": [
    {
      "reportType": "GET_XML_BROWSE_TREE_DATA",
      "processingEndTime": "2020-09-23T22:52:59+00:00",
      "processingStatus": "DONE",
      "marketplaceIds": ["ATVPDKIKX0DER"],
      "reportDocumentId": "FOO_eae0a7b7-6c33-4191-ad1a-f31ac1ae0ce3",
      "reportId": "ID222",
      "dataEndTime": "2020-09-23T22:52:24+00:00",
      "createdTime": "2020-09-23T22:52:43+00:00",
      "processingStartTime": "2020-09-23T22:52:49+00:00",
      "reportScheduleId": "ID323",
      "dataStartTime": "2020-09-23T22:37:24+00:00"
    }
  ]
}

Paso 3: recuperar el reporte

Para recuperar un reporte, consulte Cómo recuperar un reporte .

Cómo recuperar un reporte

Obtenga su reporte obteniendo primero la información requerida para recuperar un documento de reporte y luego descargando y descifrando el reporte.

Pasos

1. Obtener la información necesaria para recuperar el reporte
2. Descargar y descifrar el reporte

Paso 1. Obtener la información necesaria para recuperar el reporte

Llame a la operación getReportDocument para obtener la información necesaria para recuperar el contenido de un documento de reporte. Esto incluye una URL preestablecida para el documento del reporte, así como la información necesaria para descifrar el contenido del documento. En algunos casos, el objeto puede comprimirse, en cuyo caso compressionAlgorithm se devuelve además de la URL. La URL caduca después de 5 minutos.

1. Llama la operación getReportDocument, pasando el siguiente parámetro:

Parámetro de ruta:

Ejemplo de solicitud:

GET https://sellingpartnerapi-na.amazon.com/reports/2020-09-04/documents/DOC-b8b0-4226-b4b9-0ee058ea5760

Respuesta

Una respuesta exitosa incluye los siguientes elementos:

Ejemplo de respuesta:

{
  "payload": {
    "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",
    "encryptionDetails": {
      "standard": "AES",
      "initializationVector": "58 fa bf a7 08 11 95 0f c1 a8 c6 e0 d5 6f ae c8",
      "key": "Sample"
    }
  }
}

2. Salva el valor key, initializationVector, url, y compressionAlgorithm (propiedad opcional) para usar en el Paso 2.

Paso 2. Descargar y descifrar el reporte

Deberá descargar y descifrar el reporte utilizando la información devuelta en el paso anterior. El siguiente código de ejemplo junto con las clases proporcionadas en el Selling Partner API Documents Helper pueden ayudar. También puede usar los principios demostrados en el código de ejemplo y en el código del asistente de documentos SP-API para guiarlo en la creación de aplicaciones en otros lenguajes de programación.

1. Utilice lo siguiente como entradas para el código de ejemplo:

   • Los valores de key, initializationVector, urly compressionAlgorithm opcional del paso anterior son argumentos key, initializationVector, url, y compressionAlgorithm opcionales en el método downloadAndDecrypt de la clase DownloadExample.

Nota : es responsabilidad del desarollador mantener siempre el cifrado en reposo. El contenido de reporte sin cifrar nunca debe almacenarse en el disco, ni siquiera temporalmente, porque los reporte pueden contener información confidencial. El código de ejemplo que proporcionamos demuestra este principio.

Código de ejemplo (Java)

// DownloadExample.java
import java.io.BufferedReader;
import java.io.IOException;

import com.amazon.spapi.documents.CompressionAlgorithm;
import com.amazon.spapi.documents.DownloadBundle;
import com.amazon.spapi.documents.DownloadHelper;
import com.amazon.spapi.documents.DownloadSpecification;
import com.amazon.spapi.documents.exception.CryptoException;
import com.amazon.spapi.documents.exception.HttpResponseException;
import com.amazon.spapi.documents.exception.MissingCharsetException;
import com.amazon.spapi.documents.impl.AESCryptoStreamFactory;

public class DownloadExample {
  final DownloadHelper downloadHelper = new DownloadHelper.Builder().build();

  // The key, initializationVector, url, and compressionAlgorithm are obtained from the response to
  // the getReportDocument operation.
  public void downloadAndDecrypt(String key, String initializationVector, String url, String compressionAlgorithm) {
    AESCryptoStreamFactory aesCryptoStreamFactory =
      new AESCryptoStreamFactory.Builder(key, initializationVector).build();

    DownloadSpecification downloadSpec = new DownloadSpecification.Builder(aesCryptoStreamFactory, url)
      .withCompressionAlgorithm(CompressionAlgorithm.fromEquivalent(compressionAlgorithm))
      .build();

    try (DownloadBundle downloadBundle = downloadHelper.download(downloadSpec)) {
      // This example assumes that the downloaded file has a charset in the content type, e.g.
      // text/plain; charset=UTF-8
      try (BufferedReader reader = downloadBundle.newBufferedReader()) {
        String line;
        do {
          line = reader.readLine();
          // Process the decrypted line.
        } while (line != null);
      }
    }
    catch (CryptoException | HttpResponseException | IOException | MissingCharsetException e) {
        // Handle exception here.
    }
  }
}

Mejores prácticas

Esperar cambios en los reporte

Amazon agrega periódicamente nuevos campos y valores de campo a los reporte. Asegúrese de que cualquier analizador de reporte que incorpore a sus aplicaciones pueda manejar correctamente este tipo de actualizaciones de reporte.

No confíe en la estructura de identificación del documento

No debe confiar en el formato y la estructura de los identificadores de documentos. El formato y la estructura están sujetos a cambios.