Developers

Documentação do Mercado Livre

Confira todas as informações necessárias sobre as APIs Mercado Livre.

Última atualização em 12/08/2024

Gerenciar automatizações

As automatizações de preços no MercadoLibre são ferramentas fundamentais para os vendedores que desejam manter seus produtos competitivos e maximizar suas margens de lucro. Essas ferramentas permitem ajustar os preços dos produtos de forma dinâmica e estratégica em resposta a diversas variáveis do mercado. A seguir, detalhamos as funcionalidades disponíveis para gerenciar automatizações.

Importante:

Se a publicação tiver mudanças de preços fora da automatização de preços, isso fará com que a automatização caia imediatamente, a fim de evitar inconsistências e desatualizações de preços.

Obter regras disponíveis para um item

Para um item específico, é possível obter a lista de regras disponíveis que podem ser utilizadas para uma automatização de preços, é necessário realizar um GET para o recurso /pricing-automation/items/{{itemId}}/rules

Regras

rule_id	Título	Descrição
“INT_EXT”	Preço para ganhar vendas	Seu preço será ajustado ao preço mais baixo entre publicações semelhantes do Mercado Livre e outras fora do site.

Pré condições para obter as regras disponíveis para um item

Deve consultar sobre um item existente
O item deve ser passível de automatização

Chamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' 
https://api.mercadolibre.com/pricing-automation/items/$ITEM_ID/rules

Exemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' 
https://api.mercadolibre.com/pricing-automation/items/MLA12345678/rules

Resposta:

{
    "item_id": "MLA123456",
    "rules": [
        {
            "rule_id": "INT_EXT",
        }
    ]
}

Campos da resposta

A resposta de um GET para o recurso /pricing-automation/items/{{itemId}}/rules fornecerá os seguintes parâmetros:

item_id: Identificador do item
rules: Lista de regras disponíveis para um item. Atualmente só pode ser INT_EXT
- rule_id: Regra de automatização.

Possíveis erros ao obter as regras disponíveis

Ao obter as regras disponíveis para um item, é possível que você encontre os seguintes erros. É crucial que você entenda a causa de cada um e saiba como corrigi-los, para lidar eficientemente com a situação. Aqui você tem a informação necessária para identificar e resolver esses problemas.

Resource not found:

{
    "error": "item_not_found",
      "message" : "Item with id [MLA123456] not found",
    "status": 404,
      "cause": []
}

Usuário não autorizado:

{
    "error": "user_not_authorized",
    "message": "User is not allowed to automate items",
    "status": 412,
    "cause": []
}

Não é possível automatizar o item:

{          
    "error": "item_not_automatizable",
    "message" : "Item with id [MLA123456] has no rules available",
    "status": 412,
    "cause": []
}

Não foi possível processar a estratégia definida:

{           
    "error": "unprocessable_get_strategies",
    "message" : "Error calling retrieve item strategies service",
    "status": 422,
    "cause": []
}

Não autorizado:

{
    "code": "unauthorized",
    "message": "invalid access token"
}

Atribuir nova automatização de preços

Para atribuir uma nova automatização de preços, é necessário realizar um POST para o recurso /pricing-automation/items/{{itemId}}/automation

Pré condições para atribuir uma automatização

A regra deve ser aplicada a um item existente
Deve ter um preço mínimo obrigatório
Os preços não podem ser absurdos (Máximo e Mínimo)
Deve cumprir as condições de Criação

Chamada:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' 

{
    "rule_id" : "INT_EXT", 
    "min_price": 100000,
    "max_price": 1000000
}
https://api.mercadolibre.com/pricing-automation/items/$ITEM_ID/automation

Exemplo:

curl -X POST -H 'Authorization: Bearer $ACCESS_TOKEN' 

{
    "rule_id" : "INT_EXT", 
    "min_price": 100000,
    "max_price": 1000000
}
https://api.mercadolibre.com/pricing-automation/items/MLA12345678/automation

Resposta:

{
    "item_id": "MLA123456",
    "status": "ACTIVE",
    "item_rule": {
        "rule_id": "INT_EXT",
    },
    "min_price": 100000,
    "max_price": 1000000
}

Campos da resposta

A resposta de um POST para o recurso pricing-automation/items/$ITEM_ID/automation fornecerá os seguintes parâmetros

item_id: Identificador do item
status: Estado da automatização, possíveis status:
- ACTIVE
- PAUSED
item_rule: Regra de automatização, atualmente a única regra disponível é “INT_EXT” (Competição interna e externa simultânea)
- rule_id: Regra de automatização.
min_price: Preço mínimo definido para a automatização.
max_price: Preço máximo definido para a automatização.

Possíveis erros ao atribuir uma automatização

Ao atribuir uma nova automatização, é possível que você encontre os seguintes erros. É crucial que você entenda a causa de cada um e saiba como corrigi-los, para lidar eficientemente com a situação. Aqui você tem a informação necessária para identificar e resolver esses problemas.

Resource bad req::

{
    "error": "argument_not_valid",
    "message": "rule_id must not be null",
    "status": 400,
    "cause": [
        {
            "code": "rule_id_not_null",
            "message": "Rule identifier is required"
        }
    ]
}

Resource not found:

{
    "error": "item_not_found",
      "message" : "Item with id [MLA123456] not found",
    "status": 404
}

Usuário não autorizado:

{
    "error": "user_not_authorized",
    "message": "User is not allowed to automate items",
    "status": 412
}

Automação já criada:

{     "error": "automation_already_created",
      "message" : "Automation already created",
    "status": 412
}

Automação não permitida:

{          
   "error": "automation_operation_not_allowed",
   "message" : "Cannot perform [assign automation] for item with id [MLA123456]",
   "status": 412
}

A regra estabelecida não pode ser processada:

{    
     "error": "unprocessable_set_rule",
     "message" : "Error calling rule assignment service",
     "status": 422
}

Não autorizado

{
    "code": "unauthorized",
    "message": "invalid access token"
}

Obter automatização de preços existente

Para obter uma automatização de um item, é necessário consultar o recurso /pricing-automation/items/{{itemId}}/automation

Pré condições para obter uma automatização

Deve corresponder a um item existente
Deve ser uma automatização já atribuída
Deve cumprir as condições de Obtenção

Chamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' 
https://api.mercadolibre.com/pricing-automation/items/$ITEM_ID/automation

Exemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/pricing-automation/items/MLA12345678/automation

Resposta:

{
    "item_id": "MLA123456",
    "status": "ACTIVE | PAUSED" 
    "item_rule": {
        "rule_id": "INT_EXT",
    },
    "min_price": 100000,
    "max_price": 1000000,
    "status_detail": {
        "cause": "ITEM_NO_ACTIVE| PROMO|COMPETITORS",
        "message": "Item paused message"
     }
}

Campos da resposta

A resposta de um GET para o recurso /pricing-automation/items/{{itemId}}/automation fornecerá os seguintes parâmetros:

item_id: Identificador do item
status: Estado da automatização, possíveis status:
- ACTIVE
- PAUSED
item_rule:
- rule_id: Regra de automatização.
min_price: Preço mínimo definido para a automatização.
max_price: Preço máximo definido para a automatização.
status_detail: Estado da automatização pausado por alguma dessas causas:
- COMPETITORS
- PROMO
- ITEM_NO_ACTIVE
cause: causa da automatização pausada
message: mensagem detalhando qual das causas pausou a automatização

Possíveis erros ao obter uma automatização

Ao consultar uma automatização, é possível que você encontre os seguintes erros. É crucial que você entenda a causa de cada um e saiba como corrigi-los, para lidar eficientemente com a situação. Aqui você tem a informação necessária para identificar e resolver esses problemas.

Resource not found:

{
    "error": "item_not_found",
      "message" :"Item with id [MLA123456] not found",
    "status": 404,
            "cause": []
}

Automação não encontrada:

{
    "error": "automation_not_found",
      "message" : "Automation not found for item with id [MLA123456]",
    "status": 404,
            "cause": []
}

Usuário não autorizado:

{
    "error": "user_not_authorized",
    "message": "User is not allowed to automate items",
    "status": 412,
    "cause": []
}

Automação não permitida:

{          
   "error": "automation_operation_not_allowed",
   "message" : "Cannot perform [get automation] for item with id [MLA123456]",
   "status": 412,
   "cause": []
}

A regra estabelecida não pode ser processada:

{    
     "error": "unprocessable_get_rule",
     "message" : "Error calling rule assignment service",
     "status": 422
}

Não autorizado:

{
    "code": "unauthorized",
    "message": "invalid access token"
}

Atualizar uma automatização de preços

Para atualizar uma regra de automatização de um item que está atribuída, é necessário realizar um PUT para o recurso /pricing-automation/items/{{itemId}}/automation

Pré condições para atualizar uma automatização

A regra deve ser aplicada a um item existente.
É obrigatório que tenha um preço mínimo.
Os preços não podem ser absurdos (Máximo e Mínimo).
Deve cumprir as condições de Modificação.

Chamada:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' 
{
    "rule_id" : "INT_EXT",
    "min_price": 100000,
    "max_price": 1000000
}
https://api.mercadolibre.com/pricing-automation/items/$ITEM_ID/automation

Exemplo:

curl -X PUT -H 'Authorization: Bearer $ACCESS_TOKEN' 
{
    "rule_id" : "INT_EXT",
    "min_price": 100000,
    "max_price": 1000000
}
https://api.mercadolibre.com/pricing-automation/items/MLA12345678/automation

Resposta:

{
 "item_id": "MLA123456",
 "status": "ACTIVE",
 "item_rule": {
           "rule_id": "INT_EXT",
             },
 "min_price": 100000,
 "max_price": 1000000
}

Campos da resposta

A resposta de um PUT para o recurso /pricing-automation/items/{{itemId}}/automation fornecerá os seguintes parâmetros:

item_id: Identificador do item
status: Estado da automatização, possíveis status:
- ACTIVE
- PAUSED
item_rule:
- rule_id: Regra de automatização.
min_price: Preço mínimo definido para a automatização.
max_price: Preço máximo definido para a automatização.

Possíveis erros ao atualizar uma automatização

Ao atualizar uma automatização, é possível que você encontre os seguintes erros. É crucial que você entenda a causa de cada um e saiba como corrigi-los, para lidar eficientemente com a situação. Aqui você tem a informação necessária para identificar e resolver esses problemas.

Response bad req:

{
    "error": "argument_not_valid",
    "message": "rule_id must not be null",
    "status": 400,
    "cause": [
        {
            "code": "rule_id_not_null",
            "message": "Rule identifier is required"
        }
    ]
}

Resource not found:

{
    "error": "item_not_found",
      "message" : "Item with id [MLA123456] not found",
    "status": 404,
      "cause": []
}

Usuário não autorizado:

{
    "error": "user_not_authorized",
    "message": "User is not allowed to automate items",
    "status": 412,
    "cause": []
}

Automação não permitida:

{          
   "error": "automation_operation_not_allowed",
   "message" : "Cannot perform [assign automation] for item with id [MLA123456]",
   "status": 412,
   "cause": []
}

A regra estabelecida não pode ser processada:

{   "error": "unprocessable_set_rule",
    "message" : "Error calling rule retrieve service",
    "status": 422,
    "cause": []
}

Não autorizado:

{
    "code": "unauthorized",
    "message": "invalid access token"
}

Eliminar uma automatização de preços

Para eliminar uma regra de automatização de um item que está atribuída, é necessário realizar um DELETE para o recurso /pricing-automation/items/{{itemId}}/automation

Pré condições para eliminar uma automatização

A regra deve ser eliminada de um item existente
Deve eliminar uma regra existente

Chamada:

curl -X DELETE -H 'Authorization: Bearer $ACCESS_TOKEN' 
https://api.mercadolibre.com/pricing-automation/items/$ITEM_ID/automation

Exemplo:

curl -X DELETE -H 'Authorization: Bearer $ACCESS_TOKEN' 
https://api.mercadolibre.com/pricing-automation/items/MLA12345678/automation

Possíveis erros ao eliminar uma automatização

Ao eliminar uma automatização, é possível que você encontre os seguintes erros. É crucial que você entenda a causa de cada um e saiba como corrigi-los, para lidar eficientemente com a situação. Aqui você tem a informação necessária para identificar e resolver esses problemas.

Resource not found:

{
    "error": "item_not_found",
      "message" : "Item with id [MLA123456] not found",
    "status": 404,
      "cause": []
}

Automação não encontrada:

{
    "error": "automation_not_found",
            "message" : "Automation not found for item with id [MLA123456]",
    "status": 404,
            "cause": []
}

Usuário no autorizado:

{
    "error": "user_not_authorized",
    "message": "User is not allowed to automate items",
    "status": 412,
    "cause": []
}

Automação não permitida:

{          
   "error": "automation_operation_not_allowed",
   "message" : "Cannot perform [delete automation] for item with id [MLA123456]",
   "status": 412,
   "cause": []
}

A regra estabelecida não pode ser processada:

{   "error": "unprocessable_delete_rule",
    "message" : "Error calling rule retrieve service",
    "status": 422,
    "cause": []
}

Não autorizado:

{
    "code": "unauthorized",
    "message": "invalid access token"
}

Obter histórico de preços para um item automatizado

Para um item específico, é possível obter o histórico das modificações de preços gerado pelas automatizações aplicadas, é necessário realizar um GET para o recurso /pricing-automation/items/{{itemId}}/price/history

Pré condições para obter o histórico de preços para um item

Deve consultar sobre um item existente

Parâmetros:

Query params	Obrigatoriedade	Detalhe value
days	Opcional	por padrão é 30
page	Opcional	por padrão é 0
size	Opcional	por padrão é 10

Chamada:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' 
https://api.mercadolibre.com/pricing-automation/items/$ITEM_ID/price/history

Exemplo:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' 
https://api.mercadolibre.com/pricing-automation/items/MLA12345678/price/history

Resposta:

{
    "result_code": 200,
    "result": {
        "content": [
            {
                "date_time": "2024-07-12T15:26:15Z",
                "percent_change": 0,
                "usd_price": 0,
                "deal_id": "68719c01-0566-4728-adef-2701750be2d0",
                "price": 120,
                "event": "CurrentStrategyConfirmed",
                "strategy_type": "automation_min_price"
            }
        ],
        "pageable": {
            "offset": 0,
            "page_number": 0,
            "page_size": 1
        },
        "total_elements": 9,
        "total_pages": 9,
        "size": 1,
        "number_of_elements": 1,
        "empty": false
    },
    "result_message": "OK"
}

Campos da resposta

A resposta de um GET para o recurso /pricing-automation/items/{{itemId}}/price/history fornecerá os seguintes parâmetros:

result_code: Código HTTP de resposta à requisição recebida.
result: Contém o conteúdo da resposta e as informações de paginação.
- content: Lista de objetos que contêm os detalhes do histórico de preços.
  - date_time: Data que indica a data e hora em que a mudança de preço foi registrada.
  - percent_change: Variação percentual do preço em relação ao valor anterior.
  - usd_price: Preço em USD do item. Pode ser 0 se não estiver disponível.
  - deal_id: Identificador único associado à transação ou evento de preço.
  - price: Preço do item na moeda local no momento do evento.
  - event: Nome do evento que causou a mudança de preço.
  - strategy_type: Tipo de estratégia utilizada para o ajuste do preço.
- pageable: Informações sobre a paginação dos resultados.
  - offset: Deslocamento desde o início da lista de resultados.
  - page_number: Número da página atual na paginação.
  - page_size: Número máximo de elementos por página.
- total_elements: Número total de elementos disponíveis na resposta.
- total_pages: Número total de páginas disponíveis de acordo com o tamanho da página.
- size: Número de elementos presentes na página atual.
- number_of_elements: Número de elementos na página atual.
- empty: Indicador se a resposta contém ou não dados.
result_message: Mensagem que fornece uma descrição do status da solicitação.

Possíveis erros ao obter o histórico de preço de um item

Ao obter o histórico de mudança de preços para um item, é possível que você encontre os seguintes erros. É crucial que você entenda a causa de cada um e saiba como corrigi-los, para lidar eficientemente com a situação. Aqui você tem a informação necessária para identificar e resolver esses problemas.

Response bad req:

{
    "message": "size must be numeric",
    "error": "bad_request",
    "status": 400,
    "cause": []
}

Não autorizado:

{
    "code": "unauthorized",
    "message": "invalid access token"
}

Item consultado não foi automatizado:

{
    "message": "Item with id [MLM20974486577] not found",
    "error": "item_not_found",
    "status": 404,
    "cause": []
}

O item não pertence ao vendedor:

{
    "message": "User is not item owner",
    "error": "user_not_authorized",
    "status": 412,
    "cause": []
}

Erro ao recuperar itens do histórico de preços

{
    "message": "Error calling retrieve price history item service",
    "error": "unprocessable_get_price_history",
    "status": 422,
    "cause": []
}