Brand Central

Com esta funcionalidade os vendedores poderão enviar sugestões de produtos que não existem no nosso Catálogo do Mercado Livre. Desta forma conseguiremos escalar nosso catálogo, dando a possibilidade de somar mais produtos de maneira mais rápida e ainda melhorando todo este fluxo. .

Receber notificações de status de sugestões

Com o tópico catalog_suggestions você pode se inscrever e receber notificações das mudanças de status das sugestões de produtos para nosso catálogo. Os status possíveis para uma sugestão são:

  • UNDER_REVIEW: a sugestão se encontra em revisão pelo Mercado Livre.
  • WAITING_FOR_FIX: foi encontrado um erro nos dados e deve ser corrigido pelo usuário.
  • PUBLISHED: a sugestão foi aprovada e o produto já se encontra criado e ativo em nosso catálogo.
  • REJECTED: a sugestão foi recusada por motivos legais ou, porque o produto já se encontra em nosso catálogo.

Obter quantidade de sugestões de um usuário

Tendo um user_id, esse recurso devolve a informação se um vendedor está ou não habilitado para usar esta funcionalidade, além disso, pode obter a quantidade (quota) que esse usuário tem disponível para criar sugestões.


Chamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/catalog_suggestions/users/$USER_ID/quota

Exemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/catalog_suggestions/users/123456/quota

Resposta:

{
  "quota": [
     {
        "type": "standard",
        "available": 10
     }
  ]
}

Resposta para usuário não permitido:

{
  "code": "forbidden",
  "message": "User not allowed",
  "status_code": 403
}

Obter domínios disponíveis para publicar sugestões

Dado um site_id, esse recurso devolve um dump de todos os domínios indicando se estão disponíveis ou não para criar sugestões.

Chamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/catalog_suggestions/domains/$SITE_ID/available/full

Exemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/catalog_suggestions/domains/MLA/available/full

Resposta:

{
    "generation_date": "2021-11-15T04:32:14.512952Z",
    "domains": [
        {
            "id": "MLA-CELLPHONE_USB_AND_AUXILIARY_ADAPTERS",
            "name": "Adaptadores de USB y auxiliar para celulares",
            "pictures": [
                {
                    "id": "715173-MLU30701120250_052019",
                    "url": "http://http2.mlstatic.com/D_NQ_NP_715173-MLU30701120250_052019-F.jpg",
                    "secure_url": "https://http2.mlstatic.com/D_NQ_NP_715173-MLU30701120250_052019-F.jpg",
                    "size": "500x500"
                }
                ],
            "available": false
        },
        {
            "id": "MLA-AIR_CONDITIONERS",
            "name": "Aires acondicionados",
            "pictures": [
                {
                    "id": "795131-MLU26486283495_122017",
                    "url": "http://mlu-s1-p.mlstatic.com/795131-MLU26486283495_122017-F.jpg",
                    "secure_url": "https://mlu-s1-p.mlstatic.com/795131-MLU26486283495_122017-F.jpg",
                    "size": "500x500"
                }
            ],
            "available": true
        },
        ...
    ]
}

Ficha técnica por domínio

Dado um domain_id, este endpoint devolve a ficha técnica para as sugestões do domínio consultado.

Chamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/domains/$DOMAIN_ID/techincal_specs?channel_id=catalog_suggestions

Exemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/domains/MLA-CELLPHONES/technical_specs?channel_id=catalog_suggestions

Resposta:

{
  "input": {
    "groups": [
      {
        "id": "MAIN",
        "label": "Características principales",
        "relevance": 1,
        "section": "SPECIFICATIONS",
        "ui_config": {},
        "components": [
          {
              "component": "TEXT_INPUT",
              "label": "Marca",
              "ui_config": {
                  "hint": "Escribe la marca real del producto o 'Genérica' si no tiene marca.",
                  "allow_custom_value": false,
                  "allow_filtering": false
              },
              "attributes": [
                  {
                      "id": "BRAND",
                      "name": "Marca",
                      "value_type": "string",
                      "value_max_length": 255,
                      "tags": [
                          "catalog_required",
                          "required"
                      ],
                      "hierarchy": "PARENT_PK",
                      "relevance": 1
                  }
              ],
              "unified_units": []
          }
        ]
      },
      {
        "id": "OTHER",
        "label": "Otros",
        "relevance": 1,
        "section": "SPECIFICATIONS",
        "ui_config": {},
        "components": [
          {
              "component": "TEXT_INPUT",
              "label": "Modelo detallado",
              "ui_config": {
                  "allow_custom_value": false,
                  "allow_filtering": false
              },
              "attributes": [
                  {
                      "id": "DETAILED_MODEL",
                      "name": "Modelo detallado",
                      "value_type": "string",
                      "value_max_length": 255,
                      "tags": [
                          "hidden"
                      ],
                      "hierarchy": "CHILD_DEPENDENT",
                      "relevance": 1
                  }
              ],
              "unified_units": []
          }
        ]
      }
    ]
  },
  "output": {
    "main_title": "Características Principales",
    "groups": [
      {
        "id": "GENERAL_CHARACTERISTICS",
        "label": "Características generales",
        "relevance": 1,
        "section": "SPECIFICATIONS",
        "ui_config": {},
        "components": [
          {
            "component": "TEXT_OUTPUT",
            "label": "Marca",
            "ui_config": {
                "hint": "Escribe la marca real del producto o 'Genérica' si no tiene marca."
            },
            "attributes": [
              {
                "id": "BRAND",
                "name": "Marca",
                "value_type": "string",
                "tags": [],
                "hierarchy": "PARENT_PK",
                "relevance": 1
              }
            ]
          },
          {
            "component": "TEXT_OUTPUT",
            "label": "Línea",
            "ui_config": {},
            "attributes": [
              {
                "id": "LINE",
                "name": "Línea",
                "value_type": "string",
                "tags": [],
                "hierarchy": "PARENT_PK",
                "relevance": 1
              }
            ]
          }
        ]
      }
    ]
  }
}

Ficha técnica para sugestões

Contamos com recursos que permitem consultar somente o input ou somente o output da ficha técnica para um determinado domínio consultado. O input se trata das configurações que usamos para pedir certos atributos e o output se trata das configurações que definem quais os atributos que vamos mostrar no front.


Input

Chamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' hhttps://api.mercadolibre.com/domains/$DOMAIN_ID/techincal_specs/input?channel_id=catalog_suggestions

Exemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/domains/MLA-CELLPHONES/technical_specs/input?channel_id=catalog_suggestions

Resposta:

{
  "groups": [
    {
      "id": "MAIN",
      "label": "Características principales",
      "relevance": 1,
      "section": "SPECIFICATIONS",
      "ui_config": {},
      "components": [
        {
            "component": "TEXT_INPUT",
            "label": "Marca",
            "ui_config": {
                "hint": "Escribe la marca real del producto o 'Genérica' si no tiene marca.",
                "allow_custom_value": false,
                "allow_filtering": false
            },
            "attributes": [
                {
                    "id": "BRAND",
                    "name": "Marca",
                    "value_type": "string",
                    "value_max_length": 255,
                    "tags": [
                        "catalog_required",
                        "required"
                    ],
                    "hierarchy": "PARENT_PK",
                    "relevance": 1
                }
            ],
            "unified_units": []
        }
      ]
    },
    {
      "id": "OTHER",
      "label": "Otros",
      "relevance": 1,
      "section": "SPECIFICATIONS",
      "ui_config": {},
      "components": [
        {
            "component": "TEXT_INPUT",
            "label": "Modelo detallado",
            "ui_config": {
                "allow_custom_value": false,
                "allow_filtering": false
            },
            "attributes": [
                {
                    "id": "DETAILED_MODEL",
                    "name": "Modelo detallado",
                    "value_type": "string",
                    "value_max_length": 255,
                    "tags": [
                        "hidden"
                    ],
                    "hierarchy": "CHILD_DEPENDENT",
                    "relevance": 1
                }
            ],
            "unified_units": []
        }
      ]
    }
  ]
}
  }
}

Output

Chamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/domains/$DOMAIN_ID/techincal_specs/output?channel_id=catalog_suggestions

Exemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/domains/MLA-CELLPHONES/technical_specs/output?channel_id=catalog_suggestions

Resposta:

{
  "main_title": "Características Principales",
  "groups": [
    {
      "id": "GENERAL_CHARACTERISTICS",
      "label": "Características generales",
      "relevance": 1,
      "section": "SPECIFICATIONS",
      "ui_config": {},
      "components": [
        {
          "component": "TEXT_OUTPUT",
          "label": "Marca",
          "ui_config": {
              "hint": "Escribe la marca real del producto o 'Genérica' si no tiene marca."
          },
          "attributes": [
            {
              "id": "BRAND",
              "name": "Marca",
              "value_type": "string",
              "tags": [],
              "hierarchy": "PARENT_PK",
              "relevance": 1
            }
          ]
        },
        {
          "component": "TEXT_OUTPUT",
          "label": "Línea",
          "ui_config": {},
          "attributes": [
            {
              "id": "LINE",
              "name": "Línea",
              "value_type": "string",
              "tags": [],
              "hierarchy": "PARENT_PK",
              "relevance": 1
            }
          ]
        }
      ]
    }
  ]
}

Validações prévias

Com este recurso é possível fazer um check sobre a sugestão antes de enviá-la efetivamente. Ele recebe uma sugestão e devolve o resultado das validações próprias de Brand Central, de Products Standards e de Items.


Exemplo:

curl -X POST  -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -d
'{
    "title": "Sugerencia de test",
    "domain_id": "MLA-CELLPHONES",
    "pictures": [
        {
          "id": "647954-MLA46144073729_052021"
        }
    ],
    "attributes": [
        {
            "id": "BRAND",
            "values": [
                {
                     "name": "Samsung"
                }
            ]
        },
        {
            "id": "IS_DUAL_SIM",
            "values": [
                {
                    "name": "Si"
                }
            ]
        },
        {
            "id": "GTIN",
            "values": [
                {
                    "name": 12345678
                }
            ]
        },
        {
            "id": "RAM",
            "values": [
                {
                    "name": "6 GB"
                }
            ]
        },
        {
            "id": "COLOR",
            "values": [
                {
                    "name": "Rojo"
                }
            ]
        }
    ]
}
'
https://api.mercadolibre.com/catalog_suggestions/validate

Resposta: Status 200 OK


Quando a sugestão tem erros de validação.


Status: 400


Exemplo:


{
    "error": "validation_error",
    "message": "Validation error",
    "status": 400,
    "cause": [
        {
            "department": "items",
            "cause_id": 10147,
            "type": "error",
            "code": "item.attributes.missing_required",
            "references": [
                "item.attributes",
                "item.variations.attribute_combinations"
            ],
            "message": "The attributes [MODEL, INTERNAL_MEMORY] are required for category MLA1055. Check the attribute is present in the attributes list or in all variation's attributes_combination or attributes."
        },
        {
            "department": "quality",
            "cause_id": 3026,
            "type": "error",
            "code": "InvalidProductIdentifier",
            "references": [
                "suggestion.attributes"
            ],
            "message": "El código universal 12345678 tiene un formato incorrecto."
        },
        {
            "department": "quality",
            "cause_id": 3035,
            "type": "error",
            "code": "IreqAttributesMissing",
            "references": [
                "suggestion.attributes"
            ],
            "message": "El campo \"Memoria interna\" es obligatorio y no está cargado."
        },
        {
            "department": "quality",
            "cause_id": 3017,
            "type": "error",
            "code": "InvalidAttributeValue",
            "references": [
                "suggestion.attributes"
            ],
            "message": "El campo \"Es Dual SIM\" debe ser alguna de las opciones disponibles y le cargaste \"Si\"."
        },
        {
            "department": "quality",
            "cause_id": 304,
            "type": "error",
            "code": "CatalogRequiredMissing",
            "references": [
                "suggestion.attributes"
            ],
            "message": "El campo \"Modelo\" es obligatorio y no está cargado."
        }
    ]
}

Criar sugestão

Para criação de cada sugestão de produto, deverá ser enviado um POST com as informações do item conforme mostrado a seguir:

Exemplo:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -d
'{
  "title": "Item De Test, No Ofertar!",
  "domain_id": "MLA-CELLPHONES",
  "pictures": [{
    "id": "647954-MLA46144073729_052021"
  }],
  "attributes": [{
      "id": "BRAND",
      "values": [
      {
        "id": "59387",
        "name": "Xiaomi"
      }
     ]
    },
    {
      "id": "LINE",
      "values": [
       {
        "id": "199791",
        "name": "Redmi"
       }
      ]
   }
  ]
}'
https://api.mercadolibre.com/catalog_suggestions

Resposta:

{
	"id": "MLA922220746",
	"site_id": "MLA",
	"title": "Item De Test, No Ofertar!",
	"seller_id": 238564384,
	"domain_id": "MLA-CELLPHONES",
	"status": "UNDER_REVIEW",
	"attributes": [{
			"id": "BRAND",
			"values": [
			{
				"id": "59387",
				"name": "Xiaomi"
			}
		  ]
		},
		{
			"id": "LINE",
			"values": [
			{
				"id": "199791",
				"name": "Redmi"
			}
		  ]
		}
	],
	"pictures": [{
		"id": "647954-MLA46144073729_052021"
	}]
}

Obter sugestão

Com este recurso é possível obter os detalhes de uma sugestão que foi criada anteriormente.


Chamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/catalog_suggestions/$SUGGESTION_ID

Exemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/catalog_suggestions/123456

Resposta:

{
  "id": "MLA12345",
  "site_id": "MLA",
  "status": "UNDER_REVIEW" | "WAITING_FOR_FIX" | "PUBLISHED" | "REJECTED",
  "sub_status": "VALIDATING" | "WAITING_FOR_FIX" | "READY_TO_IMPORT" | "IMPORTED" | "PUBLISHED" | "REJECTED",
  "title": "Item De Test, No Ofertar!",
  "seller_id": 111111,
  "domain_id": "MLA-CELLPHONES",
  "attributes": [
    {
      "id": "BRAND",
      "name": "Marca",
      "values": [
        {
          "id": "59387",
          "name": "Xiaomi",
          "struct": null
        }
      ]
    },
    {
      "id": "LINE",
      "name": "Línea",
      "values": [
        {
          "id": "199791",
          "name": "Redmi",
          "struct": null
        }
      ]
    }
  ],
  "pictures": [
    {
      "id": "667092-MLA29115232412_012019",
      "url": "http://http2.mlstatic.com/D_667092-MLA29115232412_012019-O.jpg",
      "secure_url": "https://http2.mlstatic.com/D_667092-MLA29115232412_012019-O.jpg",
      "size": "500x375"
    }
  ],
  "tags": [
    "test_suggestion"
  ],
  "date_created": "2021-06-08T18:49:08Z",
  "last_updated": "2021-06-30T17:51:08Z"
}

Criar descrição

Este recurso pode ser usado para criar a descrição do produto relacionado a uma sugestão feita, deve ser somado a descrição todo o detalhe do item.

Exemplo:

curl -X POST-H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -d
{    
    "plain_text": "Texto de la Descripción"
        
}
https://api.mercadolibre.com/catalog_suggestions

Resposta: HTTP status 200 OK.

Modificar descrição

Com este recurso poderá ser feita a modificação de uma descrição que foi enviada para uma sugestão antes criada.

Chamada:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/catalog_suggestions/$SUGGESTION_ID/descriptions

Exemplo:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'Content-Type: application/json' -d 
{
  "plain_text": "Texto de la Descripción"
}
https://api.mercadolibre.com/catalog_suggestions

Resposta: HTTP status 200 OK.


Obter resultado das validações

Dado um suggestion_id é possível validar o resultado das validações internas de produtos padrões, que tenham finalizado até o momento.

Chamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/catalog_suggestions/$SUGGESTION_ID/validations

Exemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/catalog_suggestions/123456/validations

Resposta:

{
    "validations": [
          {
              "department": "quality",
              "cause_id": 3025,
              "type": "error",
              "code": "InvalidProcessingPicture",
              "references": [
                "suggestion.pictures"
              ],
              "message": "Ocurrió un error procesando la foto. Por favor cargala nuevamente"
          },
          {
              "department": "quality",
              "cause_id": 3025,
              "type": "error",
              "code": "InvalidProcessingPicture",
              "references": [
                "suggestion.pictures"
              ],
              "message": "Ocurrió un error procesando la foto. Por favor cargala nuevamente"
          },
          {
              "department": "quality",
              "cause_id": 3074,
              "type": "error",
              "code": "ProductIdentifierMissing",
              "references": [
                "suggestion.attributes"
              ],
              "message": "El campo \"Código universal de producto\" es obligatorio y no está cargado."
          }
    ]
}

Modificar sugestão

Se deseja modificar uma sugestão enviada, deve realizar o seguinte PUT:

Chamada:

curl -X PUT-H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/catalog_suggestions/$SUGGESTION_ID

Exemplo:

curl -X PUT-H 'Authorization: Bearer $ACCESS_TOKEN' -H "Content-Type: application/json" -d
{
    "title": "Titulo a modificar",
    "attributes": [
      {
        "id": "BRAND",
        "name": "Marca",
        "values": [
          {
            "id": "11111",
            "name": "Xiaomi 1",
            "struct": null
          }
        ]
      },
      {
        "id": "LINE",
        "values": [
          {
            "id": "199791",
            "name": "Redmi",
            "struct": null
           }
        ]
      }
    ],
    "pictures": [
      {
        "id": "647954-MLA46144073729_052021"
      }
    ]
  }

Resposta:

{
  "id": "MLA1103361143",
  "site_id": "MLA",
  "status": "WAITING_FOR_FIX",
  "title": "Titulo A Modificar",
  "seller_id": 818222588,
  "domain_id": "MLA-GAME_CONSOLES",
  "attributes": [
    {
      "id": "BRAND",
      "name": "Marca",
      "values": [
        {
          "id": "11111",
          "name": "Xiaomi 1"
        }
      ]
    },
    {
      "id": "LINE",
      "name": "Línea",
      "values": [
        {
          "id": "199791",
          "name": "Redmi"
         }
      ]
    },
    {
      "id": "MODEL",
      "name": "Modelo",     
      "values": [
        {
          "name": "juego 1"
         }
      ]
    }
  ],
  "pictures": [
    {
      "id": "647954-MLA46144073729_052021",
      "url": "ttp://mla-s1-p.mlstatic.com/647954-MLA46144073729_052021-O.jpg",
      "secure_url":"https://mla-s1-p.mlstatic.com/647954-MLA46144073729_052021-O.jpg",
      "size": "500x313"
    }
  ],
   "tags": [
      "test_suggestion"
  ],
  "date_created": "2021-09-14T20:38:36Z",
  "last_updated": "2021-09-24T17:43:36Z"
}

Listar sugestões

Temos este recurso que possibilita listar todas as sugestões criadas por um vendedor, trazendo alguns detalhes e status que a sugestão tem neste momento.

Exemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/catalog_suggestions/users/$USERID/suggestions/search

Resposta:

{
  "total": 1,
  "scroll_id": "YXBpY29yZS1pdGVtcy1zZWFyY2g=:ZHMtYXBpY29yZS1pdGVtcy0wNQ==:FGluY2x1ZGVfY29udGV4dF91dWlkDXF1ZXJ5QW5kRmV0Y2gBFDNmWU1xM29Cb2dhM2N3amFBREM0AAAAAA0NlNkWaDBFWTEzejVRb080N3RDTDVwbzlZdw==",
  "suggestions": [
    {
      "id": "MLA924694517",
      "site_id": "MLA",
      "status": "UNDER_REVIEW",
      "sub_status": "VALIDATING",
      "title": "Item De Test, No Ofertar",
      "seller_id": 772437317,
      "domain_id": "MLA-CELLPHONES",
      "attributes": [
        {
          "id": "BRAND",
          "name": "Marca",
          "values": [
            {
              "id": "59387",
              "name": "Xiaomi",
              "struct": null
            }
          ]
        },
        {
          "id": "LINE",
          "name": "Línea",
          "values": [
            {
              "id": "199791",
              "name": "Redmi",
              "struct": null
             }
          ]
        }
      ],
      "pictures": [
        {
          "id": "647954-MLA46144073729_052021",
          "url": "ttp://mla-s1-p.mlstatic.com/647954-MLA46144073729_052021-O.jpg",
          "secure_url":"https://mla-s1-p.mlstatic.com/647954-MLA46144073729_052021-O.jpg",
          "size": "500x313"
        }
      ]
    }
  ]
}

Filtros opcionais

  • scroll_id [string]: no caso de estar “scrolleando” através das sugestões de um usuário. Opcional.
  • limit [integer]: para configurar a quantidade de elementos a devolver no request. min: 10 max: 50 default: 50 Opcional.
  • offset [integer]: offset da busca, quer dizer, índice do primeiro elemento a retornar. O limit deveria se manter fixo durante toda a paginação, enquanto o que irá variando é o offset incrementando na mesma quantidade que o limit. Na resposta devolvemos o campo “total” com o qual se poderá guiar para saber até que valor pode incrementar o offset. Opcional.
  • search_type [scan|search]: search_type = scan devolve scroll_id para utilizar nos seguintes requests. default: search Opcional.
  • domain_ids [string[ ]: para filtrar as sugestões de determinados domínios. Opcional.
  • status [string]: para filtrar as sugestões com determinados status. Opcional.
  • title [string]: permite passar um título parcial e buscar sugestões cujo title faça match com o string. Opcional.

Erros

Error_code Mensagem de erro Descrição
400 Property [title] cannot be blank POST/PUT sem título da sugestão
400 Domain is not active Domínio inativo no Catálogo
400 User is not allowed to create products Usuário sem permissão para publicar
400 User is not allowed to create products from this brand Usuário sem permissão para publicar uma marca em especial
400 Attribute values must not be null Atributos com valores em null
400 Item has unprocessable tags Sugestão em um status não modificável
400 Domain is not modifiable Usuário tenta modificar o domínio de uma sugestão
400 Suggestion ${suggestion_id} can not be modified Status não permite mudança da descrição da sugestão
400 Suggestion ${suggestion_id} already has a description Sugestão já tem uma descrição criada
403 User {caller.id} not allowed to get validations for suggestion {suggestion_id} User não é dono da sugestão que solicita as validações

Habilitar Brand Central para usuários de teste

Para começar a usar e testar os recursos de BC com um usuário de teste, envie os dados do seu usuário de teste neste formulário.

banner footer

Inscreva-se em nosso Newsletter

ou registre-se para receber as últimas notícias sobre nossa API