Guía de casos de uso de la Feeds API v2020-09-04

Versión API: 2020-09-04

¿Qué es la API de feeds?

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

flujo de trabajo para enviar un feed

Estos son los pasos de alto nivel para enviar un feed:

1. Llama a operación createFeedDocument , especificando el tipo de contenido para el feed que está enviando.

   Amazon devuelve un valor feedDocumentId y una URL para cargar el contenido del feed.

2. Cifre y cargue el contenido de su documento de feed a la URL del paso anterior.

3. Llama a operación createFeed . Utilizar el parámetro inputFeedDocumentId para pasar en el valor feedDocumentId del paso 1. Especifique los marketplaces a los que desea que se aplique el feed y cualquier opción de feed relevante.

   Amazon devuelve un valor feedId .

4. Llame periódicamente a la operación getFeed , especificando el valor feedId del paso 3, hasta que la feed pase a uno de los siguientes estados de terminal: CANCELLED , DONE , o FATAL . Cuando la feed pase al estado, continúe con el Paso 5

   Amazon devuelve el valor resultFeedDocumentId cuando el feed pasa al estado DONE .

5. Llama a operación getFeedDocument . Utilizar el parámetro feedDocumentId para pasar en el valor resultFeedDocumentId del paso anterior.

   Amazon devuelve el valor feedDocumentId , una URL para descargar el reporte de procesamiento de feeds y el compressionAlgorithm.

6. Descargue y descifre el reporte de procesamiento de feeds.

7. Consulte el reporte de procesamiento de feeds para detectar errores generados durante el procesamiento de feeds. Si hay errores, corríjalos y envíe el feed corregido, comenzando en el paso 1. Si no hay errores, el envío de su feed fue exitoso.

Para obtener más detalles sobre cómo enviar un feed, consulte Tutorial: Enviar un feed .

Terminología

• Cipher block chaining. 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.
• Amazon S3 presigned URL : una URL para un bucket de S3 desde el que puede descargar un objeto sin credenciales ni permisos de seguridad de AWS. En algunos casos, el objeto puede comprimirse, en cuyo caso se devuelve compressionAlgorithm además de la URL. La URL caduca después de 5 minutos.

Tutorial: enviar un feed

Este tutorial le muestra cómo enviar un feed, verificar el estado del procesamiento del feed y verificar que el envío del feed se realizó correctamente. El tutorial contiene ejemplos de código Java que pueden ayudarlo con tareas como cifrar y cargar una feed y descargar y descifrar un reporte de procesamiento de feed. Puede usar los principios demostrados en estos ejemplos de código para guiarlo en la realización de estas tareas utilizando otros lenguajes de programación.

requisitos previos

Para completar este tutorial, necesitará:

1. Un feed para enviar. Consulte Valores de tipo de feed para obtener una lista de los tipos de feed disponibles.
2. Autorización del seller para el que está llamando. Consulte Guía para desarrolador de la Selling Partner API para obtener más información.
3. Una instalación de Java Development Kit (JDK) en funcionamiento, incluida la biblioteca javax.crypto.
4. El Selling Partner API Documents Helper.
5. Una comprensión del cifrado del lado del cliente mediante el Cipher block chaining (CBC). Para definiciones, consulte Terminología .

Paso 1. Crear un documento de feed

Llama a operación createFeedDocument para crear un documento de feed.

1. Llama a operación createFeedDocument , pasando el siguiente parámetro:

Parámetro del Body:

Ejemplo de solicitud

POST https://sellingpartnerapi-na.amazon.com/feeds/2020-09-04/documents
{
  "contentType":"text/tab-separated-values; charset=UTF-8"
}

Respuesta

Una respuesta exitosa incluye lo siguiente:

Ejemplo de respuesta

{
  "payload":
  {
    "feedDocumentId":"amzn1.tortuga.3.920614b0-fc4c-4393-b0d9-fff175300000.T29XK4YL08B2VM",
    "url":"https://tortuga-prod-na.s3.amazonaws.com/%2FNinetyDays/amzn1.tortuga.3.920614b0-fc4c-4393-b0d9-fff175300000.T29XK4YL08B2VM?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20200919T035824Z&X-Amz-SignedHeaders=<headers>&X-Amz-Expires=300&X-Amz-Credential=<credential>&X-Amz-Signature=<signature>",
    "encryptionDetails":
    {
      "standard":"AES",
      "initializationVector":"kF3bZt0FSv6JQEimfEJD8g==",
      "key":"5EZo/P06OGF0UAy8QuOnMIaQbkAvYBru6EGsFvK8wJ2="
    }
  }

2. Guarde los siguientes valores:

   • initializationVector, Key y url Use este valor en el Paso 2. Cifre y cargue los datos del feed .
   • feedDocumentId . Utilice este valor en el Paso 3. Crea un feed . Este El valor feedDocumentId caduca después de dos días. Si pasa en un caducado valor feedDocumentId para el operación createFeed , la llamada fallará.

Paso 2. Cifre y cargue los datos del feed

Puede cifrar y cargar datos de feed utilizando la información devuelta en el paso anterior. El siguiente código de muestra, junto con las clases proporcionadas en el Selling Partner API (SP-API) Documents Helper, pueden ayudar. También puede usar los principios demostrados en el código de muestra y en el asistente de documentos SP-API para guiarlo en la creación de aplicaciones en otros lenguajes de programación.

El código de ejemplo tiene métodos para crear un flujo de entrada a partir de una string y crear un flujo de entrada canalizado.

Para crear un flujo de entrada a partir de una string

• Utilice lo siguiente como entrada para el código de muestra:
  • Los datos de su feed se ingresan en el Clase ByteArrayInputStream .
  • El key , initializationVector y Los valores url del paso anterior son argumentos para el key , initializationVector y parámetros de url del encryptAndUpload_fromString del método UploadExample clase de ejemplo.

Para crear un flujo de entrada canalizado

• Utilice lo siguiente como entrada para el código de muestra:
  • Los datos de su feed se ingresan en el PipedInputStream a través de su conexión con el PipedOutputStream .
  • El key , initializationVector y Los valores url del paso anterior son argumentos para el key , initializationVector y parámetros de url del método encryptAndUpload_fromPipedInputStream del UploadExample clase de ejemplo.

Cifrar y cargar código de muestra (Java)

import java.io.ByteArrayInputStream;
import java.io.IOException;
import java.io.InputStream;
import java.io.PipedInputStream;
import java.io.PipedOutputStream;
import java.nio.charset.StandardCharsets;

import com.amazon.spapi.documents.UploadHelper;
import com.amazon.spapi.documents.UploadSpecification;
import com.amazon.spapi.documents.exception.CryptoException;
import com.amazon.spapi.documents.exception.HttpResponseException;
import com.amazon.spapi.documents.impl.AESCryptoStreamFactory;

/* We want to maintain encryption at rest, so do not write unencrypted data to disk.  This is bad:
InputStream source = new FileInputStream(new File("/path/to/myFeed.xml"));

Instead, if your data can fit in memory, you can create an InputStream from a String (see encryptAndUpload_fromString()).
Otherwise, you can pipe data into an InputStream using Piped streams (see encryptAndUpload_fromPipedInputStream()).
 */
public class UploadExample {
  private final UploadHelper uploadHelper = new UploadHelper.Builder().build();

  // key, initializationVector, and url are returned by the createFeedDocument operation.
  public void encryptAndUpload_fromString(String key, String initializationVector, String url) {
    AESCryptoStreamFactory aesCryptoStreamFactory =
      new AESCryptoStreamFactory.Builder(key, initializationVector)
      .build();

    // This contentType must be the same value that was provided to createFeedDocument.
    String contentType = String.format("text/plain; charset=%s", StandardCharsets.UTF_8);

    // The character set must be the same one that is specified in contentType.
    try
      (InputStream source = new ByteArrayInputStream("my feed data".getBytes(StandardCharsets.UTF_8))) {
        UploadSpecification uploadSpec =
          new UploadSpecification.Builder(contentType, aesCryptoStreamFactory, source, url)
          .build();

        uploadHelper.upload(uploadSpec);
      }
    catch (CryptoException | HttpResponseException | IOException e) {
      // Handle exception.
    }
  }

  // key, initializationVector, and url are returned from createFeedDocument.
  public void encryptAndUpload_fromPipedInputStream(String key, String initializationVector, String url) {
    AESCryptoStreamFactory aesCryptoStreamFactory =
      new AESCryptoStreamFactory.Builder(key, initializationVector)
      .build();

    // This contentType must be the same value that was provided to createFeedDocument.
    String contentType = String.format("text/plain; charset=%s", StandardCharsets.UTF_8);

    try
      (PipedInputStream source = new PipedInputStream()) {
        new Thread(
          new Runnable() {
          public void run() {
            try
              (PipedOutputStream feedContents = new PipedOutputStream(source)) {
                // The character set must be the same one that is specified in contentType.
                feedContents.write("my feed data\n".getBytes(StandardCharsets.UTF_8));
                feedContents.write("more feed data".getBytes(StandardCharsets.UTF_8));
              }
            catch (IOException e) {
              // Handle exception.
            }
          }
        }).start();

        UploadSpecification uploadSpec =
          new UploadSpecification.Builder(contentType, aesCryptoStreamFactory, source, url)
          .build();

        uploadHelper.upload(uploadSpec);
      }
    catch (CryptoException | HttpResponseException | IOException e) {
      // Handle exception.
    }
  }
}

Paso 3. crear un feed

Llama a operación createFeed para especificar el identificador del documento de feed, el tipo de feed, los marketplaces a los que desea que se aplique la feed y cualquier parámetro opcional que desee.

1. Llama a operación createFeed , pasando los siguientes parámetros:

Parámetros del Body:

Ejemplo de solicitud

POST https://sellingpartnerapi-na.amazon.com/feeds/2020-09-04/feeds
{
  "feedType":"POST_PRODUCT_DATA",
  "marketplaceIds":[
    "ATVPDKIKX0DER",
    "A2EUQ1WTGCTBG2"
  ],
  "inputFeedDocumentId":"amzn1.tortuga.3.920614b0-fc4c-4393-b0d9-fff175300000.T29XK4YL08B2VM"
}

Ejemplo de solicitud de un pedido Easy Ship

POST https://sellingpartnerapi-na.amazon.com/feeds/2020-09-04/feeds
{
  "feedType":"POST_EASYSHIP_DOCUMENTS",
  "marketplaceIds":["A21TJRUUN4KGV"],
  "feedOptions":
  {
    "AmazonOrderId":"902-3159896-1390916",
    "DocumentType":"ShippingLabel"
  },
  "inputFeedDocumentId":"amzn1.tortuga.3.06438a22-2b6f-4138-a120-362c096d5e04.TKXDFQFUMYD86"
}

Respuesta

Una respuesta exitosa incluye el siguiente elemento:

Ejemplo de respuesta

{
  "payload":
  {
    "feedId": "23492394"
  }
}

2. Salva el valor feedId . Pase este valor en la operación getFeed en el Paso 4. Confirme el procesamiento del feed .

Paso 4. Confirmar procesamiento de feeds

Confirme el procesamiento del feed llamando periódicamente al getFeed hasta que el feed pase a uno de los siguientes estados de terminal: DONE , CANCELLED , o FATAL . Cuando la feed se mueve hacia el estado DONE , continúe con el Paso 5. Obtenga información para recuperar el reporte de procesamiento de feeds .

📘

Los feeds pueden tardar hasta ocho horas en procesarse

En condiciones de alta carga, no es raro que los feeds tarden hasta ocho horas en procesarse. Los feeds de datos de productos se procesan secuencialmente; el feed más reciente se pondrá IN_QUEUE en el sistema de procesamiento hasta que se completen los envíos de feeds anteriores. Se pueden producir retrasos sustanciales en el procesamiento cuando varios feeds de productos contienen solo unos pocos artículos cada uno en lugar de un solo feed de productos con todos los artículos.

1. Llama a operación getFeed , pasando el siguiente parámetro:

Parámetro de ruta:

Ejemplo de solicitud:

GET https://sellingpartnerapi-na.amazon.com/feeds/2020-09-04/feeds/23492394

Respuesta

Una respuesta exitosa incluye los siguientes elementos:

Ejemplo de respuesta

{
  "payload":
  {
    "processingEndTime":"2020-08-10T16:56:55+00:00",
    "processingStatus":"DONE",
    "marketplaceIds":[
      "ATVPDKIKX0DER"
    ],
    "feedId":"23492394",
    "feedType":"POST_PRODUCT_DATA",
    "createdTime":"2020-08-10T16:55:32+00:00",
    "processingStartTime":"2020-08-10T16:55:40+00:00",
    "resultFeedDocumentId":"amzn1.tortuga.3.ed4cd0d8-447b-4c22-96b5-52da8ace1207.T3YUVYPGKE9BMY"
  }
}

2. Compruebe el valor de lo atributo processingStatus .

   • Si processingStatus es IN_QUEUE o IN_PROGRESS , el procesamiento del feed aún no se ha completado. Vuelva a intentar la operación getFeed hasta que processingStatus alcanza uno de los siguientes estados de terminal: DONE , CANCELLED , o FATAL .
   • Si processingStatus es DONE , el procesamiento del feed está completo. Vaya al Paso 5. Obtenga información para recuperar el reporte de procesamiento de feeds .
   • Si processingStatus es CANCELED , el feed se canceló antes de que comenzara a procesarse. Si desea volver a enviar el feed, comience de nuevo en el Paso 1. Crear un documento de feed .
   • Si processingStatus es FATAL , la transmisión se detuvo debido a un error fatal. Es posible que algunas, ninguna o todas las operaciones del feed se hayan completado correctamente. En algunos casos (pero no en todos), Amazon genera un reporte de procesamiento de feeds. Si Amazon genera un reporte, podría tener un formato diferente al de un reporte de procesamiento de feeds para un feed completado con éxito. Vaya al Paso 5. Obtenga información para recuperar el reporte de procesamiento de feeds para intentar recuperar un reporte de procesamiento de feeds. En casos excepcionales, Amazon puede detener un feed por motivos no relacionados con el feed. Si no puede encontrar errores en el feed para corregir, intente enviar el feed nuevamente.

Nota : La operación getFeed solo proporciona información para las solicitudes de feed que se crearon en los últimos 90 días.

Paso 5. Obtener información para recuperar el reporte de procesamiento de feeds

El reporte de procesamiento de feeds indica qué registros del feed que envió se realizaron correctamente y qué registros generaron errores. En este paso, obtiene una URL preestablecida para descargar el reporte de procesamiento del feed, así como la información necesaria para descifrar el contenido del documento. En algunos casos, el objeto puede comprimirse, en cuyo caso se devuelve compressionAlgorithm además de la URL. La URL caduca después de 5 minutos.

1. Llama a operación getFeedDocument , pasando el siguiente parámetro:

Parámetro de ruta

Ejemplo de solicitud

GET https://sellingpartnerapi-na.amazon.com/feeds/2020-09-04/documents/amzn1.tortuga.3.ed4cd0d8-447b-4c22-96b5-52da8ace1207.T3YUVYPGKE9BMY

Respuesta

Una respuesta exitosa incluye los siguientes elementos:

Ejemplo de respuesta:

{
  "payload":
  {
    "feedDocumentId":"amzn1.tortuga.3.ed4cd0d8-447b-4c22-96b5-52da8ace1207.T3YUVYPGKE9BMY",
    "url":"https://tortuga-prod-na.s3.amazonaws.com/%2FNinetyDays/amzn1.tortuga.3.920614b0-fc4c-4393-b0d9-fff175300000.T29XK4YL08B2VM?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20200919T035824Z&X-Amz-SignedHeaders=<headers>&X-Amz-Expires=300&X-Amz-Credential=<credential>&X-Amz-Signature=<signature>",
    "encryptionDetails":
    {
      "standard":"AES",
      "initializationVector":"kF3bZt0FSv6JQEimfEJD8g==",
      "key":"5EZo/P06OGF0UAy8QuOnMIaQbkAvYBru6EGsFvK8wJ2="
    }
  }

1. Salva el initializationVector, Key y url valores para pasar en el paso 6. Descargue y descifre el reporte de procesamiento de feeds .

Paso 6. Descargue y descifre el reporte de procesamiento de feeds

Puede descargar y descifrar el reporte de procesamiento de feeds utilizando la información devuelta en el paso anterior. El siguiente código de muestra de Java, junto con las clases proporcionadas en el Selling Partner API (SP-API) Documents Helper, pueden ayudar. También puede usar los principios demostrados en el código de muestra de Java y en el 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:

   • El key, initializationVector, url, y los valores del compressionAlgorithm optional del paso anterior son argumentos para el key, initializationVector, url, y parámetros del compressionAlgorithm del método downloadAndDecrypt de la claseDownloadExample.

Nota: Es responsabilidad del desarrollador mantener siempre el cifrado en reposo. El contenido de reportes de procesamiento de feeds sin cifrar nunca debe almacenarse en el disco, ni siquiera temporalmente, porque los reportes de procesamiento de feeds pueden contener información confidencial. El código de muestra que proporcionamos demuestra este principio.

Descargar y descifrar código de muestra (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();
 
  // key, initializationVector, url, and compressionAlgorithm are returned by the getFeedDocument 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.
    }
  }
}

Paso 7. Verifique el reporte de procesamiento de feeds para ver si hay errores.

Consulte el reporte de procesamiento de feeds para detectar errores generados durante el procesamiento. Si no hay errores, el envío de su feed está completo. Si hay errores, corríjalos y envíe el feed corregido, comenzando en el Paso 1. Crear un documento de feed . Repita el proceso hasta que no haya errores en el reporte de procesamiento de feeds.

Mejores prácticas

Para conocer las prácticas recomendadas sobre el uso de la Feeds API, consulte Prácticas recomendadas de la Feeds API .