Guía de casos de uso de la Feeds API v2021-06-30

Versión API: 2021-06-30

¿Qué es la API de feeds?

Con la Selling Partner API para Feeds (Feeds API), puede crear aplicaciones que permitan a los sellers cargar información en Amazon que les ayude a administrar sus negocios de venta. Hay feeds para una amplia variedad de casos de uso, como la creación de listados, la gestión de inventario y precios, el reconocimiento de pedidos y más. Consulte Valores de tipo de feed para obtener una lista de los tipos de feed disponibles.

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. Sube el contenido de tu 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. Sondee periódicamente la cola de Amazon SQS para Evento de notificación FEED_PROCESSING_FINISHED , que proporciona información cuando el procesamiento del feed está CANCELLED , DONE , o FATAL .

   Amazon devuelve el valor resultFeedDocumentId en la notificación cuando el feed se mueve 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 del feed y el algoritmo de compresión.

6. Descargue 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

• URL prefirmada de Amazon S3 : 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 compresionAlgorithm 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 demuestran una forma de cargar un feed y descargar un reporte de resumen de procesamiento de feeds. Puede usar los principios demostrados en el código de muestra para guiarlo en la creación de aplicaciones en otros lenguajes de programación, usar otras bibliotecas HttpClient o cargar feeds con diferentes formatos.

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 Autorización de aplicaciones API de selling partners para obtener más información.
3. Una instalación funcional de Java Development Kit (JDK).

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/2021-06-30/documents
{
  "contentType":"text/xml; charset=UTF-8"
}

Respuesta

Una respuesta exitosa incluye lo siguiente:

Ejemplo de respuesta

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

2. Guarde los siguientes valores:

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

Paso 2. Construir un feed

Cree un feed que pueda cargar en el Paso 3. Sube los datos del feed .

Feeds XML

Para construir un feed XML, debe incluir los tres XSD principales (Base, Envelope, y Header) además del feed específico de su categoría.

XSD principales:

• Base Se utiliza para promover la consistencia entre los feeds. Todos los demás XSD hacen referencia a los elementos y tipos de datos en Base XSD.
• Envelope Se utiliza para envolver todos los demás datos con datos de protocolo de nivel de mensaje. Consiste en un header y uno o más mensajes.
• Header Utilizado por Envelope XSD para especificar datos universales relacionados con lo feed o un mensaje en lo feed.

Para obtener links a XSD para feeds específicas de categoría, vaya a XSD en la Ayuda de Seller Central y busque en la sección Categoría XSD .

El siguiente es un ejemplo de un feed XML para un producto relacionado con la salud:

📘

Utilice una ID de seller para MerchantIdentifier

El valor de MerchantIdentifier en el siguiente feed debe ser un ID de seller. Su ID de seller se puede encontrar en Seller Central en Configuración > Información de la cuenta > Su token de comerciante .

<?xml version="1.0" encoding="iso-8859-1"?>
<AmazonEnvelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="amzn-envelope.xsd">
  <Header>
    <DocumentVersion>1.01</DocumentVersion>
    <MerchantIdentifier>XXXXXXXXXXXXX</MerchantIdentifier>
  </Header>
  <MessageType>Product</MessageType>
  <PurgeAndReplace>false</PurgeAndReplace>
  <Message>
    <MessageID>1</MessageID>
    <OperationType>Update</OperationType>
    <Product>
      <SKU>56789</SKU>
      <StandardProductID>
        <Type>ASIN</Type>
        <Value>B0EXAMPLEG</Value>
      </StandardProductID>
      <ProductTaxCode>A_GEN_NOTAX</ProductTaxCode>
      <DescriptionData>
        <Title>Example Product Title</Title>
        <Brand>Example Product Brand</Brand>
        <Description>This is an example product description.</Description>
        <BulletPoint>Example Bullet Point 1</BulletPoint>
        <BulletPoint>Example Bullet Point 2</BulletPoint>
        <MSRP currency="USD">25.19</MSRP>
        <Manufacturer>Example Product Manufacturer</Manufacturer>
        <ItemType>example-item-type</ItemType>
      </DescriptionData>
      <ProductData>
        <Health>
          <ProductType>
            <HealthMisc>
              <Ingredients>Example Ingredients</Ingredients>
              <Directions>Example Directions</Directions>
            </HealthMisc>
          </ProductType>
        </Health>
      </ProductData>
    </Product>
  </Message>
</AmazonEnvelope>

Paso 3. Sube los datos del feed

Puede cargar el feed que creó en el Paso 2. Construya un feed usando la información devuelta en el Paso 1. Crear un documento de feed . El siguiente código de ejemplo muestra una forma de cargar el contenido de lo feed. También puede usar los principios demostrados en el código de muestra para guiarlo en la creación de aplicaciones en otros lenguajes de programación o en el uso de otras bibliotecas HttpClient.

La muestra método upload que se muestra en la clase UploadExample acepta el contenido de su feed como primer argumento, y el valor url que guardó en el paso 1 como segundo argumento.

Cargar código de muestra (Java)

// UploadExample.java
// This example is for use with the Selling Partner API for Feeds, Version: 2021-06-30
import java.io.IOException;
import java.nio.charset.StandardCharsets;

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

/**
 * Example that uploads content.
 */
public class UploadExample {

  public static void main(String args[]) {
    String url = "<URL from the createFeedDocument operation>";
    String content = "<your feed content>";

    UploadExample obj = new UploadExample();
    obj.upload(content.getBytes(StandardCharsets.UTF_8), url);
  }

  /**
   * Upload content to the given URL.
   *
   * @param source the content to upload
   * @param url    the URL to upload content
   */
  public void upload(byte[] source, String url) {
    OkHttpClient client = new OkHttpClient();

    // The contentType must match the input provided to the createFeedDocument operation. This example uses text/xml, but your contentType may be different depending upon on your chosen feedType (text/plain, text/csv, and so on).
    String contentType = String.format("text/xml; charset=%s", StandardCharsets.UTF_8);
    try {
      Request request = new Request.Builder()
        .url(url)
        .put(RequestBody.create(MediaType.parse(contentType), source))
        .build();

      Response response = client.newCall(request).execute();
      if (!response.isSuccessful()) {
        System.out.println(
          String.format("Call to upload document failed with response code: %d and message: %s",
            response.code(), response.message()));
      }
    } catch (IOException e) {
      System.out.println(e.getMessage());
    }

  }
}

Paso 4. 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 lo 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/2021-06-30/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 (Easy Ship order)

POST https://sellingpartnerapi-na.amazon.com/feeds/2021-06-30/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

{
  "feedId": "23492394"
}

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

Paso 5. 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 6. 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/2021-06-30/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 la 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 6. 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 6. 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 6. 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 compresionAlgorithm 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/2021-06-30/documents/amzn1.tortuga.3.ed4cd0d8-447b-4c22-96b5-52da8ace1207.T3YUVYPGKE9BMY

Respuesta

Una respuesta exitosa incluye los siguientes elementos:

Ejemplo de respuesta:

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

1. Salva el URL y opcional valores del compressionAlgorithm para pasar en el paso 7. Descargue el reporte de procesamiento de feeds .

Paso 7. Descargar el reporte de procesamiento de feeds

Puede descargar el reporte de procesamiento de feeds utilizando la información devuelta en el paso anterior. El siguiente código de muestra de Java puede ayudar. También puede usar los principios demostrados en el código de muestra de Java 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 url y los valores del compressionAlgorithm opcional del paso anterior son argumentos para el url y parámetros del compressionAlgorithm del método download del clase DownloadExample.

Nota: Es responsabilidad del desarrollador mantener siempre el cifrado en reposo. El contenido de reporte 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 código de muestra (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();
        }
      }
    }
  }
}

Paso 8. 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.

Uso de múltiples marketplaces

Si está registrado en varios marketplaces, entonces tiene varios valores de marketplaceId asociados con su ID de seller. Para una lista de valores de marketplaceId , consulte Marketplace IDs . Puede enviar un feed que se aplique a uno o varios valores marketplaceId . Si se encuentra en la región de la UE o NA, puede enviar feeds para admitir varios marketplaces si se ha registrado con una cuenta de seller. única y unificada.

Si vende en varios marketplaces, puede administrar sus niveles de inventario utilizando los mismos SKU en varios marketplaces. Esto elimina la necesidad de mantener sincronizados manualmente los niveles de inventario en varios marketplaces. Para obtener más información sobre cómo vender en varios marketplaces, consulte Vender en los marketplaces europeos de Amazon .

Entender cómo se utilizan valores marketplaceId

Usted especifica a qué marketplaces desea que se aplique un feed proporcionando una lista de valores marketplaceId para el parámetro marketplaceIds cuando llama la operación [createFeed](referencia-de-la-feeds-api-v2021-06-30#post-feeds2021-06-30feeds) . Por ejemplo, un seller de múltiples marketplaces de la UE podría especificar que se aplique un feed a sus marketplaces FR y DE especificando el parámetro marketplaceIds de la siguiente manera:

[
  "A13V1IB3VIYZZH",
  "A1PA6795UKMFR9"
]

Para los sellers de la UE y NA, no necesita usar un endpoint de país específico, como https://sellingpartnerapi-eu.amazon.com , para indicar a qué marketplace se debe aplicar un feed. Puede aplicar cambios a un marketplace de la UE o NA determinado especificando que marketplaceId al enviar un feed. Para una lista de valores de marketplaceId , consulte Marketplace IDs .

Mejores prácticas

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