Última actualización 04/05/2023

Campañas Smart

Importante:
A partir del 10 de Mayo de 2023 deberá enviar el query param app_version=v2 para obtener la respuesta con la nueva versión de los recursos.
Por ahora las 2 versiones de /seller-promotions convivirán juntas, es decir, habrá retrocompatibilidad por un tiempo, para que pueda actualizar su desarrollo.

Los vendedores son invitados periódicamente a participar de diferentes campañas que se realizan en el sitio. En este tipo de campañas, Mercado Libre paga un porcentaje del descuento ofrecido.
Las campañas Smart son similares a las co-fondeadas, pero ya se utilizan de un proceso automatizado para definir los items candidatos. Si el vendedor recibió una invitación y quiere sumarse, puedes hacerlo con los siguientes recursos.



Consultar detalle de campaña

Para obtener los detalles de una promoción del tipo Smart, realiza la siguiente consulta:

Ejemplo:

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

Respuesta:

{
  "id": "P-MLB1812010",
  "type": "SMART",
  "sub_type": "COFINANCED",
  "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"
}

Campos de la respuesta

  • id: identificador de la campaña.
  • type: tipo de campaña (SMART).
  • sub_type: actualmente trabajamos solo con cofinanced, pero en el futuro podemos tener otros tipos.
  • status: status de la campaña.
  • start_date: fecha que empieza la campaña.
  • finish_date: fecha que se cierra la campaña.
  • deadline_date: fecha límite para crear la campaña.
  • name: nombre de la campaña.


Estados

Estos son los distintos estados por los que puede pasar una campaña Smart.

Estado Descripción
pending Promoción aprobada, pero aún no inició.
started Promoción activa.
finished Promoción finalizada.


Consultar ítems en una campaña

Para conocer los ítems que forman parte de una campaña Smart puedes realizar la siguiente consulta:

Ejemplo:

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

Respuesta:

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

Al crearse una nueva campaña se seleccionan todos los ítems aplicables a la misma. El estado inicial (status) de los ítems es candidate y sin offer id asignado. Al momento que el vendedor incorpora un ítem a la campaña su status se modifica y se le asigna un offer_id único.



Estado de los ítems

En la siguiente tabla puedes encontrar los posibles estados que pueden tomar los ítems dentro de este tipo de campaña.

Estado Descripción
candidate Ítem candidato para participar de la promoción.
pending Ítem con promoción aprobada y programada.
started Ítem activo en la campaña.
finished Ítem eliminado de la campaña


Indicar ítems para una campaña

Una vez que has sido invitado a participar en una campaña Smart, puedes indicar qué productos deseas incluir en la misma.

Llamada:

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

Ejemplo:

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

Respuesta:

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

Parámetros

  • promotion_id: identificación de la promoción.
  • promotion_type: tipo de promoción (SMART).
  • offer_id: identificación de la oferta acordada.

Eliminar descuento pre-acordado

Llamada:

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'

Ejemplo:

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

Respuesta: Status 200 OK