Documentación Mercado Libre
Descubre toda la información que debes conocer sobre las APIs de Mercado Libre.
Documentación
Gestionar promociones
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 | Sí | Sí |
---|---|---|---|---|---|---|---|
Co-fondeada | MARKETPLACE CAMPAIGN | Usuario acepta | No | Sí | No | Sí | No |
Descuento por volumen | VOLUME | Usuario acepta | No | Sí | No | Sí | No |
Oferta del día | DOD | Usuario define | Sí | No | Sí, informativo | No | No |
Oferta relámpago | LIGHTNING | Usuario define | Sí | No | Sí, mandatorio | No | No |
Descuento pre-acordado por ítem | PRE_NEGOTIATED | Usuario acuerda y acepta | No | Sí | Sí | Sí | No |
Campaña del vendedor | SELLER CAMPAIGN | Usuario define y acepta | No | No | No | Sí | No |
Campaña Smart | SMART | Usuario acepta | No | Sí | No | Sí | 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.
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).
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:
- Estados de campaña tradicional
- Estado de una campaña co-fondeada
- Estado de campaña descuento por volumen
- Estado de campaña con descuento pre-acordado por ítem
Consultar ítems de la promoción
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:
- Tradicional
- Co-fondeada
- con descuento por volumen
- de Oferta del día
- de Oferta relámpago
- con descuento pre-acordado por ítem
- del vendedor
- Smart.
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": [...]
}
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.
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:
- Indicando ítems para una campaña tradicional.
- Indicando ítems para una campaña co-fondeada.
- Indicando ítems para descuento por volumen.
- Aceptando descuento pre-acordado por ítem.
- Indicando ítems para una oferta del día.
- Indicando ítems para una oferta oferta ralámpago.
- Ofreciendo un descuento individual para un ítem.
- Indicando items para una campaña del vendedor.
- Indicando items para una campaña smart.
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:
- Modificando ítems en una campaña tradicional.
- Modificando ítems en una campaña co-fondeada.
- Modificando ítems en una campaña con descuento por volumen.
Eliminar ítems
Puedes eliminar los ítems que están participando en una determinada oferta:
- Eliminando ítems en una campaña tradicional.
- Eliminando ítems en una campaña co-fondeada.
- Eliminando ítems en una campaña con descuento por volumen.
- Eliminando descuento pre-acordado por ítem.
- Eliminando ítems en una oferta del día.
- Eliminando ítems en una oferta relámpago.
- Eliminando descuento individual a un ítem.
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.
Next post: Campañas co-fondeadas