Para evoluir a plataforma VTEX com relação a mudanças em pedidos, estamos lançando a Alterar pedido (Beta), uma solução muito mais completa, versátil e que proporciona uma nova experiência no Admin VTEX.

Após as interações entre nosso time de engenharia e clientes e parceiros que já aderiram à versão beta, elaboramos este conteúdo com boas práticas de implementação e dúvidas frequentes. O objetivo é que os próximos clientes e parceiros disponham deste material de apoio ao começarem a usar a Alterar pedido (Beta).

Este artigo está organizado da seguinte forma:

• Adaptação para diferentes casos de uso
• Alterações no request body das requisições
• Requisições com erros e falhas
• Perguntas frequentes (FAQ)

As seções a seguir apresentam os principais casos de uso da Alterar pedido (Beta) e respectivas recomendações.

A Alterar pedido (Beta) utiliza novos templates para emails transacionais (Message Center), de forma a contemplar as funcionalidades inovadoras da solução.

Para customizar um template de email no Admin VTEX, copie e cole o link abaixo no seu navegador, substituindo o {accountName} pelo nome de conta da sua loja, e depois clique em enter:

https://{accountName}.myvtex.com/admin/message-center/#/templates/vtexcommerce-order-changed-v2

Para as lojas que utilizam a versão atual para alterar pedidos via Admin VTEX, após a instalação da nova solução pela equipe da VTEX, as interfaces atualizadas estarão imediatamente disponíveis para você usar a Alterar pedido (Beta) via Admin VTEX. Isso inclui novo gerenciamento e comunicação do Minha conta e de templates de emails transacionais.

Para as lojas que utilizam nossas APIs, é necessário que a implementação na integração obedeça à nova arquitetura da funcionalidade.

Na Alterar pedido (Beta), o endpoint Create order change funciona de forma assíncrona e o usuário ou integração que faz a requisição recebe da plataforma um requestId, que é um identificador único para acompanhar a operação para alterar o pedido. Este identificador posteriormente será utilizado em determinados endpoints. Todos os endpoints da Alterar pedido (Beta) são:

• Create order change
• Preview order change
• Get order change details
• Get order change history
• Retry order change
• Cancel order change
• Update Change order settings
• Get Change order settings

Após alterar o pedido usando o endpoint Create order change, para novas requisições aos endpoints da Alterar pedido (Beta) existem as seguintes alternativas para o integrador:

• Polling: complexidade baixa.
• Preview: complexidade média.

A tabela a seguir apresenta cada uma:

Tipo de fluxo	Funcionamento
Polling Complexidade baixa	Após a operação de alteração do pedido é gerado um código único que identifica a alteração do pedido, o requestId, e com ele você pode acompanhar os detalhes da requisição pelo endpoint Get order change details. Neste endpoint, após a alteração do pedido, a propriedade do response body finished passa a ter o valor true. Além disso, o Get order change details também pode ser utilizado para obter informações sobre falhas e erros que resultaram no eventual cancelamento da operação de alteração do pedido, como será visto na seção Requisições com erros e falhas.
Preview Complexidade média	Antes de fazer uma requisição ao Create order change, a integração tem a opção de fazer uma visualização prévia que vai resultar em um response body exatamente igual à requisição de alteração. Para isso, basta usar o mesmo request body no requisição ao endpoint Preview order change. Essa pré-visualização é uma simulação da alteração e não gera efeitos reais de alteração no pedido. O uso do Preview order change é útil para você obter os valores totais associados à alteração do pedido sendo feita, e também para validar os detalhes da requisição com um request body válido. Após uma resposta de sucesso 200 OK para obter uma visualização prévia da alteração, a integração pode prosseguir com a requisição a Create order change para alterar o pedido. Posteriormente, sua integração pode ser adaptada a cenários como: Criação otimista: os dados das validações obtidas com a simulação da alteração cobrem a maior parte dos cenários de sucesso 200 OK. Implementação do Polling: mencionado anteriormente.

A Alterar pedido (Beta) mantém alguns atributos da solução anterior, mas há outros que foram criados ou transformados, tanto em nomenclatura quanto em funcionamento. As principais mudanças foram organizadas da seguinte forma:

• Valores manuais
• Adição e remoção de itens
• Atributos de itens obrigatórios e opcionais
• Responsabilidade do usuário na automatização do sistema

• Antes: os campos discountValue e incrementValue definiam o valor da alteração sendo feita no pedido, respectivamente para o decréscimo ou o acréscimo de um valor. O usuário calculava o valor da alteração e o resultado era acrescido ou decrescido no valor total do pedido por meio destes campos.

  Exemplo: em um pedido de 100 reais a ser alterado para se adicionar um item de 50 reais, o usuário enviava o incrementValue com valor de 50 reais e o sistema calculava o total do pedido como 150 reais. Se o usuário quisesse dar ao cliente um desconto de 30 reais na alteração, ele precisava enviar o discountValue com valor de 30 reais para que o total do pedido fosse 120 reais.

• Agora: os novos campos manualDiscountValue e manualIncrementValue definem valores manuais adicionais sendo acrescidos ou decrescidos do custo total do pedido independentemente das alterações sendo feitas. Como o sistema calcula de forma automática o resultado das alterações (considerando o preço e condições do fechamento da compra), o usuário pode realizar o acréscimo ou decréscimo de valores usando os campos mencionados.

  Exemplo: em um pedido de 100 reais a ser alterado para se adicionar um item de 50 reais, ao se adicionar o item, o sistema calcula automaticamente o acréscimo do valor de 50 reais e o usuário não precisa enviá-lo manualmente, sendo o resultado total do pedido igual a 150 reais. Caso o usuário queira dar ao cliente um desconto de 30 reais na alteração, basta enviar o campo manualDiscountValue com valor de 30 reais que o total do pedido será 120 reais.

• Antes: os atributos utilizados para adicionar e remover itens do pedido eram os arrays itemsAdded e itemsRemoved e eles continham objetos de itens com os campos id, price e quantity.
• Agora: os atributos para adicionar e remover itens do pedido são os objetos add e remove e eles contém um novo nível que define um objeto para cada item por meio do array items.

Exemplo de remoção de itens na Alterar pedido (Beta):

Os itens no request body das requisições precisam de menos atributos obrigatórios do que antes, são eles: id e quantity. Os demais atributos são obtidos a partir do pedido ou do sistema Catálogo.

Há outros campos que podem ser modificados para sobrepor as informações de um item sendo alterado, caso seja necessário adicionar ou alterar itens existentes. Os campos opcionais são price, unitMultiplier e measurementUnit. Quaisquer outros campos enviados na requisição são desconsiderados pelo sistema.

• Antes: era responsabilidade do usuário calcular o valor a ser alterado no pedido. Ele enviava esse valor pelo atributo discountValue ou incrementValue, dependendo se era um acréscimo ou decréscimo no preço.
• Agora: o sistema é responsável pelo fornecimento de informações sobre os itens e calcula, de forma automática, o valor final do pedido com a alteração. Ou seja, o usuário agora informa o mínimo necessário e não mais calcula o valor final do pedido, o que diminui cenários de erros.

Quando ocorre erro ou falha na requisição da Alterar pedido (Beta), as informações sobre o processamento podem ser obtidas pelo endpoint Get order change details pelo atributo logs.

Exemplo de logs com erro de processamento:

Para cada falha no sistema (erros não tratados), o sistema realiza de forma automática novas tentativas de processamento. Se as novas tentativas não funcionarem, a requisição de alteração será cancelada e o motivo do erro pode ser encontrado usando a Get order change details pelo atributo cancellationData.

Caso a origem do erro seja por inobservância do usuário às regras de validação da requisição, a operação será cancelada automaticamente e não serão feitas novas tentativas de processamento. Neste caso, o motivo do erro é também comunicado pelo cancellationData.

Exemplo do objeto cancellationData: a mudança de preço solicitada na requisição ultrapassa o valor limite configurado para cancelamento de pedidos.

Esta seção reúne dúvidas comuns de clientes e parceiros que utilizam a Alterar pedido (Beta):

1 - Como sobrescrevo o preço de um item específico?

2 - Como descubro e mudo o valor total do pedido antes que ele seja alterado?

3 - Preciso informar o preço do frete ou ele é recalculado automaticamente?

4 - Como funcionam as promoções na Alterar pedidos (Beta)?

5 - O que devo fazer quando a requisição resulta no status canceling ou canceled?

Para sobrescrever o preço de um item específico, é possível aplicar um valor manual ao item ao mesmo tempo em que sua quantidade é alterada.

No endpoint Create order change, o atributo price tem a mesma função do fluxo de fechamento de pedidos e se refere ao preço nominal do item. Por exemplo, em um pedido com um item pesável, como uma maçã, o price é referente ao preço do quilo da maçã.

Exemplo de sobrescrita de preço em um item pesável:

O endpoint Preview order change permite ao usuário simular qual será o resultado da alteração do pedido a ser feita com o Create order change, pois utiliza o mesmo request body e fornece o mesmo response body, mas sem alterar o pedido. O totalChangeValue é o atributo que informa qual o valor total sendo alterado no pedido, seja para um valor maior (ex: taxa ou adição de itens) ou menor (ex: redução manual do valor ou remoção de itens).

Se for desejável que a integração manipule a variação no valor do pedido alterado, é possível utilizar o mesmo request body utilizado na Preview order change e utilizá-lo em uma requisição ao Create order change, manipulando para mais ou para menos, respectivamente, o valor dos campos manualIncrementValue e manualDiscountValue.

Quando há mudanças na quantidade, tamanho ou peso de itens, o custo do frete é recalculado automaticamente e o valor é somado ao novo valor total do pedido.

A regra de cálculo do novo custo do frete obedece às mesmas condições aplicadas no fechamento do pedido.

A alteração do pedido aplica de forma automática as mesmas promoções e taxas que eram válidas para os itens no fechamento da compra, mas somente replicando as condições de então. Novas promoções e taxas não são recalculadas nas condições do pedido alterado.

Exemplo: em uma loja havia uma promoção "leve 3 itens e pague 2", mas o cliente comprou somente 2 itens e não foi elegível para o desconto. Quando o cliente solicitou que ao seu pedido fosse adicionado mais um item, ele passou a adquirir 3 itens, mas a promoção não seria aplicada, pois não constava no pedido original.

É possível informar a promoção de um item no momento da alteração do pedido. Isso é feito manualmente com a Create order change pelo atributo priceTags. Este já é o comportamento padrão da plataforma.

Exemplo de item com promoções aplicadas no pedido original:

Neste exemplo, a tag utilizada foi de desconto manual DISCOUNT@MANUALPRICE. A equivalente para taxas manuais seria a TAX@MANUALPRICE. O endpoint Create order change também permite utilizar o atributo priceTag de uma promoção existente e mudar seu valor na alteração do pedido.

Os status canceling e canceled significam que a alteração do pedido não foi processada corretamente, as mudanças não foram aplicadas ao pedido e o usuário pode desconsiderar a tentativa. As falhas e erros podem ocorrer por:

• Inobservância do usuário às regras de validação da requisição.
• Número excedido de tentativas de reprocessamento automático pelo sistema.
• Outras falhas de processamento do sistema.

A recomendação geral é investigar a origem do erro e checar o request body sendo enviado pelo endpoint Create order change ou Preview order change. Mais informações na seção Requisições com erros e falhas.

Help Center	Developer Portal
Alterar pedidos via Admin VTEX: Como funciona a Alterar pedido (Beta) Como alterar pedidos (Beta)	Alterar pedidos via API: Create order change Preview order change Get order change details Get order change history Retry order change Cancel order change