Documentação do Mercado Livre
Confira todas as informações necessárias sobre as APIs Mercado Livre.
Documentação do
Compatibilidades entre itens e produtos de Autopeças
Verificar compatibilidade entre domínios
Antes de criar compatibilidade entre itens e produtos, verifique se os domínios e categorias do item e do produto são compatíveis.
Ao consultar o dump a seguir, a lista de domínios e categorias em que você pode ou precisa informar compatibilidades por site.
Chamada:
curl -X GET http://api.mercadolibre.com/catalog/dumps/domains/$SITE_ID/compatibilitiesExemplo de chamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/catalog/dumps/domains/MLM/compatibilitiesExemplo de resposta:
[
{
"domain_id": "MLM-AUTOMOTIVE_SHOCK_ABSORBERS",
"main": false,
"compatibilities": [
{
"compatible_domain_id": "MLM-CARS_AND_VANS_FOR_COMPATIBILITIES",
"type": "EXTENSION",
"required": false,
"restrictions": [],
"categories": [
{
"id": "MLM45878",
"required": true,
"note_status": "ENABLED",
"restrictions_status": "DISABLED",
"universal_status": "DISABLED"
}
]
}
]
},
…
}]
Os novos campos indicam:
- categories: categorias que suportam a compatibilidade de carregamento.
- required: categorias em que é obrigatório carregar compatibilidades.
- type: tipo de compatibilidade. Apenas o tipo EXTENSION suporta compatibilidades de carregamento.
- note_status e restrictions_status: indicam se a categoria permite reportar notas e restrições de posição.
- universal_status: indica se a categoria permite a comunicação de compatibilidades universais. ENABLED: permite a comunicação de compatibilidades universais ou DISABLED: não permite a comunicação de compatibilidades universais.
Obtenha mais informações de domínios, produtos e atributos de autopeças.
Contar produtos de um domínio
Para verificar o número de produtos existentes por domínio (família de produtos) que atendem a certos atributos e valores, você pode executar o seguinte POST. Isso permitirá que você valide, antes de adicionar as compatibilidades, a quantidade de produtos e evite erros nas atribuições de compatibilidade.
Isso é importante, pois apenas um máximo de 200 produtos podem ser atribuídos por chamada.
Chamada:
curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/catalog_compatibilities/products_search/count_family_products
{
"domain_id": "$domainId",
"attributes": [{
"id": "$attributeId1",
"value_id": "$valueId1"
}, {
"id": "$attributeId2",
"value_name": "$valueName2"
}]
}Exemplo:
curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/catalog_compatibilities/products_search/count_family_products
{
"domain_id": "MLM-CARS_AND_VANS_FOR_COMPATIBILITIES",
"attributes": [{
"id": "BRAND",
"value_name": "Volkswagen"
},
{
"id": "CAR_AND_VAN_MODEL",
"value_name": "VENTO"
}
]
}Resposta:
{
"count":141
}Identifique itens que exigem compatibilidade
Com o seguinte recurso através da tag incomplete_compatibilities você pode identificar os itens que requerem compatibilidades obrigatórias para evitar moderação.
Chamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/$ITEM_IDExemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/MLA1417560910Resposta:
{
"id": "MLA743626587",
"site_id": "MLA",
"title": "Paragolpe Trasero Peugeot 307 Linea Nueva 5 Puertas",
"seller_id": 65711207,
"category_id": "MLA60954",
"official_store_id": null,
.
.
.
.
"tags": [
"good_quality_picture",
"brand_verified",
"loyalty_discount_eligible",
"good_quality_thumbnail",
"ahora-paid-by-buyer",
"incomplete_compatibilities",
"immediate_payment"
],
"warranty": "CON GARANTIA DEL FABRICANTE",
"catalog_product_id": null,
"domain_id": "MLA-VEHICLE_REAR_BUMPERS",
"parent_item_id": null,
"deal_ids": [
],
"automatic_relist": false,
"date_created": "2018-08-17T20:36:54.000Z",
"last_updated": "2023-12-15T17:18:35.000Z",
"health": 0.83,
"catalog_listing": false
}
Filtrar itens que exigem compatibilidade
Chamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/$SELLER_ID/items/search?tags=incomplete_compatibilitiesExemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/$SELLER_ID/items/search?tags=incomplete_compatibilitiesResposta:
{
"seller_id": "1373279576",
"results": [
"MLA1417560910",
"MLA1373565211",
"MLA1371734513",
"MLA1396609243"
],
"paging": {
"limit": 50,
"offset": 0,
"total": 4
},
"query": null,
.
.
.
.
}
Identifique itens com sugestões de compatibilidade
Com o seguinte recurso, você poderá encontrar a lista de todos os itens do vendedor que têm sugestões de compatibilidade, ou seja, que têm tag “pending_compatibilities”.
Chamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/$SELLER_ID/items/search?tags=pending_compatibilitiesExemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/1695976736/items/search?tags=pending_compatibilitiesResposta:
{
"seller_id": "1373279576",
"results": [
"MLB4462690924"
],
"paging": {
"limit": 50,
"offset": 0,
"total": 4
},
"query": null,
.
.
.
.
}
Com a seguinte chamada e através da tag pending_compatibilities encontrada na resposta, é possível identificar para um item específico se este tem sugestões de compatibilidades.
Chamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/$ITEM_IDExemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/MLB4462690924Resposta:
{
"id": "MLB4462690924",
"site_id": "MLB",
"title": "Pastilha Freio Dianteira Gm Blazer 4.3 V6 Mpfi 1996 À 2003 ",
"seller_id": 1695976736,
"category_id": "MLB439261",
"official_store_id": null,
.
.
.
.
.
"tags": [
"pending_compatibilities"
],
"catalog_product_id": "MLB31779615",
"domain_id": "MLB-VEHICLE_BRAKE_PADS",
"parent_item_id": null,
"deal_ids": [
],
"automatic_relist": false,
"date_created": "2024-02-22T16:51:37.577Z",
"last_updated": "2024-03-22T20:49:39.772Z",
"health": 0.75,
"catalog_listing": false
}
Filtrar ítems que tienen compatibilidades sugeridas.
Obter o número de sugestões e reclamações
Com o seguinte recurso, pode descobrir o número de sugestões de compatibilidade e de reclamações de uma determinada publicação.
Chamada:
curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/catalog_domains/$DOMAIN_ID/compatibilities/cardsExemplo:
curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'Content-Type: application/json' -d
{
"item_id": "MLB4462690924",
"product_id": "MLB31779615",
"filters": ["REPUTATION", "SUGGESTED"]
}
https://api.mercadolibre.com/catalog_domains/MLB-CARS_AND_VANS/compatibilities/cards
Atributos request
- item_id: atributo obrigatório que corresponde ao identificador do item.
- product_id: atributo que corresponde ao produto que está associado ao item, é opcional, porém o desempenho e o tempo de resposta são melhorados quando este atributo é informado.
- filters: atributo obrigatório para indicar se deseja obter o número de reclamações ["REPUTATION"], o número de sugestões de compatibilidade ["SUGGESTED"] que o item possui; ou ambos ["REPUTATION", "SUGGESTED"].
Resposta:
[
{
"title": "Tienes 293 vehículos sugeridos pendientes por agregar",
"subtitle": "Identificamos vehículos compatibles con tu producto que te ayudarán a vender más",
"filter": "SUGGESTED",
"quantity": 293
},
{
"title": "Vehículos con reclamos por incompatibilidad",
"subtitle": "Revisalos y eliminalos para evitar nuevos reclamos.",
"filter": "REPUTATION",
"quantity": 1
}
]
Reputation: são todas as compatibilidades que estão a gerando reclamações.
Suggested: são todos os casos de novas compatibilidades sugeridas às suas publicações.
Se você deseja saber como obter as compatibilidades sugeridas para cada item você pode ver mais detalhes em identificar as compatibilidades sugeridas.
Se quiser saber quais são as compatibilidades problemáticas que estão gerando reclamações e afetando a reputação do vendedor, pode ver mais detalhes em Conhecer compatibilidades que geram reclamações.
Adicionar compatibilidades
Para adicionar compatibilidades de um item a um produto e / ou domínio, você pode consultar até um máximo de 200 produtos por chamada (incluindo os definidos nos domínios) e fazê-lo de três maneiras diferentes:
- Por produto: para adicionar novas compatibilidades a um item, você deve enviar as compatibilidades que deseja adicionar. Não é necessário enviar os existentes para manter os atuais.
- Por domínios de produto: você pode especificar um conjunto de atributos que definem um domínio de produto. Para cada domínio, você deve especificar seu domínio e, para cada atributo, um valor que consiste em id e/ou name.
- Por produto e domínio: você pode adicionar compatibilidades a um item publicado de outro produto e a um dominio de produtos, ou seja permite adicionar conjuntamente os 2 primeiros.
Valores possíveis para uma restrição de posição
Ao adicionar uma compatibilidade poderá também indicar a restrição de posição da mesma, que com a chamada seguinte poderá conhecer os valores possíveis para a informar.
Chamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' http://api.mercadolibre.com/catalog_compatibilities/restrictions/values?main_domain_id=MLB-CARS_AND_VANS&secondary_domain_id=MLB-VEHICLE_SHOCK_ABSORBERSRespuesta:
{
"attributes_values": [
{
"attribute_id": "POSITION",
"values":
[
{
"value_id": "23536",
"value_name": "Superior",
},
{
"value_id": "23537",
"value_name": "Inferior"
}
]
}
]
}
Adicionar por produto
Para adicionar uma compatibilidade com um ou mais produtos individuais, você pode usar o buscador de produtos.
Chamada:
curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/$ITEM_ID/compatibilities
{
"products": [{
"id": "$PRODUCTIID",
"note": "texto",
"restrictions": [{
"attribute_id": "POSITION",
"attribute_values":
[{
"values":[{"value_id": "$VALUE_ID","value_name": "$VALUE_NAME"}]
},
{
"values":[{"value_id": "$VALUE_ID","value_name": "$VALUE_NAME"},
{"value_id": "$VALUE_ID","value_name": "$VALUE_NAME"}]
}
]
}]
}]
}
Exemplo:
curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/$ITEM_ID/compatibilities
{
"products": [{
"id": "MLB155254",
"note": "Modelos posteriores a Mayo de 2018",
"restrictions": [{
"attribute_id": "POSITION",
"attribute_values":
[{
"values":[{"value_id": "12456","value_name": "Delantero"}]
},
{
"values":[{"value_id": "65432","value_name": "Trasero"},
{"value_id": "87675","value_name": "Inferior"}]
}
]
}]
}]
}
Resposta:
{
"created_compatibilities_count": 72
}
Também é possível adicionar uma nota e restrições de posição a mais de uma compatibilidade, para isso é necessário substituir o nodo products por products_group, exemplo:
Chamada:
curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/$ITEM_ID/compatibilities
{
"products_group": [{
"ids": ["MLB155254", "MLB155255"],
"note": "texto",
"restrictions": [{
"attribute_id": "POSITION",
"attribute_values":
[{
"values":[{"value_id": "$VALUE_ID","value_name": "$VALUE_NAME"}]
},
{
"values":[{"value_id": "$VALUE_ID","value_name": "$VALUE_NAME"},
{"value_id": "$VALUE_ID","value_name": "$VALUE_NAME"}]
}
]
}]
}]
}
Adicionar por domínio de produto
Para adicionar compatibilidades definidas por um grupo de atributos que determinam um domínio, conheça os domínios e atributos das autopeças.
Chamada:
curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/$ITEM_ID/compatibilities
{
"products_families": [{
"domain_id": "$DOMAIN_ID",
"attributes": [{
"id": "$ATTRIBUTE_ID",
"value_id": "$VALUE_ID"
},
{
"id": "$ATTRIBUTE_ID",
"value_id": "$VALUE_ID"
},
],
"note": "Texto",
"restrictions":
[{
"attribute_id": "POSITION",
"attribute_values":
[{
"values":[{"value_id": "$VALUE_ID","value_name": "$VALUE_NAME"}]
},
{
"values":[{"value_id": "$VALUE_ID","value_name": "$VALUE_NAME"},
{"value_id": "$VALUE_ID","value_name": "$VALUE_NAME"}]
}
]
}]
}
Exemplo (exceto MLM):
curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/MLA794706391/compatibilities
{
"products_families": [{
"domain_id": "MLA-CARS_AND_VANS",
"attributes": [{
"id": "BRAND",
"value_id": "60249"
},
{
"id": "YEAR",
"value_name": "2010"
},
],
"note": "Solamente para vehículos de fabricación Europea",
"restrictions":
[{
"attribute_id": "POSITION",
"attribute_values":
[{
"values":[{"value_id": "12456","value_name": "Delantero"}]
},
{
"values":[{"value_id": "65432","value_name": "Trasero"},
{"value_id": "87675","value_name": "Inferior"}]
}
]
}]
}
Resposta:
{
"created_compatibilities_count": 23
}
Exemplo MLM:
curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/MLM794706391/compatibilities
{
"products_families": [{
"domain_id": "MLM-CARS_AND_VANS_FOR_COMPATIBILITIES",
"attributes": [{
"id": "DRIVE_TYPE",
"value_id": "8182649"
},
{
"id": "CAR_AND_VAN_BODY_TYPE",
"value_id": "8183109"
},
{
"id": "YEAR",
"value_name": "2010"
}
],
"note": "Solamente para vehículos de fabricación Europea",
"restrictions":
[{
"attribute_id": "POSITION",
"attribute_values":
[{
"values":[{"value_id": "12456","value_name": "Delantero"}]
},
{
"values":[{"value_id": "65432","value_name": "Trasero"},
{"value_id": "87675","value_name": "Inferior"}]
}
]
}
]
}Resposta:
{
"created_compatibilities_count": 23
}
Associar por produto e domínio de produtos
Chamada:
curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/$ITEM_ID/compatibilities
{
"products": [{
id": "$PRODUCTIID",
"note": "texto",
"restrictions": [{
"attribute_id": "POSITION",
"attribute_values":
[{
"values":[{"value_id": "$VALUE_ID","value_name": "$VALUE_NAME"}]
},
{
"values":[{"value_id": "$VALUE_ID","value_name": "$VALUE_NAME"},
{"value_id": "$VALUE_ID","value_name": "$VALUE_NAME"}]
}
]
}],
"products_families": [{
"domain_id": "$DOMAIN_ID",
"attributes": [{
"id": "ATTRIBUTE_ID",
"value_id": "$VALUE_ID"
},
{
"id": "ATTRIBUTE_ID",
"value_id": "$VALUE_ID"
},
],
"note": "Texto",
"restrictions":
[{
"attribute_id": "POSITION",
"attribute_values":
[{
"values":[{"value_id": "$VALUE_ID","value_name": "$VALUE_NAME"}]
},
{
"values":[{"value_id": "$VALUE_ID","value_name": "$VALUE_NAME"},
{"value_id": "$VALUE_ID","value_name": "$VALUE_NAME"}]
}
]
}]
}
Exemplo:
curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/MLM794706391/compatibilities
{
"products": [{
"id": "MLB155254",
"note": "Modelos posteriores a Mayo de 2018",
"restrictions": []
}],
"products_families": [{
"domain_id": "MLB-CARS_AND_VANS",
"attributes": [{
"id": "BRAND",
"value_id": "60249"
},
{
"id": "YEAR",
"value_name": "2010"
},
],
"note": "Solamente para vehículos de fabricación Europea",
"restrictions":
[{
"attribute_id": "POSITION",
"attribute_values":
[{
"values":[{"value_id": "12456","value_name": "Delantero"}]
},
{
"values":[{"value_id": "65432","value_name": "Trasero"},
{"value_id": "87675","value_name": "Inferior"}]
}
]
}]
}
No campo note não permitimos até 500 caracteres e o texto é moderado.
Resposta:
{
"created_compatibilities_count": 23
}
Possíveis erros
400: validações de consistência:
- Os campos obrigatórios estão incompletos.
- O formato dos IDs está incorreto.
- Mais de 200 produtos foram encontrados e / ou especificados para as famílias de produtos.
- Mais de 10 domínios de produto foram especificados.
- Os produtos e / ou domínios não pertencem ao mesmo site que o item.
- Todos os produtos devem ser children.
- O domínio do item é compatível com os domínios dos produtos especificados e/ou com os domínios especificados nas famílias de produtos especificadas.
- Não pode haver mais de 4 posições configuradas em uma restrição de posição.
- Cada restrição de posição pode ter no máximo 4 ids.
- Os ids devem pertencer ao conjunto fechado de ids definidos.
- A combinação de valores deve ser única, ou seja, não pode haver duas listas de ids iguais em uma restrição de posição.
- A categoria do item deve ter notas e restrições de posição habilitadas.
- A nota não pode exceder 500 caracteres.
403: token inválido ou falta de permissões no item.
404: o item, produtos ou domínios especificados não existem.
Copiar e colar compatibilidades
O primeiro passo para copiar as compatibilidades é obter uma lista dos itens ativos que possuem compatibilidades configuradas. Para isso, é necessário começar obtendo todos os itens ativos do vendedor utilizando a seguinte consulta:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' \
"https://api.mercadolibre.com/users/$USER_ID/items/search?status=active"
Uma vez obtidos os itens ativos, é necessário identificar aqueles que possuem compatibilidades. Para isso, faça uma consulta ao endpoint /items e verifique se o item contém o atributo "HAS_COMPATIBILITIES".
Para obter a lista de itens com a quantidade de compatibilidades, notas e posições, faça a seguinte chamada:
curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/compatibilities_summary
{
"domain_id": "$domainId",
"items": [
"$item_id",
"item_id",
"item_id"
]
}
'
Exemplo:
curl --location 'https://api.mercadolibre.com/items/compatibilities_summary' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data '{
"domain_id": "MLB-CARS_AND_VANS",
"items": [
"MLB4816242302",
"MLB3845318745",
"MLB3845318797"
]
}
Resposta:
[
{
"item_id": "MLB4816242302",
"item_title": "Pastilha Dianteira Anuncio De Teste 2",
"compatibilities_count": 1001,
"compatibilities_claims_count": 0,
"notes_count": 65,
"restrictions_count": 64
},
{
"item_id": "MLB3845318797",
"item_title": "Pastilha Dianteira Anuncio De Teste",
"compatibilities_count": 400,
"compatibilities_claims_count": 0,
"notes_count": 64,
"restrictions_count": 64
},
{
"item_id": "MLB3845318745",
"item_title": "Pastilha Dianteira Anuncio De Teste",
"compatibilities_count": 200,
"compatibilities_claims_count": 0,
"notes_count": 64,
"restrictions_count": 64
}
]
Para copiar as compatibilidades de um item para um item sem compatibilidades carregadas, faça a seguinte chamada:
curl --location 'https://api.mercadolibre.com/items/$ITEM_ID/compatibilities' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data '{
"item_to_copy": {
"item_id": "$ITEM_ID",
"extended_information": true
}
}'
Exemplo:
curl --location 'https://api.mercadolibre.com/items/MLB3863097751/compatibilities' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data '{
"item_to_copy": {
"item_id": "MLB4816242302",
"extended_information": true
}
}'
Respuesta:
200 OKPara copiar as compatibilidades de um item para um item que já possui compatibilidades carregadas, faça a seguinte chamada:
curl --location --request PUT 'https://api.mercadolibre.com/items/$ITEM_ID/compatibilities' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data '{
"create": {
"item_to_copy": {
"item_id": "$ITEM_ID",
"extended_information": true
}
}
}
Exemplo:
curl --location --request PUT 'https://api.mercadolibre.com/items/MLB3863034063/compatibilities' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data '{
"create": {
"item_to_copy": {
"item_id": "MLB4816242302",
"extended_information": true
}
}
}
'
Resposta:
{
"create": {
"products": [
{
"id": "MLB7864691",
"note": "frente",
"restrictions": [
{
"attribute_id": "POSITION",
"attribute_code": 1,
"attribute_values": [
{
"values": [
{
"value_id": "13701104",
"value_code": 5
}
]
}
]
}
]
},
.
.
.
"universal": false,
"item_to_copy": {
"item_id": "MLB4816242302",
"extended_information": true
}
}
}
Considerações
- Sem compatibilidades: Copia todas as compatibilidades da publicação de origem.
- Com compatibilidades: Realiza uma comparação entre as duas publicações e copia apenas os veículos da publicação de origem que ainda não estão na de destino.
Adicionar compatibilidade universal
Para indicar que um item é compatível com qualquer produto, dentro da solicitação, existe um campo universal que deve ser informado em true. Isso indica que esse item é universal (portanto, nenhuma compatibilidade deve ser associada a ele, pois ele é compatível com todos os produtos do mesmo domínio).
Ao indicar uma compatibilidade universal, não é possível especificar produtos e famílias. Se ambos os campos forem enviados, será devolvido um erro.
Chamada:
curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/$ITEM_ID/compatibilities
{
"products": [],
"products_families": [],
"products_group": [],
"universal": true
}
Exemplo:
curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/MLM12456789/compatibilities
{
"products": [],
"products_families": [],
"products_group": [],
"universal": true,
}
Resposta:
{
"created_compatibilities_count": 1
}
Possíveis erros ao atribuir compatibilidades universais
400: validação de consistência:
- Message: "Invalid arguments for specific request. Please check details to satisfy validations".
- Details: "at least one of products, products_groups, products_families or universal must be specified, if universal no products can be specified".
- Message: Item has compatibilities and these must be removed before setting it as universal.
- Message: There is no configured compatibility for the category $CATEGORY_ID
- Message: Item has universal setting and must be removed before creating compatibilities.
403: token inválido ou falta de permissões para o item.
404: o item não existe.
Atualizar compatibilidadess
Com este método, é possível criar, atualizar e eliminar compatibilidades, notas e restrições de um item, utilizando a mesma estrutura de dados que a criação de compatibilidades. Essa ação pode ser realizada para uma ou múltiplas compatibilidades.
Chamada:
curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN'
https://api.mercadolibre.com/items/$ITEM_ID/compatibilities?/code>Exemplo para criar e eliminar compatibilidades:
curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'Content-Type: application/json' -d
'{
"create": {
"products": [
{
"id": "MLB22015088"
}
],
"products_families": [
{
"domain_id": "MLB-CARS_AND_VANS",
"attributes": [
{
"id": "BRAND",
"value_id": "60249"
},
{
"id": "MODEL",
"value_name": "Gol"
},
{
"id": "YEAR",
"value_name": "2023"
}
]
}
]
},
"delete": {
"products": [
{
"id": "MLB22015074"
},
{
"id": "MLB7427549"
}
],
"products_families": [
{
"domain_id": "MLB-CARS_AND_VANS",
"attributes": [
{
"id": "BRAND",
"value_id": "60249"
},
{
"id": "MODEL",
"value_id": "62109"
},
{
"id": "YEAR",
"value_name": "2023"
}
]
}
]
}
}
Resposta:
{
"create": {
"products": [
{
"id": "MLB22015088"
}
],
"products_families": [
{
"domain_id": "MLB-CARS_AND_VANS",
"attributes": [
{
"id": "BRAND",
"value_id": "60249"
},
{
"id": "MODEL",
"value_name": "Gol"
},
{
"id": "YEAR",
"value_name": "2023"
}
]
}
],
"universal": false
},
"delete": {
"products": [
{
"id": "MLB22015074"
},
{
"id": "MLB7427549"
}
],
"products_families": [
{
"domain_id": "MLB-CARS_AND_VANS",
"attributes": [
{
"id": "BRAND",
"value_id": "60249"
},
{
"id": "MODEL",
"value_id": "62109"
},
{
"id": "YEAR",
"value_name": "2023"
}
]
}
],
"universal": false
}
}
Exemplo para criar e atualizar compatibilidades com notas e/ou restrições:
curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' -H 'Content-Type: application/json' -d
'{
"create": {
"products": [
{
"id": "MLB28049481",
"note": "nota para teste",
"restrictions": []
}
],
"products_families": [
{
"domain_id": "MLB-CARS_AND_VANS",
"attributes": [
{
"id": "BRAND",
"value_id": "60395"
},
{
"id": "MODEL",
"value_ids": [
"389577",
"16696"
]
}
]
}
]
},
"update": {
"products": [
{
"id": "MLB22567898",
"note": "nota para teste 10",
"restrictions": [
{
"attribute_id": "POSITION",
"attribute_values": [
{
"values": [
{
"value_id": "13701104",
"value_name": "Dianteira"
}
]
}
]
}
]
}
],
"products_families": [
{
"domain_id": "MLB-CARS_AND_VANS",
"attributes": [
{
"id": "BRAND",
"value_id": "67781"
},
{
"id": "MODEL",
"value_name": "ARGO"
}
],
"note": "somente as versões de freios traseiros",
"restrictions": [
{
"attribute_id": "POSITION",
"attribute_values": [
{
"values": [
{
"value_id": "13701104",
"value_name": "Dianteira"
}
]
}
]
}
]
}
]
}
}
Resposta:
{
"create": {
"products": [
{
"id": "MLB28049481",
"note": "nota para teste",
"restrictions": []
}
],
"products_families": [
{
"domain_id": "MLB-CARS_AND_VANS",
"attributes": [
{
"id": "BRAND",
"value_id": "60395"
},
{
"id": "MODEL",
"value_ids": [
"389577",
"16696"
]
}
]
}
],
"universal": false
},
"update": {
"products": [
{
"id": "MLB22567898",
"note": "nota para teste 10",
"restrictions": [
{
"attribute_id": "POSITION",
"attribute_code": 1,
"attribute_values": [
{
"values": [
{
"value_id": "13701104",
"value_name": "Dianteira",
"value_code": 5
}
]
}
]
}
]
}
],
"products_families": [
{
"domain_id": "MLB-CARS_AND_VANS",
"attributes": [
{
"id": "BRAND",
"value_id": "67781"
},
{
"id": "MODEL",
"value_name": "ARGO"
}
],
"note": "somente as versões de freios traseiros",
"restrictions": [
{
"attribute_id": "POSITION",
"attribute_code": 1,
"attribute_values": [
{
"values": [
{
"value_id": "13701104",
"value_name": "Dianteira",
"value_code": 5
}
]
}
]
}
]
}
],
"universal": false
}
}
Possíveis erros:
400 - Validações de consistência::
- Preenchimento completo dos campos obrigatórios
- Correção no formato dos ids.
- Produtos e/ou domínios pertencem ao mesmo site que o item.
- O domínio do item é compatível com os domínios dos produtos especificados.
- Foi excedido o máximo de 200 produtos para uma única solicitação.
403: Caller id não tem permissões sobre o item.
404: Item ou algum dos produtos não existe.
Alterar ou eliminar notas e restrição de posição
Para alterar ou apagar uma nota e restrição de posição, execute um PUT no recurso de informar compatibilidades alterando as informações que você precisa no campo update. Para deletar uma ou ambas informações, deve enviar o campo note e/ou array de restrictions vazio. No exemplo abaixo ambos campos são eliminados.
Exemplo:
curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/$ITEM_ID/compatibilities
{
"update": {
"products": [{
"id": "MLB155254",
"note": "",
"restrictions":[]
}
]
}
}
Identifique itens compatíveis
Com o próximo recurso você pode identificar que um item já é compatível através do atributo id = “HAS_COMPATIBILITIES”. Caso este atributo não seja observado na saída da chamada, significa que o item não possui compatibilidades informadas.
Chamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/$ITEM_IDExemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/MLA1417560910Resposta:
{
"id": "MLA1417560910",
"site_id": "MLA",
"title": "Interruptor Columna (palanca) Tamatel 15104 - No Ofertar",
"seller_id": 1373279576,
"category_id": "MLA435058",
.
.
.
.
"attributes": [
{
"id": "HAS_COMPATIBILITIES",
"name": "Tiene compatibilidades",
"value_id": "242085",
"value_name": "Sí",
"values": [],
"value_type": "boolean"
},
{},
{}
],
.
.
.
}
Listar compatibilidades
Com esse recurso, é possível listar todas as compatibilidades para um item específico.
Obter todas as compatibilidades de um item
Chamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/$ITEM_ID/compatibilities?extended=trueAtributos:
- Extended: quando o valor é “true” retornará os detalhes das notas e posições.
Exemplo de chamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/MLM794706391/compatibilities?extended=trueExemplo de resposta:
{
"products": [
{
"id": "bcbd413f-cd65-0e0f-88c9-5eb4aebb5372",
"domain_id": "MLM-CARS_AND_VANS_FOR_COMPATIBILITIES",
"catalog_product_id": "MLM15847548",
"catalog_product_name": "Volkswagen Jetta 2010 GLI Manual 5",
"source": "SELLER",
"note": "Solo modelos de caja automática"
},
{
"id": "58bd413f-cd65-a719-9570-2ca8f2b528af",
"domain_id": "MLM-CARS_AND_VANS_FOR_COMPATIBILITIES",
"catalog_product_id": "MLM15847546",
"catalog_product_name": "Volkswagen Jetta 2010 GLI Automática 6",
"source": "SELLER",
"note": "Modelos posteriores a Junio 2010",
"restrictions":
[{
"attribute_id": "POSITION",
"attribute_values":
[{
"values":[{"value_id": "12456","value_name": "Delantero"}]
},
{
"values":[{"value_id": "65432","value_name": "Trasero"},
{"value_id": "87675","value_name": "Inferior"}]
}]
}],
"reputation:" {
"level": "RED",
"total_claims": 2
}
}
],
"catalog_compatibilities_count": 15
}Campos de respuesta
- products: array com todos os veículos (compatibilidades) informados pelo vendedor.
- ID: ID da compatibilidade.
- domain_id: domínio principal do produto.
- catalog_product_id: ID do produto do domínio principal.
- catalog_product_name: nome do produto de domínio principal.
- source: fluxo de origem de compatibilidade..
- note: especificação das condições de compatibilidade entre o item e o produto principal.
- restrictions: restrições de compatibilidade entre item e produto principal (por exemplo, posição de instalação da peça).
- reputation: cor e total de veículos que geraram reclamações.
- level: assumirá o valor RED para compatibilidades com um elevado número de reclamações de incompatibilidade.
- total claims: número de reclamações de incompatibilidade relacionadas à compatibilidade.
Obter as compatibilidades de um item universal
Caso o item seja configurado como universal, a resposta um campo adicional chamado universal é adicionado, contendo uma lista de domínios principais com os quais o item é compatível.
Exemplo de resposta:
{
"universal": {
“domain_ids”: [“MLM_CARS_AND_VANS_FOR_COMPATIBILITIES”]
}
}
Obter uma compatibilidade específica de um item por seu ID
Chamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/$ITEM_ID/compatibilities/$compatibility_idExemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/MLM794706391/compatibilities/$compatibility_idResposta:
{
"id": "bcbd413f-cd65-0e0f-88c9-5eb4aebb5372",
"domain_id": "MLM-CARS_AND_VANS_FOR_COMPATIBILITIES",
"catalog_product_id": "MLM15847548",
"catalog_product_name": "Volkswagen Jetta 2010 GLI Manual 5",
"note": "Solo para versiones con frenos a disco en las ruedas traseras",
"note_status": "PENDING",
"restrictions": [{
"attribute_id": "POSITION",
"attribute_values":
[{
"values":[{"value_id": "12456","value_name": "Delantero"}]
}]
}],
"reputation:" {
"level": "RED",
"total_claims": 2
}
}As notas só aparecem no front do item no status APPROVED ou CHECKED.
Um erro 404 significa que o item ou a compatibilidade não existe.
Obtenha uma nota de compatibilidade
Chamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/$ITEM_ID/compatibilities/$COMPATIBILITY_ID/note
Exemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/MLM12456789/compatibilities/bcbd413f-cd65-0e0f-88c9-5eb4aebb5372/noteResposta:
{
"note": "Solo para versiones con frenos a disco en las ruedas traseras"
}
Eliminar compatibilidades
Se você associou uma compatibilidade incorreta ao item, é possível removê-lo desde que o vendedor o tenha feito.
Eliminar uma compatibilidade específica para o item indicado
Chamada:
curl -X DELETE -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/$ITEM_ID/compatibilities/$COMPATIBILITY_IDExemplo:
curl -X DELETE -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/MLM794706391/compatibilities/4cb9af35-8e9b-ebfd-9e7f-2245ac363d10A resposta será um http 200.
Eliminar compatibilidades para um item
Chamada:
curl -X DELETE -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/$ITEM_ID/compatibilitiesExemplo:
curl -X DELETE -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/MLM794706391/compatibilitiesResposta:
{
"deleted_compatibilities": [
"d0ba2aeb-7409-0037-7b23-0b91266fd00e",
"72ba233d-16d8-218b-4062-7a97dab166c8"
]
}Eliminar compatibilidades para um domínio de um item
Chamada:
curl -X DELETE -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/$ITEM_ID/compatibilities
{
"products_families": [{
"domain_id": "$domain_id",
"attributes": [{
"id": "$attribute_id1",
"values":[{
"id": "$value_id1",
"name": "$value_name1"
}]
},{
"id": "$attribute_id2",
"values":[{
"id": "$value_id1",
"name": "$value_name1"
}]
}]
}]
}
Exemplo:
curl -X DELETE -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/MLM794706391/compatibilities
{
"products_families": [{
"domain_id": "MLM-CARS_AND_VANS_FOR_COMPATIBILITIES",
"attributes": [{
"id": "DRIVE_TYPE",
"value_id": "8182649"
},
{
"id": "CAR_AND_VAN_BODY_TYPE",
"value_id": "8183109"
},
{
"id": "YEAR",
"value_name": "2010"
}]
}]
}
Resposta:
{
"deleted_compatibilities": [
"d0ba2aeb-7409-0037-7b23-0b91266fd00e",
"72ba233d-16d8-218b-4062-7a97dab166c8"
]
}Possíveis erros
400: formato incorreto / mais de 200 produtos para o domínio especificado / mais de 10 domínios especificados.
403: token inválido, o falta de permissões sobre o ítem.
404: o ítem ou a compatibilidade não existem.
Como informar exceções
Em casos de Peças de carros e caminhonetes, em que a categoria exige a informação de compatibilidades, mas não encontra nenhum veículo, modelo ou versão disponível no catálogo. Estes itens fazem parte do fluxo de exceções e para informá-los, disponibilizamos o seguinte recurso:
Chamada:
curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/$item_id/compatibilities/exception
{
"comment": “texto livre com um máximo de 255 caracteres”
}
Exemplo:
curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/MLB12345678/compatibilities/exception
{
"comment": “texto livre com um máximo de 255 caracteres” [Requerido]
}
Resposta:
200 OKPossíveis erros
400: o item está finalizado ou inativo.
400: o item tem compatibilidades existentes.
400: a categoria do item não tem compatibilidades.
400: o item tem uma exceção de compatibilidade existente.
400: comentário necessário.
Consultar se um item tem exceções
Chamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/$item_id/compatibilities/exceptionExemplo:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/MLB12345678/compatibilities/exception
Resposta:
{
"has_exception": true/false
}
- Devolve true apenas quando o item não tem nenhuma compatibilidade carregada e foi informada uma exceção.
- Devolve false sempre que um item tem ao menos um veículo informado como compatível (independentemente se foi informada exceção ou não).
Conhecer compatibilidades que geram reclamações
Para que você possa corrigir as compatibilidades indicadas incorretamente, com o seguinte endpoint você poderá identificar o automóvel escolhido pelo comprador a partir do momento em que é gerada uma reclamação de incompatibilidade.
Chamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/compats-snapshots/orders/$ORDER_IDExemplos:
Ordem com reclamação onde o comprador selecionou diferentes filtros durante a compra do produto e foi confirmado que o produto selecionado "Sim, era compatível" com o item (compatibility_status.compatibility = CONFIRMED)
Chamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/compats-snapshots/orders/2000006372967416Response:
{
"item_id": "MLM2187940074",
"product_id": "MLM15879678",
"seller_id": "61597650",
"user_selection": {
"label_values": [
{
"label": "Marca",
"value_name": "Jeep",
"values": [
{
"attribute_id": "BRAND",
"value_id": "60395"
}
]
},
{
"label": "Modelo",
"value_name": "Grand Cherokee",
"values": [
{
"attribute_id": "CAR_AND_VAN_MODEL",
"value_id": "8236932"
}
]
},
{
"label": "Año",
"value_name": "1998",
"values": [
{
"attribute_id": "YEAR",
"value_id": "60500"
}
]
},
{
"label": "Versión",
"value_name": "Limited - SUV 4 Puertas",
"values": [
{
"attribute_id": "CAR_AND_VAN_SUBMODEL",
"value_id": "8238101"
},
{
"attribute_id": "CAR_AND_VAN_BODY_TYPE",
"value_id": "8183114"
},
{
"attribute_id": "BODY_DOORS_NUMBER",
"value_id": "8239302"
}
]
},
{
"label": "Mecánica",
"value_name": "5.2L V8 Gasolina Aspirado Caja Automática 4 Marchas - Tracción RWD",
"values": [
{
"attribute_id": "CAR_AND_VAN_ENGINE",
"value_id": "8753511"
},
{
"attribute_id": "ASPIRATION",
"value_id": "8183201"
},
{
"attribute_id": "TRANSMISSION_CONTROL_TYPE",
"value_id": "8183158"
},
{
"attribute_id": "TRANSMISSION_SPEEDS_NUMBER",
"value_id": "8239312"
},
{
"attribute_id": "DRIVE_TYPE",
"value_id": "8182651"
}
]
}
]
},
"compatibility_status": {
"compatibility": "CONFIRMED",
"compatibility_id": "bec40b54-c7de-1ad2-a7e2-00a5e34376a4"
},
"compatibility_deleted": true,
"date_created": "2023-08-31T20:08:41Z",
"date_updated": "2023-08-31T22:37:39Z"
}
Ordem com reclamação quando o comprador não seleccionou um veículo durante a compra do produto.
Chamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/compats-snapshots/orders/2000006372967424Response:
{
"item_id": "MLM2038068352",
"seller_id": "186880296",
"compatibility_status": {
"compatibility": "NO_USER_SELECTION",
"note": "We don't have the compatibility information for this order. The user made the order without completing the widget. ",
"restrictions": []
},
"date_created": "2023-08-23T12:30:57Z"
}
Ordem com reclamação em que, antes da compra, foi confirmado ao comprador que o produto selecionado “Não era compatível” com o item (compatibility_status.compatibility = INCOMPATIBLE).
Chamada:
curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/compats-snapshots/orders/2000006372967684Response:
{
"item_id": "MLM693204319",
"seller_id": "56493851",
"compatibility_status": {
"compatibility": "INCOMPATIBLE"
},
"compatibility_deleted": true,
"date_created": "2023-08-25T14:45:48Z"
}
Os campos indicam:
- compatibility_id: identificador de compatibilidade selecionado durante a compra.
- product_id: ID do veículo selecionado antes da compra.
- user_selection: detalhes dos filtros selecionados pelo comprador no momento da compra.
- compatibility_status.compatibility:
- CONFIRMED: indica que foi confirmado ao comprador que o veículo selecionado era compatível com o item comprado.
- INCOMPATIBLE: indica que foi confirmado ao comprador que o veículo selecionado não era compatível com o item comprado.
- compatibility_deleted::
- “true” indica que a compatibilidade para o veículo selecionado pelo comprador já foi eliminada pelo item no momento da consulta.
Possíveis erros:
| Error_code | Mensagem de erro | Descrição |
|---|---|---|
| 400 | Compatibility snapshot for order with id $ORDER_ID not found. | Ordem não é válida. |
| 401 | Invalid access token. | Access token inválido. |
| 403 | The compatibility snapshot can only be retrieved for orders with claims. | A ordem não tem qualquer reivindicação associada. |
| 403 | Caller must be the seller of the item. | Está sendo feita uma tentativa de consultar a ordem de um vendedor que não corresponde ao token de acesso fornecido. |
Próximo: Referências de domínios, produtos e atributos para Autopeças.