Documentación Mercado Libre
Descubre toda la información que debes conocer sobre las APIs de Mercado Libre.![circulos azuis em degrade](https://http2.mlstatic.com/storage/developers-site-cms-admin/DevImgs/230801158836-ImgMS--1-.png)
Documentación
Campañas con cuotas para Marketplace
Publicaciones en las que elegís no agregar cuotas
Las publicaciones gold_special solo tienen las cuotas con interés que ofrecen los bancos. Por eso pagás solo el cargo por vender y, si aplica, también el costo fijo.
- Cuotas con interés - Programa Cuota Simple (Cuota Simple PBB): con esta opción, tus compradores tendrán mejor financiación (pagarán las tasas de financiación del programa). Para hacerlo, modifica tus publicaciones y actívalas con el tag cuota-simple-paid-by-buyer.
- Cuotas con interés bajo: con esta opción pagás un 4% por ofrecer a tus compradores de 3 a 12 cuotas con un interés menor que el de los bancos. Así podrás ofrecer precios más competitivos. Para hacerlo, modifica tus publicaciones y actívalas con el tag pcj-co-funded. Ver términos y condicionens.
Si tienes tienda de Mercado Shops te invitamos a acceder a la documentación para más detalles.
Publicaciones en las que elegís agregar cuotas
En las publicaciones gold_pro podrás ofrecer cuotas más convenientes a los compradores, pero deberás pagar el cargo por vender más un costo por ofrecer cuotas, y el costo fijo si aplica.
- 3 cuotas al mismo precio que publiques: tendrás un porcentaje de descuento en el cargo por venta, y así podrás ofrecer precios más competitivos. Para hacerlo, modifica tus publicaciones y actívalas con el tag 3x_campaign. Este descuento está disponible en categorías seleccionadas.
- 6 cuotas al mismo precio que publiques: tendrás un porcentaje de descuento en el cargo por venta. Estás publicaciones (6x), no tienen un tag asociado en /ítems. Al dar de alta una publicación en gold_pro, ofrecerás por defecto las 6 cuotas al mismo precio que publiques. Este descuento está disponible en a todas las categorías. Ver costos por agregar cuotas.
- Programa Cuota Simple en aquellas publicaciones que participen del programa, tendrás un % de descuento en el cargo por venta según la cantidad de cuotas que elijas. Para ofrecer precios más competitivos con este descuento, modifica tus publicaciones y activa la opción de de cuotas al mismo precio que publiques con los tags cuota-simple-3, cuota-simple-6 o cuota-simple-paid-by-buyer según corresponda. Este descuento estará disponible en categorías seleccionadas (Términos y Condiciones).
Si tienes tienda de Mercado Shops te invitamos a acceder a la documentación para ver más detalles .
Comparación opciones de cuotas
Publicaciones en las que eliges no agregar cuotas
Nombre de campaña | Listing type | Tag Marketplace | Tag Mshops |
---|---|---|---|
No quiero agregar cuotas (el vendedor no tiene habilitado Cuota Simple) | gold_special | sin tag | sin tag |
No quiero agregar cuotas (el vendedor tiene habilitado Cuota Simple) | gold_special | cuota-simple-paid-by-buyer | no aplica |
3 a 12 cuotas con interés bajo | gold_special | pcj-co-funded | mshops_pcj-co-funded |
Publicaciones en las que eliges agregar cuotas
Nombre de campaña | Listing type | Tag Marketplace | Tag Mshops |
---|---|---|---|
3 cuotas al mismo precio que publicaste | gold_pro | 3x_campaign | mshops_3x_campaign |
6 cuotas al mismo precio que publicaste | gold_pro | sin tag | no aplica |
3 cuotas al mismo precio que publicaste - Cuota Simple | gold_pro | cuota-simple-3 | mshops_cuota-simple-3 |
6 cuotas al mismo precio que publicaste - Cuota Simple | gold_pro | cuota-simple-6 | mshops_cuota-simple-6 |
9 cuotas al mismo precio que publicaste | gold_pro | 9x_campaign | mshops_9x_campaign |
12 cuotas al mismo precio que publicaste - Cuota Simple (Activación en 18/06/24) | gold_pro | cuota-simple-12 | mshops_cuota-simple-12 |
12 cuotas al mismo precio que publicaste (Activación en 18/06/24) | gold_pro | 12x_campaign | mshops_12x_campaign |
Para mas detalles sobre los casos de Mercado Shops, podras consultar la documentacion completa.
Conocer si el usuario está habilitado para sumarse a la campaña
Para conocer qué usuario tiene la posibilidad de sumarse a las campañas existentes, deberás realizar un GET al recurso /special_installments según corresponda, con el $SELLER_ID.
Parámetros opcionales:
- cuota-simple-paid-by-buyer: programa Cuota Simple en gold_special.
- pcj-co-funded: campaña 3 a 12 cuotas con un interés bajo.
- cuota-simple-3: programa Cuota Simple 3 en gold_pro.
- cuota-simple-6: programa Cuota Simple 6 en gold_pro.
En caso que el usuario pueda participar, se mostrará la fecha en la que fue habilitado.
Llamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/special_installments/$CAMPAIGN_TAG_ID/sellers/$SELLER_ID
Ejemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/special_installments/3x_campaign/sellers/1234
Respuesta:
{
"date_created": "2019-08-30T16:09:10.941-04:00",
"seller_id": 1234
}
Si el usuario NO tiene permitido o estas consultando una campaña de 3x o 9x que estan activas para todos los sellers MLA, la respuesta será:
{
"message": "seller does not exist",
"error": "seller.not_found",
"status": 404,
"cause": []
}
Conocer qué categorías pueden sumarse a la campaña
Debes realizar un POST al recurso /special_installments según la campaña que corresponda, con el $CATEGORY_ID (ejem: pcj-co-funded, 3x_campaign)
Llamada:
curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/special_installments/$CAMPAIGN_TAG_ID/categories/$CATEGORY_ID/enabled
Response Body: devolverá como respuesta el campo “enabled” con valor true o false, según corresponda.
Response Status: 200
Cacheable: Sí. Se devolverá el header “Cache-Control” con value “max-age=$max-age” indicando el tiempo recomendado en segundos para cachear la información que responde el recurso.
Ejemplo:
curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/special_installments/3x_campaign/categories/MLA1055/enabled
Respuesta:
{
"enabled": true
}
Recuerda que para el Programa Cuota Simple, deben ser productos de fabricación nacional y en el body enviar la marca ($brand) y el modelo ($model) según corresponda.
Parámetros opcionales:
- cuota-simple-paid-by-buyer: programa Cuota Simple en gold_special.
- cuota-simple-3: programa Cuota Simple 3 en gold_pro.
- cuota-simple-6: programa Cuota Simple 6 en gold_pro.
Llamada:
curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/special_installments/$CAMPAIGN_TAG_ID/categories/$CATEGORY_ID/enabled
Response Body: Se devolverá como respuesta el campo “enabled” con valor true o false, según corresponda.
Response status: 200
Cacheable: Sí. Se devolverá el header “Cache-Control” con value “max-age=$max-age” indicando el tiempo recomendado en segundos para cachear la información que responde el recurso.
Ejemplo:
curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/special_installments/cuota-simple-6/categories/MLA1055/enabled
{
"brand":"Motorola",
"model":"Z1",
"alphanumeric_model":"Z1 - 312 fD4"
}
Respuesta:
{
"enabled":true
}
Este caso indica que un ítem con marca Motorola, modelo Z1 y modelo alfanumérico “Z1-312fD4” participa del programa.
Conocer si una publicación está en la campaña
Para consultar si una publicación en las que elegís no agregar cuotas (gold_special) tiene habilitada alguna campaña, realiza un GET al recurso /items con su item_id y verifica que tenga el tag cuota-simple-paid-by-buyer o pcj-co-funded dentro de los campos.
Para consultar si una publicación en las que elegís agregar cuotas (gold_pro) tiene habilitada alguna campaña, realiza un GET al recurso /items con su item_id y verifica que tenga el tag 3x_campaign, cuota-simple-3 o cuota-simple-6 dentro de los campos. Recuerda que las publicaciones gold_pro con “6 cuotas al mismo precio que publiques” (6x), no tienen un tag asociado en /ítems.
Llamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/$ITEM_ID
Ejemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/MLA608007087
Respuesta:
{
"id": "MLA810693730",
"site_id": "MLA",
"title": "Item De Test - No Ofertar",
"subtitle": null,
"seller_id": 443024908,
"category_id": "MLA3530",
"official_store_id": null,
"price": 100,
"base_price": 100,
"original_price": null,
"inventory_id": null,
"currency_id": "ARS",
"initial_quantity": 1,
"available_quantity": 1,
"sold_quantity": 0,
"sale_terms": [],
"buying_mode": "buy_it_now",
"listing_type_id": "gold_pro",
"start_time": "2019-08-22T17:33:51.000Z",
"stop_time": "2039-08-17T04:00:00.000Z",
"end_time": "2039-08-17T04:00:00.000Z",
"expiration_time": "2019-11-10T17:33:51.000Z",
"condition": "new",
"descriptions": [],
"accepts_mercadopago": true,
"non_mercado_pago_payment_methods": [],
"international_delivery_mode": "none",
"seller_contact": null,
"location": {},
"geolocation": {
"latitude": -34.5780655,
"longitude": -58.4265317
},
"coverage_areas": [],
"warnings": [],
"listing_source": "",
"variations": [],
"status": "active",
"sub_status": [],
"tags": [
"3x_campaign",
"immediate_payment",
"test_item"
],
"warranty": null,
"catalog_product_id": null,
"domain_id": "MLA-UNCLASSIFIED_PRODUCTS",
"seller_custom_field": null,
"parent_item_id": null,
"differential_pricing": null,
"deal_ids": [],
"automatic_relist": false,
"date_created": "2019-08-22T17:33:51.000Z",
"last_updated": "2019-08-22T18:37:41.468Z",
"health": null,
"catalog_listing": false,
"item_relations": []
}
Ver cargos por venta filtrando campañas
Para consultar los costos por vender debes realizar un GET al recurso /listing_prices filtrando por precio, listing_type, tag y dominio, según corresponda.
Recuerda:
- Respetar la relación listing_type+tag (ver opciones) .
- Filtrar por channel para ver las comisiones específicas. En caso contrario, verás por defecto las de marketplace.
Llamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/sites/$SITE/listing_prices?price=$PRICE&listing_type_id=$LISTING_TYPE_ID&tags=$CAMPAIGN_TAG_ID&domain_id=$DOMAIN_ID
Ejemplo del dominio Notebooks:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/sites/MLA/listing_prices?price=10000&listing_type_id=gold_pro&tags=3x_campaign&domain_id=MLA-NOTEBOOKS
Respuesta:
[
{
"currency_id": "ARS",
"free_relist": false,
"listing_exposure": "highest",
"listing_fee_amount": 0,
"listing_fee_details": {
"fixed_fee": 0,
"gross_amount": 0
},
"listing_type_id": "gold_pro",
"listing_type_name": "Premium",
"requires_picture": true,
"sale_fee_amount": 2700,
"sale_fee_details": {
"financing_add_on_fee": 15,
"fixed_fee": 0,
"gross_amount": 2700,
"meli_percentage_fee": 12,
"percentage_fee": 27
},
"stop_time": "2043-09-09T00:00:00.000-04:00"
}
]
}
]
Es decir, el dominio Notebooks con el tag 3x_campaign, el cargo por venta en Marketplace será de 12% y el cargo por ofrecer cuotas será de 15%, total cargos de 27%. Para más información, puedes consultar recursos para obtener los costos por vender y el significado de cada campo en la respuesta.
Ejemplo del dominio Cellphones:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/sites/MLA/listing_prices?price=10000&listing_type_id=gold_special&tags=pcj-co-funded&domain_id=MLA-CELLPHONES
Respuesta:
[
{
"currency_id": "ARS",
"free_relist": false,
"listing_exposure": "highest",
"listing_fee_amount": 0,
"listing_fee_details": {
"fixed_fee": 0,
"gross_amount": 0
},
"listing_type_id": "gold_special",
"listing_type_name": "Clásica",
"requires_picture": true,
"sale_fee_amount": 1600,
"sale_fee_details": {
"financing_add_on_fee": 4,
"fixed_fee": 0,
"gross_amount": 1600,
"meli_percentage_fee": 12,
"percentage_fee": 16
},
"stop_time": "2043-09-09T00:00:00.000-04:00"
}
]
Es decir, el dominio Cellphones con el tag pcj-co-funded, el cargo por venta en Marketplace será de 12% y el cargo por ofrecer cuotas será de 4%, total cargos de 16%. Para más información puedes consultar recursos para obtener los costos por vender.
Crear una publicación en una campaña
Debes realizar el POST al recurso /items incluyendo el tag correspondiente (ver opciones). Ten en cuenta de siempre enviar el atributo buying_mode ya que es requerido en el POST para productos nuevos.
Además, recuerda que las publicaciones con el programa Cuota Simple, deben estar dentro de las categorías, marcas y modelos habilitados que confirman que sea un producto nacional. Reconoce qué productos pueden sumarse a la campaña .
Llamada:
curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items
{
"title": "Item de testeo por favor no ofertar kc:off",
"pictures": [
..
],
"price": 53936,
"variations": [],
"shipping": {
..
},
"currency_id": "ARS",
"location": {},
"attributes": [
...
],
"listing_type_id": "gold_pro",
"available_quantity": 543,
"category_id": "MLA1611",
"condition": "new",
"buying_mode": "buy_it_now",
"tags": [
"3x_campaign"
]
...
}
Respuesta:
{
"id": "MLA810693730",
"site_id": "MLA",
"title": "Item De Test - No Ofertar",
"subtitle": null,
"seller_id": 443024908,
"category_id": "MLA3530",
"official_store_id": null,
"price": 100,
"base_price": 100,
"original_price": null,
"inventory_id": null,
"currency_id": "ARS",
"initial_quantity": 1,
"available_quantity": 1,
"sold_quantity": 0,
"sale_terms": [],
"buying_mode": "buy_it_now",
"listing_type_id": "gold_pro",
"start_time": "2019-08-22T17:33:51.000Z",
"stop_time": "2039-08-17T04:00:00.000Z",
"end_time": "2039-08-17T04:00:00.000Z",
"expiration_time": "2019-11-10T17:33:51.000Z",
"condition": "new",
"descriptions": [],
"accepts_mercadopago": true,
"non_mercado_pago_payment_methods": [],
"international_delivery_mode": "none",
"seller_contact": null,
"location": {},
"geolocation": {
"latitude": -34.5780655,
"longitude": -58.4265317
},
"coverage_areas": [],
"warnings": [],
"listing_source": "",
"variations": [],
"status": "active",
"sub_status": [],
"tags": [
"3x_campaign",
"immediate_payment",
"test_item"
],
"warranty": null,
"catalog_product_id": null,
"domain_id": "MLA-UNCLASSIFIED_PRODUCTS",
"seller_custom_field": null,
"parent_item_id": null,
"differential_pricing": null,
"deal_ids": [],
"automatic_relist": false,
"date_created": "2019-08-22T17:33:51.000Z",
"last_updated": "2019-08-22T18:37:41.468Z",
"health": null,
"catalog_listing": false,
"item_relations": []
}
Recuerda que retornaremos un http error 400 siempre que no cumplas los requisitos o en los siguientes casos:
- Categoría no habilitada para ofrecer cuotas.
- Vendedor no habilitado para participar del programa Cuota Simple.
- Producto usado o reacondicionado.
- Listing_type de la publicación no corresponde con el tag campaña enviado (ver opciones).
- Marca o modelo del producto no participa de la campaña (en publicaciones con Cuota Simple).
Habilitar la campaña en una publicación
Debes realizar un PUT al recurso /items incluyendo el tag correspondiente (ver opciones). Ten en cuenta que si el item_id contiene otros tags, también deberán ser enviados en la modificación.
Además recuerda que deben ser productos nuevos y las publicaciones en el Programa Cuota Simple, deben estar dentro de las categorías, marcas y modelos habilitados que confirman que sea un producto nacional. Reconoce qué productos pueden sumarse a la campaña.
Llamada:
curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -H "Accept: application/json" -d
{
"tags": [
"3x_campaign",
"immediate_payment",
"test_item"
]
}
https://api.mercadolibre.com/items/$ITEM_ID
Ejemplo:
curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -H "Accept: application/json" -d
{
"tags": [
"3x_campaign",
"immediate_payment",
"test_item"
]
}
https://api.mercadolibre.com/items/MLA810693730
Respuesta:
{
"id": "MLA810693730",
"site_id": "MLA",
"title": "Item De Test - No Ofertar",
"subtitle": null,
"seller_id": 443024908,
"category_id": "MLA3530",
"official_store_id": null,
"price": 100,
"base_price": 100,
"original_price": null,
"inventory_id": null,
"currency_id": "ARS",
"initial_quantity": 1,
"available_quantity": 1,
"sold_quantity": 0,
"sale_terms": [],
"buying_mode": "buy_it_now",
"listing_type_id": "gold_pro",
"start_time": "2019-08-22T17:33:51.000Z",
"stop_time": "2039-08-17T04:00:00.000Z",
"end_time": "2039-08-17T04:00:00.000Z",
"expiration_time": "2019-11-10T17:33:51.000Z",
"condition": "new",
"descriptions": [],
"accepts_mercadopago": true,
"non_mercado_pago_payment_methods": [],
"international_delivery_mode": "none",
"seller_contact": null,
"location": {},
"geolocation": {
"latitude": -34.5780655,
"longitude": -58.4265317
},
"coverage_areas": [],
"warnings": [],
"listing_source": "",
"variations": [],
"status": "active",
"sub_status": [],
"tags": [
"3x_campaign",
"immediate_payment",
"test_item"
],
"warranty": null,
"catalog_product_id": null,
"domain_id": "MLA-UNCLASSIFIED_PRODUCTS",
"seller_custom_field": null,
"parent_item_id": null,
"differential_pricing": null,
"deal_ids": [],
"automatic_relist": false,
"date_created": "2019-08-22T17:33:51.000Z",
"last_updated": "2019-08-22T18:37:41.468Z",
"health": null,
"catalog_listing": false,
"item_relations": []
}
Recuerda que retornaremos un http error 400 siempre que no cumplas los requisitos o en los siguientes casos:
- Categoría no habilitada para ofrecer cuotas.
- Vendedor no habilitado para participar del programa Cuota Simple.
- Producto usado o reacondicionado.
- Listing_type de la publicación no corresponde con el tag campaña enviado (ver opciones).
- Marca o modelo del producto no participa de la campaña (en publicaciones con Cuota Simple).
Deshabilitar la campaña en una publicación
Para deshabilitar la campaña en un item_id debes realizar un PUT al recurso /items incluyendo todos los tags que tenía anteriormente excepto el tag que deseas eliminar ( cuota-simple-paid-by-buyer, pcj-co-funded, 3x_campaign, cuota-simple-3 o cuota-simple-6).
Llamada:
curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -H "Accept: application/json" -d
{
"tags": [
"immediate_payment",
"test_item"
],
}
https://api.mercadolibre.com/items/$ITEM_ID
Ejemplo:
curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -H "Accept: application/json" -d
{
"tags": [
"immediate_payment",
"test_item"
],
}
https://api.mercadolibre.com/items/MLA810693730
Respuesta:
{
"id": "MLA810693730",
"site_id": "MLA",
"title": "Item De Test - No Ofertar",
"subtitle": null,
"seller_id": 443024908,
"category_id": "MLA3530",
"official_store_id": null,
"price": 100,
"base_price": 100,
"original_price": null,
"inventory_id": null,
"currency_id": "ARS",
"initial_quantity": 1,
"available_quantity": 1,
"sold_quantity": 0,
"sale_terms": [],
"buying_mode": "buy_it_now",
"listing_type_id": "gold_pro",
"start_time": "2019-08-22T17:33:51.000Z",
"stop_time": "2039-08-17T04:00:00.000Z",
"end_time": "2039-08-17T04:00:00.000Z",
"expiration_time": "2019-11-10T17:33:51.000Z",
"condition": "new",
"descriptions": [],
"accepts_mercadopago": true,
"non_mercado_pago_payment_methods": [],
"international_delivery_mode": "none",
"seller_contact": null,
"location": {},
"geolocation": {
"latitude": -34.5780655,
"longitude": -58.4265317
},
"coverage_areas": [],
"warnings": [],
"listing_source": "",
"variations": [],
"status": "active",
"sub_status": [],
"tags": [
"immediate_payment",
"test_item"
],
"warranty": null,
"catalog_product_id": null,
"domain_id": "MLA-UNCLASSIFIED_PRODUCTS",
"seller_custom_field": null,
"parent_item_id": null,
"differential_pricing": null,
"deal_ids": [],
"automatic_relist": false,
"date_created": "2019-08-22T17:33:51.000Z",
"last_updated": "2019-08-22T18:37:41.468Z",
"health": null,
"catalog_listing": false,
"item_relations": []
}