Concorrência no catálogo

Receba notificações de posts que mudam de status na competição

Você pode se inscrever no tópico item competition para começar a receber notificações sobre a mudança de status dos itens do catálogo. Ele permite identificar as modificações no status de competição para vencedor ou vice-versa.

Para visualizar as informações da concorrência e revisar as condições com as que o vendedor está competindo para ganhar a página de produto, deve utilizar o recurso /price_to_win e entender que ações deve tomar.

Saiba mais sobre como receber notificações.

Como conhecer o preço para ganhar

As publicações de catálogo concorrem para obter as vendas da página de produto e existe um algoritmo que determina quem será o vencedor nessas vendas, baseado nas características da publicação e do vendedor.
O algoritmo que avalia qual será a publicação vencedora considera principalmente:

preço da publicação
parcelas sem juros
envio full, envio grátis, envio no dia

Notas:

- Algumas dessas características podem aplicar somente a alguns compradores (exemplo: envio no dia ou desconto de Mercado Pontos). Nesses casos, fazemos o melhor esforço por escolher um vencedor considerando o comprador particular, levando em consideração que características são aplicáveis a ele.
- Pelo dito acima, apesar de que falemos de “vencedor” de forma unívoca, eventualmente o vendedor poderia estar vencendo em geral, mas não em particular, para certos usuários (ex.: se morarem muito longe e não obteriam nunca o envio no dia).

Para que os vendedores possam concorrer eficientemente, oferecemos um recurso que indica o estado em que está a publicação de catálogo, isso pode variar, pois uma publicação pode ser vencedora, competitiva ou listada. O último estado tem os motivos pelos quais a publicação não concorre.

Chamada:

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

Exemplo de item concorrente:

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

Resposta:

"item_id": "MLA123456789",
    "current_price": 21499.0,
    "currency_id": "ARS",
    "price_to_win": 17600.0,
    "boosts": {
        "fulfillment": false,
        "free_installments": false,
        "free_shipping": true,
        "same_day_shipping": false
    },
    "status": "competing",
    "reason": [],
    "catalog_product_id": "MLA9652755"
}

Exemplo de item vencedor:

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

Resposta:

{
    "item_id": "MLA123456710",
    "current_price": 20499.0,
    "currency_id": "ARS",
    "price_to_win": 20499.0,
    "boosts": {
        "fulfillment": false,
        "free_installments": true,
        "free_shipping": true,
        "same_day_shipping": false
    },
    "status": "winning",
    "reason": [],
    "catalog_product_id": "MLA9652755"
}

Exemplo de item que não concorre:

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

Resposta:

{
    "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",
    "reason": [
        "item_paused"
    ]

Como ler a resposta:

O campo status indica se estamos ganhando para o público geral (poderíamos estar ganhando para segmentos minoritários com os que não aproveitam o envio no dia). Quando estamos ganhando, o valor é winning, quando não estamos ganhando, é competing.
O campo boosts indica quais características da nossa publicação estão aportando para as chances de ganhar. As possibilidades são:
- same_day_shipping: Envios no dia pelo Mercado Envíos.
- fulfillment: Mercado Envios Full.
- free_installments: Parcelamento sem juros.
- free_shipping: Envio sem custo pelo Mercado Envios.
- shipping_quarantine: Envios com normalidade.
- shipping_collect: Mercado Envios coleta.
O campo price_to_win indica qual é o preço (na moeda atual da publicação) para ser o ganhador. Isto é que, fazendo um PUT ao recurso /itens com o preço sugerido, você garante ser o ganhador.

O campo reason mostrará informações quando o item não estiver competindo, podendo identificar o motivo pelo qual ele não está fazendo isso.

Valores possíveis para reason

Reason	Descrição
non_trusted_seller	O vendedor não está na lista de permissões de fraude. Não pode competir. Ele aparece nas listagens em segundo plano.
reputation_below_threshold	O vendedor não atinge a reputação mínima para ganhar. Não pode competir. Aparece apenas nas listagens.
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	O item possui manufacturing time, aparece apenas nas listagens e não pode vencer porque o vencedor possui estoque imediato.
temporarily_winning_manufacturing_time	O item possui manufacturing time, está ganhando temporariamente porque não há concorrentes no mesmo nível de reputação sem MF.
temporarily_competing_manufacturing_time	O item tiene manufacturing time, esta compitiendo temporalmente porque no hay competidores en el mismo nivel de reputación sin MF, el winner también tiene MF.
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 é a melhor reputação disponível, está competindo temporariamente. O vencedor também é da mesma reputação. Se um best-seller aparecer, ele será listado apenas novamente.
item_paused	O item está em pausa, não pode ser listado.
item_not_opted_in	O item não fiz opt in, não pode ser listado ou é um item de teste.

Neste chamado, você deverá utilizar um item_id de uma publicação de catálogo, no caso de não poder fazê-lo, você obterá um código de erro 4XX.
Além disso, existem variáveis como a reputação, que são utilizadas para determinar o ganhador. Contudo, para um bom vendedor, as variáveis acima serão as utilizadas para determinar o ganhador.
Importante: em breve disponibilizaremos um recurso para receber notificações quando o vendedor se transforme em ganhador de um produto.

Conheça as condições e o preço do item vencedor

A tabela de competição permitirá que os vendedores comparem e melhorem as condições do item. Com a nova versão do recurso price_to_win, você pode adicionar via API uma tabela de competição para comparar as condições de um item que está competindo e as do vencedor. Com essa funcionalidade em seu desenvolvimento, os vendedores terão conhecimento de quais condições melhorar para ganhar a página do produto.

Chamada:

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

Exemplo:

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

Resposta:

{
    "item_id": "MLA848886211",
    "current_price": 85990,
    "currency_id": "ARS",
    "price_to_win": 65200,
    "boosts": [
        {
            "id": "same_day_shipping",
            "status": "opportunity",
            "description": "Envíos en el dia 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_boosted",
            "description": "Envíos gratis por Mercado Envíos"
        },
        {
            "id": "shipping_quarantine",
            "status": "boosted",
            "description": "Envío con normalidad"
        },
        {
            "id": "shipping_collect",
            "status": "boosted",
            "description": "Mercado Envíos Colecta"
        }
    ],
    "status": "competing",
    "reason": [],
    "catalog_product_id": "MLA14186099",
    "winner": {
        "item_id": "MLA849174940",
        "price": 76999,
        "currency_id": "ARS",
        "boosts": [
            {
                "id": "same_day_shipping",
                "status": "not_apply",
                "description": "Envíos en el dia por Mercado Envíos"
            },
            {
                "id": "fulfillment",
                "status": "boosted",
                "description": "Mercado Envíos Full"
            },
            {
                "id": "free_installments",
                "status": "boosted",
                "description": "Cuotas sin interés"
            },
            {
                "id": "free_shipping",
                "status": "not_boosted",
                "description": "Envíos gratis por Mercado Envíos"
            },
            {
                "id": "shipping_quarantine",
                "status": "boosted",
                "description": "Envío con normalidad"
            },
            {
                "id": "shipping_collect",
                "status": "opportunity",
                "description": "Mercado Envíos Colecta"
            }
        ]
    }
}

Na nova versão do recurso, além dos campos já conhecidos na versão anterior, adicionamos as informações do item que estamos consultando e as do item que está ganhando (caso o item consultado esteja competindo).

Portanto, primeiro visualizamos o preço e as condições de venda listadas nos boosts, com um status e uma explicação, permitindo comparar rapidamente com a segunda lista que se refere à publicação que está ganhando a página do produto.

Os boosts são aqueles já mencionados nos campos de resposta da versão anterior. Agora, você pode reconhecer o status deles no boost e desenhar uma tabela comparativa de acordo.

Estado dos boost	Detalhe
boosted	tem a condição de venda e atualmente aplica o aumento.
not_boosted	possui 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 vendas não se aplica como um boost ao produto em que o item concorre.

Nota:

Lembre-se de que essas informações permitem comparar rapidamente com a segunda listagem sobre a publicação do item que está ganhando a página do produto.

Conheça a publicação que está ganhando um produto

Usando o recurso de /products/{product_id} , além de conhecer as características e o status do produto, você pode reconhecer a publicação que está ganhando a página do produto com o campo buy_box_winner.

Como conhecer a relação de publicações para um produto

Se você precisar conhecer quais são os itens (de todos os vendedores) que concorrem pelas vendas de um produto em particular, tem um recurso que entrega a você essas informações.

Chamada:

curl -X GET https://api.mercadolibre.com/products/{product_id}/items

Exemplo:

curl -X GET https://api.mercadolibre.com/products/MLB6309815/items

Resposta 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,
      "installments": {
        "quantity": 1,
        "amount": 13999,
        "rate": 0,
        "currency_id": "ARS"
      },
      "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": [
        "brand_verified",
        "extended_warranty_eligible",
        "good_quality_picture",
        "good_quality_thumbnail",
        "immediate_payment",
        "cart_eligible"
      ],
      "tier": ""
    },
    {},
    {},
    {},
    {},
    {},
    {}
  ]
}

Tenha em conta que em "results" terá os itens que estão competindo para ganhar esse produto.

Filtro

O filtro funcionará da mesma forma que no recurso de Search (/sites/{site}/search) onde utilizar os valores de available_filters como parâmetro na URI é possível.

Atualmente, você tem as seguintes opções de filtragem:

Parâmetros	Valor	Descrição
official_store	all	Para mostrar apenas produtos com vencedor de Lojas Oficiais.
official_store_id	id	Para mostrar os produtos vencedores de uma loja oficial.
discount	10-100	Para mostrar os produtos vencedores com desconto maior ou igual a 10%.
price	100-200	Para produtos vencedores com preço entre 100 e 200. 100 para produtos com vencedor com preço maior ou igual a 100. 200 para produtos com vencedor com preço menor ou igual a 200.
installments	no_interest	Para produtos com vencedor com parcelamentos sem juros.
shipping	fulfillment	Para produtos com vencedor com FBM.
shipping	mercadoenvios	Para produtos com vencedor sem FBM.
shipping_cost	free	Para produtos con vencedor com frete grátis.
shipping_time	sameday/ nextday	Deve ser usado junto com a query param b.buyer_zones, que indica em quais áreas o comprador está localizado.
seller_id	id	Obter o vencedor user_id

Exemplo:

curl -X GET https://api.mercadolibre.com/products/MLB6309815/items?shipping=free