Recursos Cross
Explora los recursos principales de nuestras APIs
Documentación
Puedes usar esta documentación para las siguientes unidades de negocio:
Competencia
Notificaciones por cambio de estado
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.
Detalle de la competencia
Con este recurso puedes obtener toda la información sobre el detalle del 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.
Cuando una publicación está con estado de listada significa que no puede ganar dentro de catálogo porque incumple con ciertas razones que impiden que compita pero, sigue siendo una publicación que un comprador puede adquirir y visualizar desde el buscador principal de Mercado Libre.
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/MLA1234567/price_to_win?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/MLA765432/price_to_win?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/MLA9876543/price_to_win?version=v2Respuesta con status: sharing_first_place:
{
"item_id": "MLA9876543",
"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": "MLA15934914",
"winner": {
"item_id": "MLA765432",
"price": 48150,
"currency_id": "ARS",
"boosts": [
{
"id": "fulfillment",
"status": "opportunity",
"description": "Mercado Envíos Full"
},
{
"id": "free_installments",
"status": "opportunity",
"description": "Cuotas al mismo precio que publicaste"
},
{
"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"
}
]
}
}Ejemplo de llamada para una publicación que no está compitiendo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/MLA456789/price_to_win?version=v2Respuesta con status: listed:
{
"item_id": "MLA456789",
"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": "MLA15934914",
"winner": {
"item_id": "MLA765432",
"price": 48150,
"currency_id": "ARS",
"boosts": [
{
"id": "fulfillment",
"status": "opportunity",
"description": "Mercado Envíos Full"
},
{
"id": "free_installments",
"status": "opportunity",
"description": "Cuotas al mismo precio que publicaste"
},
{
"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"
}
]
}
}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, permitiendo identificar el motivo por el cual no lo está haciendo y así realizar acciones de mejora.
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.
Razones
Existen diferentes razones por las que una publicación no se encuentra compitiendo dentro de catálogo, a continuación listamos todos los posibles motivos que responderá el endpoint de price_to_win en el atributo reason, que te permitirá realizar las diferentes acciones para mejorar tu publicación e ingresarla a la competencia.
| 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. |
| shipping_mode | Únicamente disponible para MLB. El vendedor no está compitiendo porque su método de envío es inferior al del ganador. ME2 > ME1 > Custom Shipping > Not Specified. |
Publicación ganadora
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: Brand Central.