Recursos Cross

Confira os principais recursos das nossas APIs
circulos azuis em degrade

Documentação do

Você pode usar esta documentação para as seguintes unidades de negócio:

Última atualização em 22/08/2023

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 rápida e melhorando este fluxo.

Notificações de status

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 está 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á está criado e ativo em nosso catálogo.
  • REJECTED: a sugestão foi recusada por motivos legais ou, porque o produto já está em nosso catálogo.

Quantidade de sugestões do 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 de usuário não permitido:

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

Domínios disponíveis

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, as 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 criar uma sugestão de produto, envie 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 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/${suggestion_id}/description

Resposta: HTTP status 200 OK.


Modificar descrição

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

Chamada:

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

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/${suggestion_id}/description

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 quiser modificar uma sugestão enviada, realize 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 esta marca
400 Attribute values must not be null Atributos com valores 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} Usuário não é dono da sugestão que solicita as validações

Habilitar para usuários de teste

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