Administración de los productos
Content API es una API de RESTful que usa el recurso Products para administrar las ofertas de productos en el almacén de Microsoft Merchant Center (MMC).
A continuación se muestra el URI base que se usa para llamar a Content API.
https://content.api.bingads.microsoft.com/shopping/v9.1/bmc/
Cada solicitud HTTP debe incluir el token de acceso de OAuth del usuario y el token de desarrollador. Para especificar el token de acceso del usuario, establezca el encabezado AuthenticationToken . Para especificar el token de desarrollador, establezca el encabezado DeveloperToken .
Si administra catálogos en nombre de otros clientes, debe establecer lo siguiente:
- Encabezado CustomerId al identificador de cliente del cliente cuya tienda administra.
- Encabezado CustomerAccountId al identificador de cuenta de cualquiera de las cuentas del cliente que administre (no importa qué cuenta administrada).
De forma predeterminada, content API usa objetos JSON para representar la oferta del producto. Para usar XML, establezca el parámetro de consulta alt en XML.
Para obtener más información sobre el uso del recurso Products, consulte las secciones siguientes.
- Obtención de una oferta de producto de la tienda
- Obtención de una lista de ofertas de productos de la tienda
- Eliminación de una oferta de la tienda
- Adición y actualización de una oferta de producto
- Uso del procesamiento por lotes
Obtención de una oferta de producto de la tienda
Para obtener una oferta de producto específica del almacén, anexe la plantilla siguiente al URI base.
{mmcMerchantId}/products/{productUniqueId}
Establezca {mmcMerchantId} en el identificador de la tienda MMC y establezca en {productUniqueId} el identificador de producto completo (por ejemplo, Online:en:US:Sku123), no en el offerId del producto. Dado que el identificador del producto distingue mayúsculas de minúsculas, use el identificador que la API le devolvió al agregar el producto.
Envíe una solicitud HTTP GET a la dirección URL resultante. Si se encontró el producto, la respuesta contiene un objeto Product que contiene la oferta.
Si insertó un producto con el mismo identificador en varios catálogos, el servicio devuelve solo uno de ellos, qué producto y de qué catálogo no está determinado. Por este motivo, no debe insertar un producto con el mismo identificador de producto en varios catálogos.
Para obtener un ejemplo de código que muestra cómo obtener una oferta de producto, consulte Ejemplo de administración de código de productos.
Obtención de una lista de ofertas de productos de la tienda
Para obtener una lista de las ofertas de productos que se encuentran en el almacén, anexe la siguiente plantilla al URI base.
{mmcMerchantId}/products
Establezca en {mmcMerchantId} el identificador de la tienda MMC.
Para ver la lista de ofertas, use los parámetros de consulta max-results y start-token . En la primera llamada, establezca max-results en el número máximo de ofertas que desea que devuelva el servicio. El número máximo de ofertas que el servicio puede devolver es 250. El valor predeterminado es 25. Envíe una solicitud HTTP GET a la dirección URL resultante. A continuación se muestra un ejemplo de la solicitud.
https://content.api.bingads.microsoft.com/shopping/v9.1/bmc/{mmcMerchantId}/products?max-results=250
Si el almacén contiene ofertas, la respuesta contiene un objeto Product que contiene hasta el número solicitado de ofertas.
Si hay más ofertas disponibles, la respuesta incluye el nextPageToken campo (consulte Productos). El nextPageToken campo contiene el valor de token que se usa para establecer el parámetro en en la start-token siguiente solicitud List. A continuación se muestra un ejemplo que usa el token.
https://content.api.bingads.microsoft.com/shopping/v9.1/bmc/{mmcMerchantId}/products?max-results=250&start-token=DFSos893j...
Para obtener un ejemplo de código que muestra cómo obtener una lista de ofertas de productos, consulte Ejemplo de código de administración de productos.
Eliminación de una oferta de la tienda
Para eliminar una oferta de producto específica del almacén, anexe la siguiente plantilla al URI base.
{mmcMerchantId}/products/{productUniqueId}
Establezca {mmcMerchantId} en el identificador de la tienda MMC y establezca en {productUniqueId} el identificador de producto completo (por ejemplo, Online:en:US:Sku123), no en el offerId del producto. Dado que el identificador del producto distingue mayúsculas de minúsculas, use el identificador que la API le devolvió al agregar el producto.
Envíe una solicitud HTTP DELETE a la dirección URL resultante. Si se encontró el producto, se elimina.
Si ha insertado un producto con el mismo identificador de producto en varios catálogos, el servicio los elimina todos. No debe insertar un producto con el mismo identificador de producto en varios catálogos.
Para obtener un ejemplo de código que muestra cómo eliminar una oferta de producto, consulte Ejemplo de administración de código de productos.
Adición y actualización de una oferta de producto
Agregar o actualizar una oferta es una operación de inserción. Dado que una actualización es una operación de inserción, debe incluir todos los campos de la oferta en la solicitud; no se puede actualizar un solo campo.
Para insertar una oferta de producto, anexe la plantilla siguiente al URI base.
{mmcMerchantId}/products
Establezca en {mmcMerchantId} el identificador de la tienda MMC.
El envío de una solicitud HTTP POST a la dirección URL resultante escribe la oferta en el catálogo de almacén predeterminado. Para escribir la oferta en un catálogo específico, incluya el parámetro de consulta bmc-catalog-id .
https://content.api.bingads.microsoft.com/shopping/v9.1/bmc/{mmcMerchantId}/products?bmc-catalog-id=123456
Si se insertó el producto, la respuesta contiene un objeto Product . El Product objeto incluye el identificador de producto, que se usa para obtener y eliminar la oferta.
Una oferta debe incluir los campos siguientes:
La API usa channel, contentLanguage, targetCountryy offerId para generar el identificador de producto. Dado que estos campos se usan para generar el identificador, es posible que no los actualice. El identificador del producto distingue mayúsculas de minúsculas; el identificador usa el mismo uso de mayúsculas y minúsculas que usó para especificar channel, contentLanguage, targetCountryy offerId.
Precaución
Asegúrese de usar el mismo uso de mayúsculas y minúsculas para channel, contentLanguage, targetCountryy offerId porque puede agregar el mismo producto varias veces si el uso de mayúsculas y minúsculas es diferente.
Los campos siguientes también son necesarios si el fabricante asignó valores.
Debe especificar los valores si se conocen. Si no especifica ninguno de ellos, debe establecer el campo identifierExists en false. The default is true.
Si se sabe que el producto tiene estos identificadores y no los especifica, MMC acepta el producto por ahora, pero el Product objeto de la respuesta incluye el warnings campo . Siempre debe comprobar si el warnings campo existe y corregir todos los problemas identificados.
Además de los campos necesarios, también debe especificar la fecha y hora en que desea que expire la oferta (consulte expirationDate). De forma predeterminada, la oferta expira 30 días a partir de la fecha y hora en que se escribe en la tienda o el catálogo. Debe realizar un seguimiento de los productos que están a punto de expirar y antes de que expiren actualicen su fecha de expiración o simplemente actualicen el producto (no es necesario actualizar ninguno de los campos del producto), lo que amplía automáticamente la fecha de expiración otros 30 días. Si establece explícitamente la fecha de expiración, debe establecer una nueva fecha de expiración usted mismo; Actualizar el producto no extenderá automáticamente la fecha de expiración otros 30 días en este caso.
Todos los demás campos se consideran opcionales; sin embargo, debe especificar tantos como sean necesarios para describir con precisión el producto.
Nota:
El Product objeto solo debe incluir campos que estén establecidos en valores. No incluya campos NULL en el Product objeto . Por ejemplo, no incluya "adult":null.
Microsoft no usa todos los Product campos. Para obtener una lista de los campos que la API acepta pero no usa, consulte ¿Qué atributos de Google puedo usar? Todos los demás campos utilizados por Microsoft se usan para filtrar los productos al publicar anuncios de productos.
Si especifica un campo desconocido para Content API, el servicio omite el campo.
Al insertar una oferta, el servicio realiza validaciones básicas en la oferta y devuelve errores y advertencias según corresponda. Si se produce un error, la respuesta contiene un ErrorResponse objeto . Si se producen advertencias, la respuesta contiene un Product objeto y el warnings campo enumera las advertencias.
Si la oferta supera las validaciones básicas, se somete a validaciones y revisiones sin conexión, como revisiones editoriales, que pueden tardar hasta 36 horas. La oferta no funcionará hasta que se completen todas las validaciones y revisiones. Para determinar el estado de una oferta, use el recurso Status .
Tenga en cuenta que la API no proporciona controles de simultaneidad, como ETags. Si dos aplicaciones intentan agregar o actualizar el mismo producto, la última gana.
Una oferta que se muestra en un anuncio de producto incluye el precio, el título, el nombre de la tienda (o sellerName si se especifica), el vínculo a la página web que contiene más información sobre el producto y una imagen del producto.
En el caso de los productos de ropa que están disponibles en varios colores, patrones o materiales, cree un producto para cada variante y use el campo itemGroupId para agrupar todas las variantes del producto.
Para obtener un ejemplo de código que muestra cómo insertar una oferta de producto, consulte Ejemplo de administración de código de productos.
Uso del procesamiento por lotes
Si está procesando varias ofertas de productos, debe considerar la posibilidad de usar la característica de procesamiento por lotes de la API. Esta característica le permite procesar varias inserciones, obtiene y elimina en una sola solicitud. El procesamiento de varias ofertas en la misma solicitud es más eficaz que enviar una solicitud independiente para cada oferta. El costo incurrido con el procesamiento de una sola solicitud se reparte entre las miles de ofertas de la solicitud por lotes en lugar de incurrir en ese costo para cada solicitud individual.
No inserte, obtenga ni elimine el mismo producto en la misma solicitud.
Para enviar una solicitud por lotes, anexe la plantilla siguiente al URI base.
{mmcMerchantId}/products/batch
Establezca en {mmcMerchantId} el identificador de la tienda MMC.
El envío de una solicitud HTTP POST a la dirección URL resultante aplica las operaciones de inserción al catálogo de almacén predeterminado. Para aplicar las ofertas a un catálogo específico, incluya el parámetro de consulta bmc-catalog-id .
https://content.api.bingads.microsoft.com/shopping/v9.1/bmc/{mmcMerchantId}/products/batch?bmc-catalog-id=123456
El cuerpo del post es un objeto Batch que contiene una matriz de objetos Item . Para todas las operaciones, establezca los batchIdcampos y merchantIdmethod .
batchId es un identificador definido por el usuario que se usa para identificar el elemento por lotes en la respuesta; es el merchantId identificador de almacén y es la method operación que se va a realizar (por ejemplo, insertar, eliminar o obtener).
Si method se inserta, establezca el product campo en un objeto Product que contenga la oferta que se va a agregar o actualizar. De lo contrario, si method es una obtención o eliminación, establezca productId en el identificador completo de la oferta que desea obtener o eliminar.
El tamaño del cuerpo de una solicitud por lotes no puede superar los 4 MB. Si el cuerpo supera los 4 MB, la respuesta devuelve el código de estado HTTP 413. Dependiendo del tamaño de cada oferta (el número de campos que especifique), puede enviar entre 2000 y 6000 ofertas. Si comprime el cuerpo, puede enviar el número máximo de ofertas, que es de 12 000 (dependiendo de su tamaño).
Para comprimir el cuerpo, use solo la compresión GZip y establezca el encabezado Content-Encoding de la solicitud en gzip.
El servicio procesa cada elemento del lote. La respuesta contiene un Batch objeto que contiene cada uno Item que estaba en la solicitud. Tenga en cuenta que no hay ninguna garantía de que el orden de los elementos de la respuesta esté en el mismo orden que los elementos de la solicitud.
Para las operaciones de inserción, el elemento incluye solo los batchId campos y product . El product campo contiene la misma oferta que envió en la solicitud, pero también incluye el identificador de producto completo. Si se produce un error o una advertencia, el elemento incluye los batchIdcampos , methody error . El error campo contiene los motivos por los que se produjo un error en la inserción o advertencias sobre los problemas con la oferta que debe corregir.
Para obtener operaciones, el elemento incluye los batchId campos y product . El product campo contiene la oferta que solicitó. Si no se encuentra el producto, el objeto no incluirá el product campo .
En el caso de las operaciones de eliminación, el elemento solo incluye el batchId campo; no hay ninguna indicación de si la oferta existe y se eliminó.
Para obtener un ejemplo de código que muestra cómo usar el procesamiento por lotes, consulte Creación de una solicitud por lotes.