Competencia en catálogo

En catálogo, las publicaciones compiten por obtener las ventas de la página de producto y un algoritmo determina quién será el ganador de esas ventas en base a características de la publicación y del vendedor mismo, como Precio de la publicación, Cuotas sin interés, Envío full, gratis o en el día. Además, hablaremos de “el ganador” en forma unívoca, aunque eventualmente el vendedor podría estar ganando en general pero no en particular para ciertos usuarios (por ejemplo, si viven muy lejos y no obtendrían un envío en el día).

Recibir notificaciones de publicaciones compitiendo en catálogo

Con el tópico Item competition podrás suscribirte y comenzar a recibir notificaciones del cambio de estado de los ítems de catálogo, y te permitirá reconocer el ítem que modifica su estado de competencia a ganador o viceversa. Para ver la información de la competencia y revisar las condiciones con las que el vendedor está compitiendo para ganar la página de producto, utiliza el recurso /price_to_win para saber qué acciones realizar.

Conocer el precio para ganar en catálogo

Importante:

Los vendedores que compartan condiciones de venta en sus productos similares a las del ganador de catálogo, tienen una parte de visibilidad en la página de producto y su estado es“sharing_first_place”.

Con el recurso /price_to_win?siteId=$SITE_ID&version=v2 reconoces el estado de la publicación de catálogo: puede estar ganando, compartiendo primer lugar, perdiendo o listada. Este último significa que tiene razones por las cuales la publicación no compite.
También puedes armar una tabla de competencia para comparar las condiciones de los items y mejorarlos en base a la competencia. Con esta funcionalidad en tu desarrollo, los vendedores conocerán qué condiciones mejorar para ganar la página de producto.

Ejemplo de ítem perdiendo

Llamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/$ITEM_ID/price_to_win?siteId=$SITE_ID&version=v2

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/MLA123456789/price_to_win?siteId=MLA&version=v2

Respuesta:

{
   "item_id": "MLA901414479",
   "current_price": 12999,
   "currency_id": "ARS",
   "price_to_win": 11500,
   "boosts": [
       {
           "id": "same_day_shipping",
           "status": "boosted",
           "description": "Envíos en el día por Mercado Envíos"
       },
       {
           "id": "fulfillment",
           "status": "opportunity",
           "description": "Mercado Envíos Full"
       },
       {
           "id": "free_installments",
           "status": "opportunity",
           "description": "Cuotas sin interés"
       },
       {
           "id": "free_shipping",
           "status": "not_apply",
           "description": "Envíos gratis por Mercado Envíos"
       },
       {
           "id": "shipping_collect",
           "status": "boosted",
           "description": "Mercado Envíos Colecta"
       }
   ],
   "status": "competing",
   "competitors_sharing_first_place": "null",
   "visit_share": "minimum",
   "consistent": true,
   "reason": [],
   "catalog_product_id": "MLA16107499",
   "winner": {
       "item_id": "MLA884484295",
       "price": 13499,
       "currency_id": "ARS",
       "boosts": [
           {
               "id": "same_day_shipping",
               "status": "boosted",
               "description": "Envíos en el día por Mercado Envíos"
           },
           {
               "id": "fulfillment",
               "status": "opportunity",
               "description": "Mercado Envíos Full"
           },
           {
               "id": "free_installments",
               "status": "boosted",
               "description": "Cuotas sin interés"
           },
           {
               "id": "free_shipping",
               "status": "not_apply",
               "description": "Envíos gratis por Mercado Envíos"
           },
           {
               "id": "shipping_collect",
               "status": "boosted",
               "description": "Mercado Envíos Colecta"
           }
       ]
   }
}

Ejemplo de ítem ganando

Llamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/$ITEM_ID/price_to_win?siteId=$SITE_ID&version=v2

Ejemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/MLA123456789/price_to_win?siteId=MLA&version=v2

Respuesta:

{
   "item_id": "MLA884484295",
   "current_price": 13499,
   "currency_id": "ARS",
   "price_to_win": 13499,
   "boosts": [
       {
           "id": "same_day_shipping",
           "status": "boosted",
           "description": "Envíos en el día por Mercado Envíos"
       },
       {
           "id": "fulfillment",
           "status": "opportunity",
           "description": "Mercado Envíos Full"
       },
       {
           "id": "free_installments",
           "status": "boosted",
           "description": "Cuotas sin interés"
       },
       {
           "id": "free_shipping",
           "status": "not_apply",
           "description": "Envíos gratis por Mercado Envíos"
       },
       {
           "id": "shipping_collect",
           "status": "boosted",
           "description": "Mercado Envíos Colecta"
       }
   ],
   "status": "winning",
   "competitors_sharing_first_place": "0",
   "visit_share": "maximum",
    "consistent": true,
   "reason": [],
   "catalog_product_id": "MLA16107499",
   "winner": {
       "item_id": "MLA884484295",
       "price": 13499,
       "currency_id": "ARS",
       "boosts": [
           {
               "id": "same_day_shipping",
               "status": "boosted",
               "description": "Envíos en el día por Mercado Envíos"
           },
           {
               "id": "fulfillment",
               "status": "opportunity",
               "description": "Mercado Envíos Full"
           },
           {
               "id": "free_installments",
               "status": "boosted",
               "description": "Cuotas sin interés"
           },
           {
               "id": "free_shipping",
               "status": "not_apply",
               "description": "Envíos gratis por Mercado Envíos"
           },
           {
               "id": "shipping_collect",
               "status": "boosted",
               "description": "Mercado Envíos Colecta"
           }
       ]
   }
}

Ejemplo de ítem compartiendo primer lugar

Nota:

El estado “sharing_first_place” identifica a todos los vendedores con la mejor oferta y un nivel de exposición compartida en Catálogo.

Ejemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/MLA123456710/price_to_win?siteId=MLA&version=v2

Respuesta:

{
   "item_id": "MLA901414479",
   "current_price": 12999,
   "currency_id": "ARS",
   "price_to_win": 11500,
   "boosts": [
       {
           "id": "same_day_shipping",
           "status": "boosted",
           "description": "Envíos en el día por Mercado Envíos"
       },
       {
           "id": "fulfillment",
           "status": "opportunity",
           "description": "Mercado Envíos Full"
       },
       {
           "id": "free_installments",
           "status": "opportunity",
           "description": "Cuotas sin interés"
       },
       {
           "id": "free_shipping",
           "status": "not_apply",
           "description": "Envíos gratis por Mercado Envíos"
       },
       {
           "id": "shipping_collect",
           "status": "boosted",
           "description": "Mercado Envíos Colecta"
       }
   ],
   "status": "sharing_first_place",
   "competitors_sharing_first_place": "2",
   "visit_share": "medium",
   "consistent": true,
   "reason": [],
   "catalog_product_id": "MLA16107499",
   "winner": {
       "item_id": "MLA884484295",
       "price": 13499,
       "currency_id": "ARS",
       "boosts": [
           {
               "id": "same_day_shipping",
               "status": "boosted",
               "description": "Envíos en el día por Mercado Envíos"
           },
           {
               "id": "fulfillment",
               "status": "opportunity",
               "description": "Mercado Envíos Full"
           },
           {
               "id": "free_installments",
               "status": "boosted",
               "description": "Cuotas sin interés"
           },
           {
               "id": "free_shipping",
               "status": "not_apply",
               "description": "Envíos gratis por Mercado Envíos"
           },
           {
               "id": "shipping_collect",
               "status": "boosted",
               "description": "Mercado Envíos Colecta"
           }
       ]
   }
}

Ejemplo de ítem no compitiendo

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/MLA123456710/price_to_win?siteId=MLA&version=v2

Respuesta:

{
   "item_id":"MLA123456710",
   "current_price":68000,
   "currency_id":"ARS",
   "price_to_win":null,
   "boosts":{
      "same_day_shipping":false,
      "fulfillment":false,
      "free_installments":false,
      "free_shipping":true,
      "cross_docking":false,
      "drop_off":true,
      "shipping_quarantine":false
   },
   "status":"listed",
   "competitors_sharing_first_place": null,
   "visit_share": "minimum",
   "reason":[
      "item_paused"
   ]
}

Campos de la respuesta

price_to_win: precio en la moneda actual de la publicación para ser el ganador, es decir, que realizando un PUT al recurso /items con el precio sugerido, la publicación ganará la página de producto.
boosts: características de la publicación que aportan chances de ganar, como:

same_day_shipping: Envíos en el día con Mercado Envíos.
fulfillment: Mercado Envíos Full.
free_installments: Cuotas sin interés.
free_shipping: Envíos gratis con Mercado Envíos.
shipping_quarantine: Envío con normalidad.
shipping_collect: Mercado Envíos Colecta.

Ahora, puedes reconocer dentro del boost el estado de estos y dibujar una tabla comparativa según corresponda.

Estado del boost	Detalle
boosted	Tiene la condición de venta y actualmente aplica el boost.
not_boosted	Tiene la condición de venta pero no es un boost que mejora las posibilidades de ganar.
opportunity	No tiene la condición de venta. Si se aplica, mejoraría las chances de ganar.
not_apply	La condición de venta no aplica como boost en el producto donde compite el ítem.

Note:

Esta información te permite comparar rápidamente con el segundo listado sobre la publicación del ítem que se encuentra ganando la página de producto.

status: indica si el producto está ganando para el público general o para segmentos minoritarios como quienes que no aprovechan el envío en el día. Cuando está ganando, el valor es winning, sino será competing para el que se encuentra perdiendo y se suma un nuevo valor sharing_first_place para cuando se comparte primer lugar y se dividen entre todos los que comparte el primer lugar en base a sus condiciones los niveles de visibilidad en la página de producto.
competitors_sharing_first_place indica la cantidad de vendedores que comparten el primer lugar. Dependerá también de los estados:

Winning: será 0, ya que al ser ganador se lleva todas las ventas y visibilidad en el catálogo.
Competing: será null, ya que al perder tiene que mejorar las condiciones para compartir el primer lugar o ganar.
Listed: será null, ya que al perder tiene que mejorar las condiciones para compartir el primer lugar o ganar.
Sharing_first_place: cantidad de vendedores compitiendo por el primer lugar.

visit_share: nivel de visibilidad de la publicación en catálogo. Los valores pueden variar dependiendo los estados:

Winning: Siempre será maximum.
Competing: Siempre será minimum.
Sharing_first_place: Siempre será medium.

reason: motivo por el cual el ítem no está compitiendo. Los valores posibles son:

Reason	Explicación
non_trusted_seller	El vendedor no está en la whitelist de fraude. No puede competir. Aparece en los listados al final.
reputation_below_threshold	El vendedor no alcanza la reputación mínima para poder ganar. No puede competir. Solamente aparece en los listados.
winner_has_better_reputation	El vendedor tiene una reputación que podría competir pero hay un ganador con mejor reputación. Por el momento, solo aparece en los listados (caso amarillo con winner verde).
manufacturing_time	El ítem tiene manufacturing time, solo aparece en los listados y no puede ganar porque el ganador tiene stock inmediato.
temporarily_winning_manufacturing_time	El ítem tiene manufacturing time, está ganando temporalmente porque no hay competidores en el mismo nivel de reputación sin MF.
temporarily_competing_manufacturing_time	El ítem tiene manufacturing time, esta compitiendo temporalmente porque no hay competidores en el mismo nivel de reputación sin MF, el ganador también tiene MF.
temporarily_winning_best_reputation_available	El vendedor no es verde pero cuenta con una reputación que puede ganar y es la mejor oferta disponible. Está ganando temporalmente. Si aparece una mejor oferta, deja de ganar.
temporarily_competing_best_reputation_available	El vendedor no es verde pero es la mejor reputación disponible, está compitiendo temporalmente. El ganador también es de la misma reputación. Si aparece un mejor vendedor, vuelve a solo estar listado.
item_paused	El ítem está pausado, no puede listarse.
item_not_opted_in	El ítem no ha hecho opt in, no puede listarse o es un ítem de test.

En esta llamada utiliza un item_id de una publicación de catálogo. En caso de no hacerlo obtendrás un código de error 4XX.
Además existen variables como la reputación que son utilizadas para determinar el ganador. Sin embargo, para un buen vendedor, serán las anteriores las variables utilizadas para determinar el ganador.

Conocer la publicación que está ganando un producto

Usando el recurso de /products/$PRODUCT_ID podrás, además de conocer las características y estado del producto, reconocer mediante el campo buy_box_winner la publicación que está ganando la página de producto.

Listado de publicaciones para un producto

Si necesitas conocer cuáles son los artículos (de todos los vendedores) que compiten por las ventas de un producto en particular tienes un recurso que te entrega esa información.

Llamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/products/$PRODUCT_ID/items

Ejemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/products/MLB6309815/items

Respuesta simplificada:

{
  "paging": {
    "total": 7,
    "offset": 0,
    "limit": 100
  },
  "results": [
    {
      "item_id": "MLA824759321",
      "category_id": "MLA1055",
      "seller_id": 90205574,
      "price": 13999,
      "currency_id": "ARS",
      "sold_quantity": 0,
      "available_quantity": 1,
      "shipping": {
        "mode": "me2",
        "tags": [
          "mandatory_free_shipping"
        ],
        "free_shipping": true,
        "logistic_type": "fulfillment",
        "store_pick_up": false
      },
      "warranty": "Garantía de fábrica: 1 años",
      "condition": "new",
      "sale_terms": [
        {
          "id": "INVOICE",
          "name": "Facturación",
          "value_id": "6891885",
          "value_name": "Factura A",
          "value_struct": null
        },
        {
          "id": "WARRANTY_TYPE",
          "name": "Tipo de garantía",
          "value_id": "2230279",
          "value_name": "Garantía de fábrica",
          "value_struct": null
        },
        {
          "id": "WARRANTY_TIME",
          "name": "Tiempo de garantía",
          "value_id": null,
          "value_name": "1 años",
          "value_struct": {
            "number": 1,
            "unit": "años"
          }
        }
      ],
      "official_store_id": null,
      "original_price": null,
      "listing_type_id": "gold_special",
      "accepts_mercadopago": true,
      "seller_address": {
        "city": {
          "id": "TUxBQ0xBWmI3M2Q3",
          "name": "Santa Fe"
        },
        "state": {
          "id": "TUxBUFNBTmU5Nzk2",
          "name": "Santa Fe"
        },
        "neighborhood": {
          "id": "TUxBQk9UUjQyMjJa",
          "name": "Otros Barrios"
        }
      },
      "international_delivery_mode": "none",
      "tags": [
        "extended_warranty_eligible",
        "good_quality_picture",
        "good_quality_thumbnail",
        "immediate_payment",
        "cart_eligible"
      ],
      "tier": ""
    },
    {},
    {},
    {},
    {},
    {},
    {}
  ]
}

Ten en cuenta que “results” devolverá los ítems que están compitiendo para ganar ese producto.

Filtrado

El filtrado funciona igual que en el recurso de Search (/sites/{site}/search) donde es posible utilizar los valores de available_filters como parámetro en la URL.

Actualmente cuentas con las siguientes opciones de filtrado:

Parámetro	Valor	Explicación
official_store	all	Para que se muestren solo productos ganadores de Tiendas Oficiales.
official_store_id	id	Para mostrar los productos ganadores de una Tienda Oficial.
discount	10-100	Para mostrar productos ganadores con descuento mayor o igual al 10%.
price	100-200	Para productos ganadores con precio entre 100 y 200 100 para productos ganador con precio mayor o igual a 100. 200 para productos ganadores con precio menor o igual a 200.
shipping	fulfillment	Para productos ganadores con FBM.
shipping	mercadoenvios	Para productos ganadores sin FBM.
shipping_cost	free	Para productos ganadores con envío gratis.
shipping_time	sameday/ nextday	Debe ser usado junto con el query param b.buyer_zones el cual indica en qué zonas se encuentra el comprador.
seller_id	id	Obtener el ganador user_id

Ejemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/products/MLB6309815/items?shipping_cost=free

Conoce más sobre Competencia en catálogo.

Siguiente: Destaque especial en catálogo.