Documentação do Mercado Livre

Confira todas as informações necessárias sobre as APIs Mercado Livre.
circulos azuis em degrade

Documentação

Última atualização em 08/02/2024

Campanhas com co-participação e campanha de preços competitivos

Importante:
- A partir de 10 de janeiro de 2024 eliminaremos a versão anterior do recurso /seller-promotions.
- Para obter a resposta com a nova versão, envie a query param app_version=v2. Consulte a documentação de cada campanha para conhecer as mudanças.
- Alteramos o nome de "campanha Smart" a "campanha com co-participação automatizada", mas não alteramos nada na API e continua tendo o "type" smart.
- Estas campanhas estão na mesma documentação porque trabalham com a mesma lógica e os mesmos parâmetros.

Os vendedores são convidados periodicamente a participar de diferentes campanhas realizadas no site. Nestes tipos de campanhas, o Mercado Livre paga uma porcentagem do desconto oferecido.
As campanhas com co-participação automatizada são similares às com co-participação já existentes, mas já utilizam um processo automatizado para definir os itens que serão convidados a participar do desconto. Já as campanhas de preços competitivos buscam alcançar os melhores preços frente a outros sites web e marketplaces, e os candidatos regeneram todos os dias, com isto um item pode ser candidato a este tipo de campanha hoje e amanhã não.
Se o vendedor recebeu um convite e quer participar, você pode fazer isso com os seguintes recursos.



Consultar detalhes da campanha

Nota:
Para ambas campanhas as respostas têm os mesmos campos, mudando apenas a informação de "type" (SMART ou PRICE_MATCHING).
Para a campanha com co-participação automatizada (SMART), já não enviamos a informação de sub_type.

Para obter os detalhes de uma promoção do tipo Smart, faça a seguinte consulta:

Exemplo de co-participação automatizada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/promotions/P-MLB1812010?promotion_type=SMART&app_version=v2

Resposta de co-participação automatizada:

{
  "id": "P-MLB1812010",
  "type": "SMART",
  "status": "started",
  "start_date": "2023-04-26T23:00:00Z",
  "finish_date": "2023-05-10T23:59:00Z",
  "deadline_date": "2023-05-10T23:59:00Z",
  "name": "test-smart-2"
}

Exemplo de preços competitivos:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/promotions/P-MLB2087012?promotion_type=PRICE_MATCHING&app_version=v2
  

Resposta de preços competitivos:

{
   "id": "P-MLB2087012",
   "type": "PRICE_MATCHING",
   "status": "pending",
   "start_date": "2023-09-19T18:15:00Z",
   "finish_date": "2023-10-01T05:59:59Z",
   "deadline_date": "2023-10-01T05:59:59Z",
   "name": "Gánale a la competencia con un aporte de Mercado Libre"
}

Campos da resposta

  • id: identificador da campanha.
  • type: tipo de campanha (SMART, PRICE_MATCHING).
  • status: estado da campanha.
  • start_date: data em que começa a campanha.
  • finish_date: data em que termina a campanha.
  • deadline_date: data limite para criar a campanha.
  • name: nome da campanha.


Estados

Estes são os diferentes estados pelos quais as campanhas com co-participação automatizada e as campanhas de preços competitivos podem passar:

Estado Descripción
pending Promoção aprovada, mas ainda não foi iniciada.
started Promoção ativa.
finished Promoção finalizada.


Consultar itens de uma campanha

Para ver os itens que fazem parte de uma campanha, você pode realizar a seguinte consulta:

Exemplo de co-participação automatizada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' 'https://api.mercadolibre.com/seller-promotions/promotions/P-MLB1812010/items?promotion_type=SMART&app_version=v2'

Resposta de co-participação automatizada:

{
  "results": [
      {
          "id": "MLB3538191898",
          "status": "candidate",
          "price": 3000,
          "original_price": 5000,
          "offer_id": "CANDIDATE-MLB3538191898-25593903",
          "meli_percentage": 20,
          "seller_percentage": 20,
          "start_date": "2023-04-26T11:40:00Z",
          "end_date": "2023-05-30T15:47:00Z"
      }
  ],
  "paging": {
      "offset": 0,
      "limit": 50,
      "total": 1
  }
}

Exemplo preços competitivo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' 'https://api.mercadolibre.com/seller-promotions/P-MLB2087012/items?promotion_type=PRICE_MATCHING&app_version=v2'

Resposta de preços competitivos:

{
  "results": [
      {
          "id": "MLB4048719074",
          "status": "candidate",
          "price": 3000,
          "original_price": 5000,
          "offer_id": "CANDIDATE-MLB4048719074-70000001705",
          "meli_percentage": 20,
          "seller_percentage": 20,
          "start_date": "2023-09-19T03:00:00Z",
          "end_date": "2023-09-26T02:59:59Z"
      }
  ],
  "paging": {
      "total": 1,
      "limit": 50
  }
}

Ao criar uma nova campanha, todos os itens elegíveis são selecionados. O estado inicial (status) dos itens é candidate e contam com um offer_id de candidato. No momento em que o vendedor adiciona um item na campanha, seu estado é alterado a started> e o offer_id muda para um id de oferta.



Estado dos-itens

Na tabela a seguir, você encontrará os possíveis estados que um item em campanhas destes tipos podem ter:

Estado Descripción
candidate Item candidato para participar da promoção.
pending Item com promoção aprovada e programada.
started Item ativo na campanha.
finished Item excluído da campanha.


Indicar itens para uma campanha

Nota:
A campanha com co-participação automatizada pode ter uma duração máxima de 30 dias, enquanto a campanha de preços competitivos pode ter até 10 dias.

Após ser convidado a participar destas campanhas, poderá indicar quais produtos quer incluir nas mesmas.

Chamada:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' \
  -d '{
     "promotion_id":"$PROMOTIONDEAL_ID",
     "promotion_type":"$PROMOTION_TYPE",
     "offer_id":"$OFFER_ID"
  }'
  https://api.mercadolibre.com/seller-promotions/items/$ITEM_ID?app_version=v2

Exemplo de co-participação automatizada:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' \
  -d '{
    "promotion_id":"P-MLB1812010",
    "promotion_type":"SMART",
    "offer_id":"CANDIDATE-MLB3538191898-25593903"
  }
  '
  https://api.mercadolibre.com/seller-promotions/items/MLB3538191898?app_version=v2

Resposta de co-participação automatizada:

{
  "offer_id": "OFFER-MLB3538191898-177685",
  "price": 3000,
  "original_price": 5000
}

Exemplo de preços competitivos:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' \
-d '{
   "promotion_id": "P-MLB2087012",
   "offer_id": "CANDIDATE-MLB4048719074-70000001705",
   "promotion_type": "PRICE_MATCHING"
}
'
https://api.mercadolibre.com/seller-promotions/items/MLB4048719074?app_version=v2

Resposta de preços competitivos:

{
  "offer_id": "OFFER-MLB4048719074-10000001972",
  "price": 3000,
  "original_price": 5000
}

Parâmetros

  • promotion_id: identificação da promoção.
  • promotion_type: tipo de promoção (SMART ou PRICE_MATCHING).
  • offer_id: identificação da oferta acordada.

Eliminar campanhas

Chamada:

curl -X DELETE -H 'Authorization: Bearer $ACCESS_TOKEN' 'https://api.mercadolibre.com/seller-promotions/items/$ITEM_ID?promotion_type=$PROMOTION_TYPE&promotiondeal_id=$PROMOTION&offer_id=$OFFER_ID'

Exemplo de co-participação automatizada:

curl -X DELETE -H 'Authorization: Bearer $ACCESS_TOKEN' 'https://api.mercadolibre.com/seller-promotions/items/MLB4048719074?promotion_type=PRICE_MATCHING&promotion_id=P-MLB2087012&offer_id=OFFER-MLB4048719074-10000001972&app_version=v2

Resposta: Status 200 OK

Exemplo de preços competitivos:

curl -X DELETE -H 'Authorization: Bearer $ACCESS_TOKEN' 'https://api.mercadolibre.com/seller-promotions/items/MLB4048719074?promotion_type=PRICE_MATCHING&promotion_id=P-MLB2087012&offer_id=OFFER-MLB4048719074-10000001972&app_version=v2

Resposta: Status 200 OK