Competencia en catálogo
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=v2Ejemplo 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=v2Respuesta 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=v2Respuesta 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:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/MLA1150170600/price_to_win?siteId=MLA&version=v2Respuesta 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_TOKENRespuesta 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:
- 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.
- same_day_shipping: Envíos en el día con Mercado Envíos.
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/itemsEjemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/products/MLA18494233/itemsRespuesta 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=freeSiguiente: Destaque especial en catálogo.