Documentación Mercado Libre

Descubre toda la información que debes conocer sobre las APIs de Mercado Libre.
circulos azuis em degrade

Documentación

Última actualización 24/08/2023

Gestionar promociones

Importante:
A partir del 15 de agosto de 2023 eliminaremos la versión anterior de los recursos, para obtener la respuesta con la nueva versión envía el query param app_version=v2. Consulta la documentación de cada campaña para estar al tanto de los cambios.

Con el recurso /seller-promotions puedes centralizar todos los tipos de promociones disponibles como campañas tradicionales (DEAL),campañas co-fondeadas por Mercado Libre (MARKETPLACE CAMPAIGN), descuentos individuales (PRICE DISCOUNT), ofertas relámpago (LIGHTNING), ofertas del día (DOD), descuento por volumen (VOLUME), descuento pre-acordado por item (PRE NEGOTIATED), campaña del vendedor (SELLER_CAMPAIGN) y campaña smart (SMART). Además de los nuevos tipos de ofertas que disponibilicemos.




Características de las promociones

Tipo de campaña Nombre Definición de precio Sugerencia de precio Bonificación MELI Stock para participar Deadline Aprobación
Tradiconal DEAL Usuario define No No No
Co-fondeada MARKETPLACE CAMPAIGN Usuario acepta No No No
Descuento por volumen VOLUME Usuario acepta No No No
Oferta del día DOD Usuario define No Sí, informativo No No
Oferta relámpago LIGHTNING Usuario define No Sí, mandatorio No No
Descuento pre-acordado por ítem PRE_NEGOTIATED Usuario acuerda y acepta No No
Campaña del vendedor SELLER CAMPAIGN Usuario define y acepta No No No No
Campaña Smart SMART Usuario acepta No No No


Disponibilidad por país

Sitio Campañas tradicionales
(DEAL)
Campaña co-fondeada
(MARKETPLACE CAMPAIGN)
Descuento individual
(PRICE DISCOUNT)
Descuento por volumen
(VOLUME)
Descuento pre-acordado por ítem
(PRE_NEGOTIATED)
Oferta del día
(DOD)
Oferta relámpago
(LIGHTNING)
MLA, MLB, MLM, MCO, MLC, MLU, MPE
MLV

Promociones del vendedor

Recuerda que un usuario puede tener más de una invitación y de diferentes tipos.

Llamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/users/$USER_ID?app_version=v2

Ejemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/users/1356551933?app_version=v2

Respuesta:

{
      "results": [
          {
              "id": "P-MLB1806015",
              "type": "MARKETPLACE_CAMPAIGN",
              "status": "started",
              "start_date": "2023-04-20T02:00:00Z",
              "finish_date": "2023-08-01T02:00:00Z",
              "deadline_date": "2023-08-01T01:00:00Z",
              "name": "Campanha de teste v2",
              "benefits": {
                  "type": "REBATE",
                  "meli_percent": 5,
                  "seller_percent": 25
              }
          },
          {
              "id": "P-MLB1806017",
              "type": "VOLUME",
              "status": "started",
              "start_date": "2023-04-20T03:00:00Z",
              "finish_date": "2023-08-01T02:00:00Z",
              "deadline_date": "2023-08-01T01:00:00Z",
              "name": "Leva 3 paga 2",
              "benefits": {
                  "type": "VOLUME",
                  "meli_percent": 9.9999,
                  "seller_percent": 23.3331,
                  "name": "3x2",
                  "buy_quantity": 3,
                  "pay_quantity": 2,
                  "item_discount_percent": 33.333
              }
          },
          {
              "id": "P-MLB1806019",
              "type": "DEAL",
              "status": "started",
              "start_date": "2023-04-20T03:00:00Z",
              "finish_date": "2023-08-01T02:00:00Z",
              "deadline_date": "2023-08-01T01:00:00Z",
              "name": "deals de teste v2"
          },
          {
              "id": "P-MLB1809008",
              "type": "DEAL",
              "status": "started",
              "start_date": "2023-04-21T21:00:00Z",
              "finish_date": "2023-08-01T02:00:00Z",
              "deadline_date": "2023-08-01T01:00:00Z",
              "name": "Deals de test v2"
          },
          {
              "id": "P-MLB1809009",
              "type": "DEAL",
              "status": "started",
              "start_date": "2023-04-21T23:00:00Z",
              "finish_date": "2023-08-01T02:00:00Z",
              "deadline_date": "2023-08-01T01:00:00Z",
              "name": "campanha de teste"
          }
      ],
      "paging": {
          "offset": 0,
          "limit": 50,
          "total": 5
      }
   }

Campos de la respuesta

id: código de identificación de la oferta.
type: tipo de la oferta (DEAL, MARKETPLACE_CAMPAIGN, DOD, LIGHTNING, VOLUME, PRE NEGOTIATED, SELLER_CAMPAIGN, SMART).
status: Estado
start_date: fecha de inicio de la oferta.
finish_date: fecha de fin de la oferta.
deadline_date: plazo máximo para aceptar la invitación.
name: nombre de la promoción.
deadline_date: plazo máximo para incorporar los ítems a la promoción.
benefits: configuración de beneficios de la promoción.


Consultar items candidatos

El recurso /seller-promotions/candidates permite identificar los ítems invitados a participar de una promoción. Siempre que un ítem obtiene el status de candidate en una promoción se envía una notificación con el candidate_id, con este recurso es posible identificar el ítem, la promoción y el status.

Llamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'  https://api.mercadolibre.com/seller-promotions/candidates/$CANDIDATE_ID?app_version=v2

Ejemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN'  https://api.mercadolibre.com/seller-promotions/candidates/CANDIDATE- MLB1254949426-803130663?app_version=v2

Respuesta:

{    
    "id": "CANDIDATE-MLB1254949426-803130663",    
    "item_id": "MLB1254949426",    
    "promotion_id": "P-MLB4629001",    
    "type": "MARKETPLACE_CAMPAIGN",    
    "status": {        
    "id": "candidate"    
  } 
}

Campos de respuesta

id: código de identificación del candidato.

item_id: ítem asociado al candidato.

promotion_id: id de la promoción.

type: tipo de promoción (DEAL, MARKETPLACE_CAMPAIGN, DOD, LIGHTNING, VOLUME, PRICE DISCOUNT, PRE_NEGOTIATED, SELLER_CAMPAIGN, SMART).

status: estado del candidato.


Nota:
El id del candidato se obtiene a través de la notificación del topic public candidate.

Consultar ofertas

El recurso /seller-promotions/offers permite identificar cambios en la oferta de un ítem. Todos los cambios se envían por medio de notificaciones con el offer_id, es posible identificar el item, la promoción y el estado.

Llamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/offers/$OFFERS_ID?app_version=v2

Ejemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/offers/OFFER-MLB1970246686-42701792?app_version=v2

Respuesta:

{    
    "id": "OFFER-MLB1970246686-42701792",    
    "item_id": "MLB1970246686",    
    "promotion_id": "P-MLB3329001",    
    "type": "DEAL",    
    "status": {        
    "id": "ACTIVE"    
  } 
}

Campos de la respuesta

id: código de identificación de la oferta.
item_id: ítem asociado a la oferta.
promotion_id: id de la promoción.
type: tipo de promoción (DEAL, MARKETPLACE_CAMPAIGN, DOD, LIGHTNING, VOLUME, PRICE DISCOUNT, PRE_NEGOTIATED, SELLER_CAMPAIGN, SMART).
status: estado de la oferta. (programmed, active, e inactive).

Nota:
El id de la oferta lo obtienes por medio de una notificación del tópico public offers.

Consultar detalles de la promoción

Realiza la siguiente consulta para acceder a los detalles particulares de una campaña tradicional, campaña co-fondeada y para los descuentos por volumen.

Llamada:

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

Para obtener más información, acceda a las documentaciones de cada campaña.


Estado

A continuación puedes encontrar los posibles estados que pueden tener los distintos tipos de promociones:


Consultar ítems de la promoción

Nota:
En esta consulta se obtiene el estado del ítem en la campaña.

Para conocer los ítems que forman parte de una determinada oferta puedes realizar la siguiente consulta:

Llamada:

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

Además, puedes consultar ítems de una campaña:


Filtros

Puedes aplicar filtros por ítem o status.


Llamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/promotions/$PROMOTION_ID/items?promotion_type=$PROMOTION_TYPE&status=$STATUS&item_id=$ITEM_ID&app_version=v2

Ejemplo de filtro por ítem:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/seller-promotions/promotions/MLA1111/items?promotion_type=DEAL&item_id=MLA604400000&app_version=v2

Respuesta:

 {
   "results": [
       {
           "id": "MLA604400000",
           "status": "started",
           "price": 23968,
           "original_price": 28549
       }
   ],
   "paging": {...}
}

Ejemplo de filtro por status started:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' /seller-promotions/promotions/MLA1111/items?promotion_type=DEAL&status=started&app_version=v2

Respuesta:

  {
   "results": [
       {
            "id": "MLA639970000",
            "status": "started",
            "price": 4037,
            "original_price": 4427
        },
        {
            "id": "MLA639973333",
            "status": "started",
            "price": 6007,
            "original_price": 6587
        },
],
   "paging": [...]
}
Nota:
Los status que se pueden filtrar son: started, finished, pending y candidate.

Paginación

Para realizar la paginación deberás utilizar el parámetro searchAfter. El valor enviado en este parámetro es siempre el último id del ítem retornado en la llamada anterior.


Nota:
Si no utilizas el parámetro de limit, se retornarán por defecto 50 ítems del total. Puedes agregar un limit máximo de 50.

Llamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' 'https://api.mercadolibre.com/seller-promotions/promotions/$PROMOTIONS_ID/items?promotion_type=$PROMOTION_TYPE&searchAfter=$ITEM_ID&app_version=v2'

Ejemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' 'https://api.mercadolibre.com/seller-promotions/promotions/MLB9377/items?promotion_type=DEAL&searchAfter=MLB2674512267&app_version=v2'

Respuesta:

"results": [
       {
           "id": "MLB2674512266",
           "status": "candidate",
           "price": 0,
           "original_price": 0
       },
       {
           "id": "MLB2674506199",
           "status": "candidate",
           "price": 0,
           "original_price": 0
       },
       {
           "id": "MLB2674506138",
           "status": "candidate",
           "price": 0,
           "original_price": 0
       },
       {
           "id": "MLB2674505931",
           "status": "candidate",
           "price": 0,
           "original_price": 0
       },
       {
           "id": "MLB2674505924",
           "status": "candidate",
           "price": 0,
           "original_price": 0
 
 […]
 
 "paging": {
       "searchAfter": "MLB2674512267",
       "limit": 50,
       "total": 14424
   }
}


Cómo participar

Puedes participar en distintos tipos de promociones e incluso ofrecer un descuento individual para los ítems:

Consultar promociones del ítem

Aca puede obtener todas las promociones que tiene el item y los status de las promociones en el momento de la consulta.

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

Ejemplo:

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

Respuesta:

[
      {
          "type": "PRICE_DISCOUNT",
          "status": "candidate",
          "price": 4000,
          "start_date": "2023-04-26T00:00:00",
          "finish_date": "2023-05-10T00:00:00"
      },
      {
          "type": "DOD",
          "status": "candidate",
          "price": 4000,
          "start_date": "2023-04-28T00:00:00",
          "finish_date": "2023-04-28T23:59:59"
      },
      {
          "id": "P-MLB1817004",
          "type": "MARKETPLACE_CAMPAIGN",
          "status": "pending",
          "start_date": "2023-04-27T23:00:00Z",
          "finish_date": "2023-06-01T02:00:00Z",
          "deadline_date": "2023-06-01T01:00:00Z",
          "name": "Campanha teste 10",
          "benefits": {
              "type": "REBATE",
              "meli_percent": 3,
              "seller_percent": 27
          }
      },
      {
          "id": "MLB1345",
          "type": "DEAL",
          "status": "pending",
          "start_date": "2023-04-27T23:00:00-03:00",
          "finish_date": "2023-05-31T23:00:00-03:00",
          "name": "teste 20"
      },
      {
          "id": "C-MLB300",
          "type": "SELLER_CAMPAIGN",
          "sub_type": "FIXED_PERCENTAGE",
          "status": "started",
          "price": 4250,
          "top_price": 3500,
          "start_date": "2023-04-27T00:00:00",
          "finish_date": "2023-05-05T23:59:59",
          "name": "camp del seller 1"
      },
      {
          "id": "P-MLB1812010",
          "type": "SMART",
          "status": "started",
          "name": "test-smart-2",
          "offers": [
              {
                  "id": "OFFER-MLB3538191898-177685",
                  "original_price": 5000,
                  "new_price": 3000,
                  "prime_price": null,
                  "status": "active",
                  "start_date": "2023-04-26T11:40:00Z",
                  "end_date": "2023-05-30T15:47:00Z",
                  "benefits": {
                      "type": "REBATE",
                      "meli_percent": 20,
                      "seller_percent": 20
                  }
              }
          ]
      },
      {
          "id": "C-MLB302",
          "type": "SELLER_CAMPAIGN",
          "sub_type": "FLEXIBLE_PERCENTAGE",
          "status": "candidate",
          "start_date": "2023-04-27T12:04:00",
          "finish_date": "2023-05-05T00:00:00",
          "name": "camp del seller 2"
      }
   ]  

Modificar ítems

Puedes modificar los ítems que están participando en una determinada oferta:

Nota:
Para editar los descuentos individuales (PRICE DISCOUNT), las ofertas del día (DOD) y las ofertas relámpago (LIGHTNING) debes eliminar la promoción y aplicarla nuevamente.


Eliminar ítems

Puedes eliminar los ítems que están participando en una determinada oferta:


Asignar campañas de pruebas

Para realizar pruebas con campañas de test, envíanos los datos de tu usuario y/o ítems en el soporte por site.


Recuerda que tanto los usuarios como los ítems deben ser de test.


Nota:
Debes agregar el parámetro version=test dentro de las llamadas para interactuar con las promociones de test.

Next post: Campañas co-fondeadas