Última actualización 23/08/2022

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, con base en características de la publicación y del vendedor mismo, como precio de la publicación, cuotas sin interés y tipo de envío: full, gratis o en el día.

Importante:
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 mismo día de la compra).

Notificaciones por cambio de estado en la competencia

Con el tópico Item competition podrás suscribirte y comenzar a recibir notificaciones sobre el cambio de estado de las publicaciones de catálogo, te permitirá reconocer la publicación que modifica su estado de competencia a ganador o viceversa.


Conocer el precio para ganar

Con este recurso puedes reconocer el estado de la publicación de un vendedor dentro 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.


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 de llamada para una publicación que está perdiendo en competencia:


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

Respuesta con "status": "competing":

{
   "item_id": "MLA1142208727",
   "current_price": 539990,
   "currency_id": "ARS",
   "price_to_win": 487622,
   "boosts": [
       {
           "id": "fulfillment",
           "status": "opportunity",
           "description": "Mercado Envíos Full"
       },
       {
           "id": "free_installments",
           "status": "opportunity",
           "description": "Cuotas sin interés"
       },
       {
           "id": "free_shipping",
           "status": "boosted",
           "description": "Envíos gratis por Mercado Envíos"
       },
       {
           "id": "shipping_collect",
           "status": "boosted",
           "description": "Mercado Envíos Colecta"
       },
       {
           "id": "same_day_shipping",
           "status": "boosted",
           "description": "Envíos en el día por Mercado Envíos"
       }
   ],
   "status": "competing",
   "consistent": true,
   "visit_share": "minimum",
   "competitors_sharing_first_place": null,
   "reason": [],
   "catalog_product_id": "MLA18494233",
   "winner": {
       "item_id": "MLA1110011006",
       "price": 492499,
       "currency_id": "ARS",
       "boosts": [
           {
               "id": "fulfillment",
               "status": "opportunity",
               "description": "Mercado Envíos Full"
           },
           {
               "id": "free_installments",
               "status": "opportunity",
               "description": "Cuotas sin interés"
           },
           {
               "id": "free_shipping",
               "status": "boosted",
               "description": "Envíos gratis por Mercado Envíos"
           },
           {
               "id": "shipping_collect",
               "status": "boosted",
               "description": "Mercado Envíos Colecta"
           },
           {
               "id": "same_day_shipping",
               "status": "boosted",
               "description": "Envíos en el día por Mercado Envíos"
           }
       ]
   }
}

Ejemplo de llamada para una publicación que está ganando en competencia:


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

Respuesta con "status": "winning":

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

Ejemplo de llamada para una publicación que está compartiendo el primer lugar en competencia:

Nota:
El “status”:“sharing_first_place” identifica a todos los vendedores que según las condiciones de la oferta actualmente comparten el primer lugar como “ganador”.

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

Respuesta con "status": "sharing_first_place":

{
   "item_id": "MLA1150170600",
   "current_price": 493000,
   "currency_id": "ARS",
   "price_to_win": 485109,
   "boosts": [
       {
           "id": "fulfillment",
           "status": "opportunity",
           "description": "Mercado Envíos Full"
       },
       {
           "id": "free_installments",
           "status": "opportunity",
           "description": "Cuotas sin interés"
       },
       {
           "id": "free_shipping",
           "status": "boosted",
           "description": "Envíos gratis por Mercado Envíos"
       },
       {
           "id": "shipping_collect",
           "status": "boosted",
           "description": "Mercado Envíos Colecta"
       },
       {
           "id": "same_day_shipping",
           "status": "boosted",
           "description": "Envíos en el día por Mercado Envíos"
       }
   ],
   "status": "sharing_first_place",
   "consistent": true,
   "visit_share": "medium",
   "competitors_sharing_first_place": 1,
   "reason": [],
   "catalog_product_id": "MLA18494233",
   "winner": {
       "item_id": "MLA1110011006",
       "price": 492499,
       "currency_id": "ARS",
       "boosts": [
           {
               "id": "fulfillment",
               "status": "opportunity",
               "description": "Mercado Envíos Full"
           },
           {
               "id": "free_installments",
               "status": "opportunity",
               "description": "Cuotas sin interés"
           },
           {
               "id": "free_shipping",
               "status": "boosted",
               "description": "Envíos gratis por Mercado Envíos"
           },
           {
               "id": "shipping_collect",
               "status": "boosted",
               "description": "Mercado Envíos Colecta"
           },
           {
               "id": "same_day_shipping",
               "status": "boosted",
               "description": "Envíos en el día por Mercado Envíos"
           }
       ]
   }
}

Ejemplo de llamada para una publicación que no está compitiendo:


curl -X GET https://api.mercadolibre.com/items/MLA1146313673/price_to_win?access_token=$ACCESS_TOKEN

Respuesta con "status": "listed":


{
   "item_id": "MLA1146313673",
   "current_price": 239999,
   "currency_id": "ARS",
   "price_to_win": null,
   "boosts": [
       {
           "id": "fulfillment",
           "status": "opportunity",
           "description": "Mercado Envíos Full"
       },
       {
           "id": "free_installments",
           "status": "opportunity",
           "description": "Cuotas sin interés"
       },
       {
           "id": "free_shipping",
           "status": "boosted",
           "description": "Envíos gratis por Mercado Envíos"
       },
       {
           "id": "shipping_collect",
           "status": "boosted",
           "description": "Mercado Envíos Colecta"
       },
       {
           "id": "same_day_shipping",
           "status": "opportunity",
           "description": "Envíos en el día por Mercado Envíos"
       }
   ],
   "status": "listed",
   "consistent": true,
   "visit_share": "minimum",
   "competitors_sharing_first_place": null,
   "reason": [
       "reputation_below_threshold"
   ],
   "catalog_product_id": "MLA16163648",
   "winner": {
       "item_id": "MLA930793214",
       "price": 267999,
       "currency_id": "ARS",
       "boosts": [
           {
               "id": "fulfillment",
               "status": "opportunity",
               "description": "Mercado Envíos Full"
           },
           {
               "id": "free_installments",
               "status": "opportunity",
               "description": "Cuotas sin interés"
           },
           {
               "id": "free_shipping",
               "status": "boosted",
               "description": "Envíos gratis por Mercado Envíos"
           },
           {
               "id": "shipping_collect",
               "status": "boosted",
               "description": "Mercado Envíos Colecta"
           },
           {
               "id": "same_day_shipping",
               "status": "boosted",
               "description": "Envíos en el día por Mercado Envíos"
           }
       ]
   }
}

Campos de la respuesta

price_to_win: Indica el 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 Indica las características de la publicación que aportan chances de ganar:

Puedes reconocer dentro del campo “boosts” el estado 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.

status: Indica si el producto está ganando para el público general o para segmentos minoritarios, por ejemplo: quienes no aprovechan el envío en el mismo día. Cuando está ganando, el valor es winning, de lo contrario será competing indica que se encuentra perdiendo, adicionalmente el valor sharing_first_place para cuando se comparte primer lugar con otras publicaciones dentro de la página de producto.
visit_share: Indica el nivel de visibilidad que tiene tu publicación en el catálogo. Estos valores pueden variar dependiendo los estados:

  • Winning: Siempre será “maximum”.
  • Competing: Siempre será "minimum".
  • Sharing_first_place: Siempre será "medium.

competitors_sharing_first_place: Indica la cantidad de vendedores que comparten el primer lugar. Por lo que dependerá también de los estados de las publicaciones:

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

  • reason: Mostrará información únicamente cuando la publicación no esté compitiendo, pudiendo identificar el motivo por el cual no lo está haciendo.


    Valores posibles para reason:

    Reason Explicación
    non_trusted_seller El vendedor no puede competir porque se encuentra marcado como “vendedor no confiable”. Aparece en los listados al final.
    reputation_below_threshold El vendedor no puede competir, ya que no alcanza la reputación requerida para poder ganar. 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 La publicación tiene manufacturing time, aparece en los listados y no puede ganar porque el ganador tiene stock inmediato.
    temporarily_winning_manufacturing_time La publicación tiene manufacturing time, está ganando temporalmente porque no hay competidores en el mismo nivel de reputación sin manufacturing time.
    temporarily_competing_manufacturing_time La publicación tiene manufacturing time, está compitiendo temporalmente porque no hay competidores en el mismo nivel de reputación sin manufacturing time, el ganador también tiene manufacturing time.
    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 tiene 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 estar únicamente listado.
    item_paused La publicación está pausada, no puede listarse.
    item_not_opted_in La publicación no ha hecho opt in, no puede listarse, se utilizó en la llamada un item_id de una publicación que no es de catálogo o es un ítem de test por eso no puede entrar a competir.

    catalog_product_id: Indica el ID de la página de producto a la que pertenece la publicación.
    winner: Indica el detalle del producto que está actualmente como ganador, permitiendo realizar una comparación rápida, con el item_id de la publicación que estás consultando, mostrando campos como: "item_id", "price", "currency_id" y "boosts".


    Qué publicación está ganando

    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.
    Ejemplo de respuesta acotada, del detalle de una página de producto:

    {
        "id": "MLM12345",
        "status": "active",
        "sold_quantity": 391,
        "domain_id": "MLM-CELLPHONES",
        "permalink": "https://www.mercadolibre.com.mx/apple-iphone-13-pro-128-gb-grafito,
        "name": "Apple iPhone 13 Pro (128 GB) - Grafito",
        "family_name": "Apple iPhone 13 Pro",
        "buy_box_winner": {
            "item_id": "MLM987654321",
            "category_id": "MLM1055",
            "seller_id": 1234567,
            "price": 25219,
            "currency_id": "MXN",
            "sold_quantity": 362,
            "available_quantity": 110,
            "shipping": {
                "mode": "me2",
                "tags": [
                    "mandatory_free_shipping"
                ],
                "free_shipping": true,
                "logistic_type": "fulfillment",
                "store_pick_up": false
            },
            "warranty": "Garantía de fábrica: 12 meses",
            "condition": "new",
            "sale_terms": [...],
            "official_store_id": 3953,
            "original_price": 25999,
            "listing_type_id": "gold_pro",
            "accepts_mercadopago": true,
            "seller_address": {...},
            "international_delivery_mode": "none",
            "tags": [...],
            "item_override_attributes": [],
            "seller": {
                "reputation_level_id": "GREEN",
                "tags": []
            },
            "deal_ids": [...],
            "tier": "candidate",
            "inventory_id": "DHEV26968",
            "product_id": "MLM18494248",
            "site_id": "MLM"
        },
        "buy_box_winner_price_range": {
            "min": {
                "price": 25219,
                "currency_id": "MXN"
            },
            "max": {
                "price": 38999,
                "currency_id": "MXN"
            }
        },
        "pickers": [ ... ],
        "pictures": [ ... ],
        "main_features": [ ... ],
        "attributes": [ ... ],
        "short_description": { ... },
        "parent_id": "MLM18494246",
        "children_ids": [],
        "settings": { ... },
        "buy_box_activation_date": "2022-04-22T15:20:15Z",
        "authority_types": [ ... ],
        "date_created": "2021-09-27T18:13:54Z"
    }

    Listado de publicaciones de una página de producto

    Si necesitas conocer cuáles son todas las publicaciones de catálogo (de todos los vendedores) que compiten por las ventas de una página de producto, puedes realizar la siguiente 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/MLA18494233/items

    Respuesta simplificada:

    {
        "paging": {
            "total": 41,
            "offset": 0,
            "limit": 100
        },
        "results": [
            {
                "item_id": "MLA1110011006",
                "site_id": "MLA",
                "seller_id": 1234567,
                "accepts_mercadopago": true,
                "sold_quantity": 25,
                "available_quantity": 1,
                "price": 492499,
                "category_id": "MLA1055",
                "currency_id": "ARS",
                "warranty": "Garantía de fábrica: 12 meses",
                "condition": "new",
                "listing_type_id": "gold_special",
                "international_delivery_mode": "none",
                "tier": "",
                "inventory_id": "",
                "tags": [
                    "good_quality_picture",
                    "good_quality_thumbnail",
                    "extended_warranty_eligible",
                    "immediate_payment",
                    "cart_eligible"
                ],
                "deal_ids": [],
                "official_store_id": null,
                "original_price": null,
                "shipping": {
                    "free_shipping": true,
                    "store_pick_up": false,
                    "mode": "me2",
                    "logistic_type": "xd_drop_off",
                    "tags": [
                        "self_service_in",
                        "mandatory_free_shipping"
                    ]
                },
                "seller_address": {...
                },
                "sale_terms": [
                    {
                        "value_struct": null,
                        "id": "INVOICE",
                        "name": "Facturación",
                        "value_name": "Factura A",
                        "value_id": "6891885"
                    },
                    {
                        "value_struct": {
                            "number": 12,
                            "unit": "meses"
                        },
                        "id": "WARRANTY_TIME",
                        "name": "Tiempo de garantía",
                        "value_name": "12 meses",
                        "value_id": null
                    },
                    {
                        "value_struct": null,
                        "id": "WARRANTY_TYPE",
                        "name": "Tipo de garantía",
                        "value_name": "Garantía de fábrica",
                        "value_id": "2230279"
                    }
                ]
            },
            {
                "item_id": "MLA1150170600",
                "site_id": "MLA",
                "seller_id": 7654321,
                "accepts_mercadopago": true,
                "sold_quantity": 1,
                "available_quantity": 1,
                "price": 493000,
                "category_id": "MLA1055",
                "currency_id": "ARS",
                "warranty": "Garantía de fábrica: 12 meses",
                "condition": "new",
                "listing_type_id": "gold_special",
                "international_delivery_mode": "none",
                "tier": "",
                "inventory_id": "",
                "tags": [...
                ],
                "deal_ids": [],
                "official_store_id": null,
                "original_price": null,
                "shipping": {
                  ...
                },
                "seller_address": {
                ...
                },
                "sale_terms": [
                  ...
                ]
            },
            {...
            },
            {...
            },
            {...
            },
            {...
            },
            {...
            },
            {...
            },
            {...
            },
            {...
            },
            {...
            },
            {...
            },
            {...
            },
            {...
            },
            {...
            },
            {...
            },
            {...
            },
            {...
            },
            {...
            },
            {...
            }
        ],
        "experiments": null
    }

    Ten en cuenta que “results” devolverá todas las publicaciones en la página de producto que están compitiendo para ganar ese producto.


    Usar filtros

    Puedes utilizar filtros para acotar la respuesta dentro del recurso “/products/$PRODUCT_ID/items” este 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 Muestra unicamente productos ganadores de Tiendas Oficiales.
    official_store_id id Muestra los productos ganadores de una Tienda Oficial.
    discount 10-100 Muestra productos ganadores con un descuento mayor o igual al 10%.
    price 100-200 Muestra productos ganadores donde su precio esté entre 100 y 200, dependiendo de la currency local.
    shipping fulfillment Muestra productos ganadores con logística fulfillment.
    shipping mercadoenvios Muestra productos ganadores sin logística fulfillment.
    shipping_cost free Muestra 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 Muestra productos por user_id.

    Ejemplo de llamada usando filtros:

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

    Siguiente: Destaque especial en catálogo.