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.

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

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"
        },
        {
            "rule_id": "INT"
        }
    ]
}

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 e INT .
  • 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 automação, possíveis status:
  • ACTIVE
  • PAUSED
• item_rule: Regra de automação, as regras disponíveis são:
• rule_id: Regra de automação
• “INT_EXT” (Concorrência interna e externa simultânea).
• “INT”(Concorrência interna apenas, no caso de ser de catálogo apenas esse tipo de publicações será considerado).
• title: Nome da regra selecionada. A única disponível é “Preço para ganhar vendas”
• description: Descrição da regra selecionada.
• min_price: Precio mínimo seteado a la automatización.
• max_price: Precio máximo seteado a la automatización.

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": []
}