Publicar no catálogo
Anunciar no catálogo a partir de um anúncio existente
Após conferir que seu anúncio existente é elegível para o catálogo e tiver obtido o catalog_product_id ativo que corresponde exatamente ao que você está anunciando, deve criar o anúncio de catálogo a partir de um POST no recurso /items/catalog_listings.
Variações
Nos domínios onde atualmente existe catálogo, os anúncios de catálogo não contém variações, pois elas estão associadas a um produto específico. Portanto, se seu anúncio original possuía variações, você terá um anúncio de catálogo para cada uma delas. As informações importantes de suas variações (por exemplo, a cor do item) não serão perdidas, mas estarão refletidas nos atributos do produto de catálogo. No futuro, é possível que existam domínios onde o produto nunca especifique perfeitamente o que é vendido (o tamanho em roupas, por exemplo) e é possível que as variações sejam permitidas. Vamos informar quando isso acontecer. Se seu item contém variações, você deve fazer um POST para cada uma delas, enviando o campo variation_id no corpo do POST.
Exemplo de um item com variações:
curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/catalog_listings
{
"item_id":"MLB1234",
"variation_id": 4321,
"catalog_product_id":"MLB9876"
}
Exemplo de um item sem variações:
curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/catalog_listings
{
"item_id":"MLB1234",
"catalog_product_id":"MLB9876"
}
Exemplo resumido de resposta para a criação de um item:
Resposta:
{
"id": "MLB1234",
"site_id": "MLB",
"title": "Samsung Galaxy J7 Prime 16 Gb Negro",
"warranty": null,
"catalog_product_id": "MLB9876",
"domain_id": "MLB-CELLPHONES",
"seller_custom_field": null,
"parent_item_id": null,
"differential_pricing": null,
"deal_ids": [],
"automatic_relist": false,
"date_created": "2019-08-02T11:33:31.270Z",
"last_updated": "2019-08-02T11:33:31.270Z",
"total_listing_fee": null,
"health": null,
"catalog_listing": true,
"item_relations": [
{
"id": "MLB123456789",
"variation_id": null,
"stock_relation": 1
}
]
}
Além disso, lembre-se de que:
- Se o item tiver variações, mas for enviado sem elas, o POST falhará, retornando um erro 400.
- catalog_product_id é um campo obrigatório no POST, o item possuindo ou não variações.
Sincronização das condições de vendas
A sincronização das condições de venda (como preço, forma de entrega, estoque, garantia, SKU e PIs) das publicações associadas será automática e com as seguintes regras:
- O vendedor não poderá remover a sincronização (opt-out).
- As publicações novas serão sincronizadas desde o início.
- As publicações existentes associadas serão sincronizadas assim que o vendedor modificar qualquer uma das condições de venda da publicação original.
Criar uma publicação de catálogo de maneira direta
Para realizar uma publicação direta em catálogo é necessário obter o catalog_product_id que corresponde exatamente ao produto a ser publicado, consultar o recurso de busca de produtos, você obtém uma sugestão de produtos com base em determinados parâmetros de busca.
Caso haja uma diferença entre o que o usuário compra e o produto associado, é possível que sejam geradas reclamações e / ou cancelamentos que impactarão negativamente na sua reputação e, como conseqüência, a desqualificação para publicação no catálogo, levando à suspensão da conta.
Além de criar publicações de catálogo à partir publicação original, você também pode criar itens de catálogo de forma direta, sem precisar de um item de marketplace para vincular. Lembre-se de que, para criar o item em catálogo, você deve considerar os mesmos requisitos estabelecidos em Publicar item no catálogo.
Lembre-se, no momento do POST, é necessário enviar os seguintes valores para a publicação do catálogo a ser criada.
- "catalog_product_id": este valor deve ser confirmado com o recurso de search/product.
- "catalog_listing": true: é necessário enviar o valor como true para gerar o item de catálogo.
Chamada:
curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items
Exemplo:
curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -d
'{
"site_id": "MLA",
"title": "Item de test no ofertar",
"category_id": "MLA1055",
"price": 10000000,
"currency_id": "ARS",
"available_quantity": 1,
"buying_mode": "buy_it_now",
"listing_type_id": "gold_special",
"pictures": [],
"attributes": [
{
"id": "CARRIER",
"name": "Compañía telefónica",
"value_id": "298335",
"value_name": "Liberado",
"value_struct": null,
"attribute_group_id": "OTHERS",
"attribute_group_name": "Otros"
},
{
"id": "ITEM_CONDITION",
"name": "Condición del ítem",
"value_id": "2230284",
"value_name": "Nuevo",
"value_struct": null,
"attribute_group_id": "OTHERS",
"attribute_group_name": "Otros"
}
],
"catalog_product_id": "MLA6005934",
"catalog_listing": true
}'
https://api.mercadolibre.com/items
Resposta:
{
"id": "MLA811894603",
"site_id": "MLA",
"title": "Apple iPhone iPhone 3g 8 Gb Negro 128 Mb Ram",
"subtitle": null,
"seller_id": 464161506,
"category_id": "MLA1055",
"official_store_id": null,
"price": 10000000,
"base_price": 10000000,
"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_special",
"start_time": "2019-08-29T14:49:42.945Z",
"historical_start_time": "2019-08-29T14:49:42.945Z",
"stop_time": "2039-08-24T04:00:00.000Z",
"end_time": "2039-08-24T04:00:00.000Z",
"expiration_time": "2019-11-17T14:49:42.987Z",
"condition": "new",
"permalink": "http://articulo.mercadolibre.com.ar/MLA-811894603-apple-iphone-iphone-3g-8-gb-negro-128-mb-ram-_JM",
"pictures": [
{
"id": "675782-MLA31138875214_062019",
"url": "http://mla-s1-p.mlstatic.com/675782-MLA31138875214_062019-O.jpg",
"secure_url": "https://mla-s1-p.mlstatic.com/675782-MLA31138875214_062019-O.jpg",
"size": "249x500",
"max_size": "598x1200",
"quality": ""
},
{
"id": "915001-MLA31138546867_062019",
"url": "http://mla-s2-p.mlstatic.com/915001-MLA31138546867_062019-O.jpg",
"secure_url": "https://mla-s2-p.mlstatic.com/915001-MLA31138546867_062019-O.jpg",
"size": "250x500",
"max_size": "600x1200",
"quality": ""
},
{
"id": "881441-MLA31138332972_062019",
"url": "http://mla-s2-p.mlstatic.com/881441-MLA31138332972_062019-O.jpg",
"secure_url": "https://mla-s2-p.mlstatic.com/881441-MLA31138332972_062019-O.jpg",
"size": "243x500",
"max_size": "585x1200",
"quality": ""
},
{
"id": "804666-MLA31139286536_062019",
"url": "http://mla-s1-p.mlstatic.com/804666-MLA31139286536_062019-O.jpg",
"secure_url": "https://mla-s1-p.mlstatic.com/804666-MLA31139286536_062019-O.jpg",
"size": "405x500",
"max_size": "836x1030",
"quality": ""
}
],
"video_id": null,
"descriptions": [
{
"id": "MLA811894603-2265773390"
}
],
"accepts_mercadopago": true,
"non_mercado_pago_payment_methods": [],
"shipping": {
"mode": "not_specified",
"local_pick_up": false,
"free_shipping": false,
"methods": [],
"dimensions": null,
"tags": [],
"logistic_type": "not_specified",
"store_pick_up": false
},
"international_delivery_mode": "none",
"seller_address": {
"id": 1061221617,
"comment": "",
"address_line": "Test Address 123",
"zip_code": "1414",
"city": {
"id": "",
"name": "Palermo"
},
"state": {
"id": "AR-C",
"name": "Capital Federal"
},
"country": {
"id": "AR",
"name": "Argentina"
},
"latitude": 38.11569,
"longitude": 13.3614868,
"search_location": {
"neighborhood": {
"id": "TUxBQlBBTDI1MTVa",
"name": "Palermo"
},
"city": {
"id": "TUxBQ0NBUGZlZG1sYQ",
"name": "Capital Federal"
},
"state": {
"id": "TUxBUENBUGw3M2E1",
"name": "Capital Federal"
}
}
},
"seller_contact": null,
"location": {},
"geolocation": {
"latitude": 38.11569,
"longitude": 13.3614868
},
"coverage_areas": [],
"attributes": [
{
"id": "CARRIER",
"name": "Compañía telefónica",
"value_id": "298335",
"value_name": "Liberado",
"value_struct": null,
"attribute_group_id": "OTHERS",
"attribute_group_name": "Otros"
},
{
"id": "ITEM_CONDITION",
"name": "Condición del ítem",
"value_id": "2230284",
"value_name": "Nuevo",
"value_struct": null,
"attribute_group_id": "OTHERS",
"attribute_group_name": "Otros"
},
{
"id": "BRAND",
"name": "Marca",
"value_id": "9344",
"value_name": "Apple",
"value_struct": null,
"attribute_group_id": "OTHERS",
"attribute_group_name": "Otros"
},
{
"id": "LINE",
"name": "Línea",
"value_id": "58993",
"value_name": "iPhone",
"value_struct": null,
"attribute_group_id": "OTHERS",
"attribute_group_name": "Otros"
},
{
"id": "MODEL",
"name": "Modelo",
"value_id": "14605",
"value_name": "iPhone 3G",
"value_struct": null,
"attribute_group_id": "OTHERS",
"attribute_group_name": "Otros"
},
{
"id": "IS_DUAL_SIM",
"name": "Es Dual SIM",
"value_id": "242084",
"value_name": "No",
"value_struct": null,
"attribute_group_id": "OTHERS",
"attribute_group_name": "Otros"
},
{
"id": "COLOR",
"name": "Color",
"value_id": "52049",
"value_name": "Negro",
"value_struct": null,
"attribute_group_id": "OTHERS",
"attribute_group_name": "Otros"
},
{
"id": "INTERNAL_MEMORY",
"name": "Memoria interna",
"value_id": "59566",
"value_name": "8 GB",
"value_struct": {
"number": 8,
"unit": "GB"
},
"attribute_group_id": "OTHERS",
"attribute_group_name": "Otros"
},
{
"id": "RAM",
"name": "Memoria RAM",
"value_id": "366239",
"value_name": "128 MB",
"value_struct": {
"number": 128,
"unit": "MB"
},
"attribute_group_id": "OTHERS",
"attribute_group_name": "Otros"
},
{
"id": "MAIN_COLOR",
"name": "Color principal",
"value_id": "2450295",
"value_name": "Negro",
"value_struct": null,
"attribute_group_id": "OTHERS",
"attribute_group_name": "Otros"
},
{
"id": "OPERATING_SYSTEM_NAME",
"name": "Nombre del sistema operativo",
"value_id": "7404961",
"value_name": "iOS",
"value_struct": null,
"attribute_group_id": "OTHERS",
"attribute_group_name": "Otros"
},
{
"id": "WITH_IMEI",
"name": "Con IMEI",
"value_id": "242085",
"value_name": "Sí",
"value_struct": null,
"attribute_group_id": "OTHERS",
"attribute_group_name": "Otros"
}
],
"warnings": [],
"listing_source": "",
"variations": [],
"thumbnail": "http://mla-s1-p.mlstatic.com/675782-MLA31138875214_062019-I.jpg",
"secure_thumbnail": "https://mla-s1-p.mlstatic.com/675782-MLA31138875214_062019-I.jpg",
"status": "active",
"sub_status": [],
"tags": [
"immediate_payment",
"test_item"
],
"warranty": null,
"catalog_product_id": "MLA6005934",
"domain_id": "MLA-CELLPHONES",
"seller_custom_field": null,
"parent_item_id": null,
"differential_pricing": null,
"deal_ids": [],
"automatic_relist": false,
"date_created": "2019-08-29T14:49:43.099Z",
"last_updated": "2019-08-29T14:49:43.099Z",
"total_listing_fee": null,
"health": null,
"catalog_listing": true,
"item_relations": []
}
Publicações de catálogo criadas automaticamente
Tenha em conta que a publicação original será atualizada com os attributes, variations.attributes o variations.attribute_combinations do produto ao qual foi associado para que ambas as publicações, relacionadas, sejam consistentes.
Abaixo você pode ver um item do catálogo com optin automático. Lembre-se que você pode reconhecer essas publicações com a tag catalog_boost.
Exemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/MLA123456789
Resposta:
{
"id":"MLA123456789",
"site_id":"MLA",
"title":"Samsung Galaxy A10 32 Gb Negro 2 Gb Ram",
"subtitle":null,
"seller_id":12312345,
"category_id":"MLA1055",
"official_store_id":null,
"price":14498.49,
"base_price":14498.49,
"original_price":null,
"currency_id":"ARS",
"initial_quantity":1,
"available_quantity":1,
"sold_quantity":0,
"sale_terms":[
],
"buying_mode":"buy_it_now",
"listing_type_id":"gold_special",
"start_time":"2020-02-25T13:30:06.000Z",
"stop_time":"2040-02-20T04:00:00.000Z",
"condition":"new",
"permalink":"https://articulo.mercadolibre.com.ar/MLA-840863454-samsung-galaxy-a10-32-gb-negro-2-gb-ram-_JM",
"thumbnail":"http://mla-s1-p.mlstatic.com/935364-MLA31838804614_082019-I.jpg",
"secure_thumbnail":"https://mla-s1-p.mlstatic.com/935364-MLA31838804614_082019-I.jpg",
"pictures":[
],
"video_id":"63vjmsBa3nw",
"descriptions":[
],
"accepts_mercadopago":true,
"non_mercado_pago_payment_methods":[
],
"shipping":{
},
"international_delivery_mode":"none",
"seller_address":{
},
"seller_contact":null,
"location":{
},
"geolocation":{
},
"coverage_areas":[
],
"attributes":[
],
"warnings":[
],
"listing_source":"",
"variations":[
],
"status":"active",
"sub_status":[
],
"tags":[
"extended_warranty_eligible",
"catalog_boost",
"good_quality_picture",
"good_quality_thumbnail",
"immediate_payment",
"cart_eligible"
],
"warranty":"Garantía del vendedor: 6 meses",
"catalog_product_id":"MLA14648964",
"domain_id":"MLA-CELLPHONES",
"parent_item_id":null,
"differential_pricing":null,
"deal_ids":[
],
"automatic_relist":false,
"date_created":"2020-02-25T13:30:06.000Z",
"last_updated":"2020-02-28T16:28:14.000Z",
"health":0.9,
"catalog_listing":true
}
Filtrar itens publicados automaticamente por vendedor
Você pode realizar uma busca por vendedor para identificar os itens marcados com a tag catalog_boost, usando o seguinte recurso.
Exemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/1234567/items/search?status=active&tags=catalog_boost
Criar publicações de marketplace com optin automático
Antes de criar novas publicações, é preciso identificar se é um produto ativo no catálogo e se está como requerido para catálogo. Para isso, execute um GET no recurso/products/search com o filtro status: active e verifique através de listing_strategy: catalog_required se o produto é requerido para gerar publicação de catálogo automaticamente.
Neste caso você poderá enviar o catalog_product_id e/ou GTIN no POST ao criar a publicação.
Resposta exemplo de produto necessário no catálogo:
{
"keywords": " Apple iphone 3g",
"domain_id": "MLA-CELLPHONES",
"paging": {
"total": 3,
"limit": 10,
"offset": 0
},
"results": [
{
"id": "MLA6005934",
"status": "active",
"domain_id": "MLA-CELLPHONES",
"settings": {
"listing_strategy": "forced_catalog"
},
"name": "Apple iPhone iPhone 3G 8 GB Negro 128 MB RAM",
"attributes": [
{
"id": "BRAND",
"name": "Marca",
"value_id": "9344",
"value_name": "Apple"
},
{
"id": "LINE",
"name": "Línea",
"value_id": "58993",
"value_name": "iPhone"
},
{
"id": "MODEL",
"name": "Modelo",
"value_id": "14605",
"value_name": "iPhone 3G"
},
{
"id": "IS_DUAL_SIM",
"name": "Es Dual SIM",
"value_id": "242084",
"value_name": "No"
},
{
"id": "COLOR",
"name": "Color",
"value_id": "52049",
"value_name": "Negro"
},
{
"id": "INTERNAL_MEMORY",
"name": "Memoria interna",
"value_id": "59566",
"value_name": "8 GB"
},
{
"id": "RAM",
"name": "Memoria RAM",
"value_id": "579543",
"value_name": "128 MB"
},
{
"id": "MAIN_COLOR",
"name": "Color principal",
"value_id": "2450295",
"value_name": "Negro"
},
{
"id": "OPERATING_SYSTEM_NAME",
"name": "Nombre del sistema operativo",
"value_id": "7404961",
"value_name": "iOS"
}
],
"pictures": [
{
"id": "675782-MLA31138875214_062019",
"url": "https://mla-s1-p.mlstatic.com/675782-MLA31138875214_062019-F.jpg"
},
{
"id": "915001-MLA31138546867_062019",
"url": "https://mla-s1-p.mlstatic.com/915001-MLA31138546867_062019-F.jpg"
},
{
"id": "881441-MLA31138332972_062019",
"url": "https://mla-s1-p.mlstatic.com/881441-MLA31138332972_062019-F.jpg"
},
{
"id": "804666-MLA31139286536_062019",
"url": "https://mla-s2-p.mlstatic.com/804666-MLA31139286536_062019-F.jpg"
}
]
},
{
"id": "MLA6007403",
"status": "active",
"domain_id": "MLA-CELLPHONES",
"settings": {
"listing_strategy": "catalog_required"
},
"name": "Apple iPhone iPhone 3G 16 GB Negro 128 MB RAM",
"attributes": [
{
"id": "BRAND",
"name": "Marca",
"value_id": "9344",
"value_name": "Apple"
},
{
"id": "LINE",
"name": "Línea",
"value_id": "58993",
"value_name": "iPhone"
},
{
"id": "MODEL",
"name": "Modelo",
"value_id": "14605",
"value_name": "iPhone 3G"
},
{
"id": "IS_DUAL_SIM",
"name": "Es Dual SIM",
"value_id": "242084",
"value_name": "No"
},
{
"id": "COLOR",
"name": "Color",
"value_id": "52049",
"value_name": "Negro"
},
{
"id": "INTERNAL_MEMORY",
"name": "Memoria interna",
"value_id": "59561",
"value_name": "16 GB"
},
{
"id": "RAM",
"name": "Memoria RAM",
"value_id": "579543",
"value_name": "128 MB"
},
{
"id": "MAIN_COLOR",
"name": "Color principal",
"value_id": "2450295",
"value_name": "Negro"
},
{
"id": "OPERATING_SYSTEM_NAME",
"name": "Nombre del sistema operativo",
"value_id": "7404961",
"value_name": "iOS"
}
],
"pictures": [
{
"id": "675782-MLA31138875214_062019",
"url": "https://mla-s1-p.mlstatic.com/675782-MLA31138875214_062019-F.jpg"
},
{
"id": "915001-MLA31138546867_062019",
"url": "https://mla-s1-p.mlstatic.com/915001-MLA31138546867_062019-F.jpg"
},
{
"id": "881441-MLA31138332972_062019",
"url": "https://mla-s1-p.mlstatic.com/881441-MLA31138332972_062019-F.jpg"
},
{
"id": "804666-MLA31139286536_062019",
"url": "https://mla-s2-p.mlstatic.com/804666-MLA31139286536_062019-F.jpg"
}
]
},
{
"id": "MLA6007404",
"status": "active",
"domain_id": "MLA-CELLPHONES",
"settings": {
"listing_strategy": "catalog_required"
},
"name": "Apple iPhone iPhone 3G 16 GB Blanco 128 MB RAM",
"attributes": [
{
"id": "BRAND",
"name": "Marca",
"value_id": "9344",
"value_name": "Apple"
},
{
"id": "LINE",
"name": "Línea",
"value_id": "58993",
"value_name": "iPhone"
},
{
"id": "MODEL",
"name": "Modelo",
"value_id": "14605",
"value_name": "iPhone 3G"
},
{
"id": "IS_DUAL_SIM",
"name": "Es Dual SIM",
"value_id": "242084",
"value_name": "No"
},
{
"id": "COLOR",
"name": "Color",
"value_id": "52055",
"value_name": "Blanco"
},
{
"id": "INTERNAL_MEMORY",
"name": "Memoria interna",
"value_id": "59561",
"value_name": "16 GB"
},
{
"id": "RAM",
"name": "Memoria RAM",
"value_id": "579543",
"value_name": "128 MB"
},
{
"id": "MAIN_COLOR",
"name": "Color principal",
"value_id": "2450308",
"value_name": "Blanco"
},
{
"id": "OPERATING_SYSTEM_NAME",
"name": "Nombre del sistema operativo",
"value_id": "7404961",
"value_name": "iOS"
}
],
"pictures": [
{
"id": "675782-MLA31138875214_062019",
"url": "https://mla-s1-p.mlstatic.com/675782-MLA31138875214_062019-F.jpg"
},
{
"id": "915001-MLA31138546867_062019",
"url": "https://mla-s1-p.mlstatic.com/915001-MLA31138546867_062019-F.jpg"
},
{
"id": "881441-MLA31138332972_062019",
"url": "https://mla-s1-p.mlstatic.com/881441-MLA31138332972_062019-F.jpg"
},
{
"id": "804666-MLA31139286536_062019",
"url": "https://mla-s2-p.mlstatic.com/804666-MLA31139286536_062019-F.jpg"
}
]
}
]
}
Validação antes de publicar um produto obrigatório no catálogo
Utilize o recurso /items/validate para validar antes de realizar um POST, para ter certeza que o item cumpre com todas os critérios, para publicar corretamente.
Benefícios no envio dos valores
POST | Benefício |
---|---|
Com catalog_product_id e GTIN | Recomendado. Ambos campos são obrigatórios separadamente. Ao enviar os dois valores, você otimiza o tempo de criação da publicação automática. A publicação original é atualizada com as informações correspondentes ao produto. |
Com catalog_product_id ou GTIN | Substituí os valores da ficha técnica pelos do produto, exceto GTIN (não é modificado ou preenchido automaticamente). |
Só com catalog_product_id | Este campo tem precedência sobre PKs ou GTINs, assumindo este valor e ignorando os outros valores. |
Só com GTIN | O produto é buscado por GTIN, completando o catalog_product_id com o resultado da busca. |
Com catalog_product_id inativo ou incorreto | Retorna erro, mesmo se o POST possuir PKs e GTINs para evitar inconsistências na criação. |
Erros de validação e soluções
Code_id | Reason | code_name | code_message | Solução |
---|---|---|---|---|
4400 | catalog_product_id ou GTIN obrigatórios (detectamos produtos com base em PKs) | body.required_fileds | Missing catalog_product_id or GTIN. It’s required at least one of them. | Enviar catalog_product_id ou GTIN |
4402 | Não conseguimos encontrar o produto ativo com base em catalog_product_id | item.catalog_product_id | The product $product_id is not active | Enviar um catalog_product_id ativo ou GTIN correto |
417 | catalog_product_id não corresponde a category_id | item.catalog_product_id | The product $product_id does not belong to the catalog_domain of the category $category_id. | Enviar um catalog_product_id correto |
418 | catalog_product_id de famílias diferentes entre o item e a variação | item.catalog_product_id | Variation catalog_product_id $variation_product_id is not a child of item catalog_product_id $item_product_id. | Enviar um catalog_product_id no nível de item e variação que sejam da mesma família. |
Seguinte: Publicações necessárias do catálogo.
