Recursos Cross

Confira os principais recursos das nossas APIs
circulos azuis em degrade

Documentação

Você pode usar esta documentação para as seguintes unidades de negócio:

Última atualização em 22/01/2024

Competição

No catálogo, as publicações competem para obter as vendas da página do produto e um algoritmo determina quem será o vencedor dessas vendas com base nas características da publicação e do próprio vendedor, como preço da publicação, parcelamento sem juros, Envio full, grátis ou no mesmo dia.

Notificação por mudança no status

Com o tópico Item competition poderá assinar e começar a receber notificações sobre a mudança de estado das publicações de catálogo, isso permitirá identificar a publicação que modifica o estado de competição a ganhador ou vice-versa.


Detalhe da concorrência

Com este recurso, poderá obter toda a informação sobre o detalhe do estado da publicação de um vendedor no catálogo: que pode estar ganhando, compartilhando o primeiro lugar, perdendo ou listada.


Quando uma publicação está com estado de listada, significa que não pode ganhar dentro do catálogo porque não cumpre com alguns motivos que a impedem de competir, mas continua sendo uma publicação que um comprador pode adquirir e visualizar pelo buscador principal do Mercado Livre.


Chamada:

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

Exemplo de chamada para uma publicação que está perdendo na competição:

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

Resposta com status: competing:

{
   "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"
           }
       ]
   }
}

Exemplo de chamada para uma publicação que está ganhando na competição:


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

Resposta com 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"
           }
       ]
   }
}

Exemplo de chamada para uma publicação que está compartilhando o primeiro lugar na competição:

Nota:
O status:sharing_first_place identifica todos os vendedores que, conforme as condições da oferta, atualmente compartilham o primeiro lugar como ganhador.

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

Resposta com 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"
           }
       ]
   }
}

Exemplo de chamada para uma publicação que não está competindo:

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

Resposta:

{
   "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"
           }
       ]
   }
}

Exemplo de chamada para uma publicação que não está competindo:


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

Resposta com 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 da resposta

price_to_win: indica o preço (na moeda atual da publicação) para ser o ganhador. Isto é, fazendo um PUT ao recurso /items com o preço sugerido a publicação ganhará na página de produto.
boosts: indica as características da publicação que proporcionam chances de ganhar, tais como:

Identifique dentro do campo boost o estado conforme corresponda:

Estado dos boost Detalhe
boosted Tem a condição de venda e atualmente aplica o boost.
not_boosted Tem a condição de venda, mas não é um boost que aumenta as chances de ganhar.
opportunity Não possui condição de venda. Caso aplique, melhoraria as chances de ganhar.
not_apply A condição de venda não se aplica como um boost ao produto em que o item compete.

status: indica se o produto está ganhando para o público ou para segmentos minoritários, por exemplo, aqueles que não aproveitam o frete no mesmo dia. Quando está ganhando, o valor é winning, caso contrário será competing e indica que está perdendo, adicionalmente, o valor sharing_first_place para quando o primeiro lugar é compartilhado com outras publicações na página de produtos.

visit_share:: indica o nível de visibilidade que a sua publicação tem no catálogo. Estes valores podem variar dependendo do estado.

  • Winning: sempre será o maximum.
  • Competing: sempre será minimum.
  • Sharing_first_place: nsempre será medium.

competitors_sharing_first_place: indica a quantidade de vendedores que compartilham o primeiro lugar. Dependerá também do estado das publicações.

  • Winning: sempre será 0, já que ao ser ganhador levará todas as vendas e visibilidade no catálogo.
  • Competing: sempre será null, já que ao perder terá que melhorar as condições para compartilhar o primeiro lugar ou ganhar.
  • Listed: sempre será null, já que ao perder terá que melhorar as condições para compartilhar o primeiro lugar ou ganhar.
  • Sharing_first_place: mostrará o valor de vendedores que se encontram competindo pelo primeiro lugar.

reason: mostrará informação apenas quando a publicação não estiver competindo, permitindo identificar o motivo peloqual não está na competição e assim realizar ações de melhora.


catalog_product_id: indica o ID da página de produto a qual pertence à publicação.


winner: indica o detalhe dol produto que está atualmente como ganhador, permitindo realizar uma comparação rápida, com o item_id daa publicação que está consultando, mostrando campos como: item_id, price, currency_id e boosts.



Motivos

Existem diferentes motivos pelos quais uma publicação não está competindo dentro do catálogo, a seguir listamos todos os possíveis motivos que responderá o endpoint de price_to_win no atributo reason, que permitirá realizar diferentes ações para melhorar a sua publicação para que ela entre na competição.

Reason Descrição
non_trusted_seller O vendedor não pode competir porque está marcado como vendedor não confiável. Aparece no fim da lista.
reputation_below_threshold O vendedor não pode competir porque não alcança a reputação necessária para ganhar. Aparece na lista.
winner_has_better_reputation O vendedor tem uma reputação que pode competir, mas há um vencedor com uma reputação melhor. No momento, ele aparece apenas nas listagens (caixa amarela com vencedor verde).
manufacturing_time A publicação tem manufacturing time, aparece apenas na lista e não pode ganhar porque o ganhador tem estoque imediato.
temporarily_winning_manufacturing_time A publicação tem manufacturing time, está ganhando temporariamente porque não há competidores no mesmo nível de reputação sem manufacturing time.
temporarily_competing_manufacturing_time A publicação tem manufacturing time, está competindo temporariamente porque não há competidores no mesmo nível de reputação sem manufacturing time, o ganhador também tem manufacturing time.
temporarily_winning_best_reputation_available O vendedor não é verde, mas tem uma reputação que pode ganhar e é a melhor oferta disponível. Ele está ganhando temporariamente. Se uma oferta melhor aparecer, pare de ganhar.
temporarily_competing_best_reputation_available O vendedor não é verde, mas tem a melhor reputação disponível, está competindo temporariamente. O ganhador também é da mesma reputação. Se aparecer um vendedor melhor, voltará a estar apenas na lista.
item_paused O item está em pausado, não pode aparecer na lista.
item_not_opted_in Não foi feito optin da publicação, não pode aparecer na lista, foi usada a chamada item_id de uma publicação que não é de catálogo ou é um item test por isso não pode entrar na competição.
shipping_mode Disponível apenas para MLB.O vendedor não está competindo porque seu método de envio é inferior ao do ganhador. ME2 > ME1 > Custom Shipping > Not Specified.


Publicação ganhadora

Usando o recurso de /products/{product_id}, além de conhecer as características e estado do produto, poderá reconhecer pelo campo buy_box_winner a publicação que está ganhando na página de produto.


Exemplo de resposta curta do detalhe de uma página de produto:

{
    "id": "MLM12345",
    "status": "active",
    "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",
        "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",
    "date_created": "2021-09-27T18:13:54Z"
}

Lista de publicações PDP

Se precisar identificar quais são as publicações de catálogo (de todos os vendedores) que competem pelas vendas de uma página de produto em particular, realize a seguinte chamada:

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

Exemplo:

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

Resposta simples:

{
    "paging": {
        "total": 41,
        "offset": 0,
        "limit": 100
    },
    "results": [
        {
            "item_id": "MLA1110011006",
            "site_id": "MLA",
            "seller_id": 1234567,
            "accepts_mercadopago": true,
            "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,
            "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
}

Considere que results devolverá todas as publicações na página de produto que estão competindo para ganhar esse produto.


Usar filtros

Utilize filtros para diminuir a resposta no recurso /products/$PRODUCT_ID/items Este filtro funciona igual ao recurso de Search /sites/{site}/search onde é possível utilizar os valores de available_filters como parâmetro na URL.
Atualmente oferecemos as seguintes opções de filtros:

Parâmetro Valor Descrição
official_store all Mostra apenas produtos ganhadores de lojas oficiais.
official_store_id id Mostra os produtos ganhadores de uma loja oficial.
discount 10-100 Mostra os produtos ganhadores com desconto maior ou igual a 10%.
price 100-200 Mostra os produtos ganhadores com preço entre 100 e 200 dependendo da currency local.
shipping fulfillment Mostra produtos ganhadores com fulfillment.
shipping mercadoenvios Mostra produtos ganhadores sem fulfillment.
shipping_cost free Mostra produtos ganhadorescom frete grátis.
shipping_time sameday/ nextday Deve ser usado com a query param b.buyer_zones, que indica em quais áreas o comprador está localizado.
seller_id id Mostra produtos por user_id

Exemplo de chamada usado filtros:


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

Próxima: Brand Central.